Cockpit CMS Tutorial Part 1: Introduction, Setting Up Your First Users , API Users, Roles & Content Models

Once upon a time, the almighty Monolithic CMS was the bane of the Internet. You had a publishing backend and the frontend of the web application neatly and tightly integrated into one solid unit. In high-level programming circles it would be described as 'the Model-View-Controller baked into a single app/unit'. But then came the newer demands of splitting the publishing backend while allowing any kind of frontend to communicate with it by fetching data. This made the concept of the Application Programming Interface (API) to gain traction. Hence the idea of the Headless CMS. Cockpit CMS is a Headless CMS. It only gives you an administration area where you can publish any kind of content and the ability to expose API routes to this content to the outside world. It is up to you as a developer to choose how you will display this content whether via Android, iOS, Python's Jinja, PHP's Laravel or embedded Raspberry Pi units.

To give a simple example: WordPress is a monolithic CMS; its admin area is tightly integrated to its frontend. You can only view the blog posts published by admins by creating WordPress PHP themes. Cockpit CMS has nothing like 'Cockpit templates'. It only has an admin area for publishing content. While both a written in PHP they are targeted at different audiences.

Now let's dive in to the tutorial. We'll be using Cockpit CMS' Mongolite/SQLite for this tutorial just to escape setting up a MySQL database (you can read our blog on why SQLite is a good alternative for small websites).

1. Download the source. Place it in your server of choice then unzip it.
2. Head over to the installer link. Follow the steps and Cockpit CMS will be set up.
3. Login with the initial Admin password that Cockpit has given you.
4. First go to http://<your website>/system then 'Roles'. Let's add a role called 'Public API' as an example. Select the permissions that this role will have. Note that these permissions apply to the API endpoints exposed by Cockpit CMS. For our 'Public API' role just choose the 'Read' capability only that are under the 'Content' accordion section. We only need the API to consume the content published on the backend but if you want more permissions you can check the appropriate checkboxes in the other sections. This role will be very critical in defining what each system user can do via the API's exposed by Cockpit CMS. 

5. Now, let's create our first user. Go to http://<your website>/system then 'Users' and create one. Let's create a user called 'Public API User' as an example. Select the 'Public API' role we created above. Under the 'API Key' section generate an API key for this user. Then click 'Create'. Your new user in mint condition has been created.

6. Now we will need to create a model that we will publish content to. Head over to 'Content'. Cockpit has 3 unique kinds of content models:
    - Singleton: Content that can only be a one piece and nothing more.
    - Collection: Multiple pieces of content. Think of this as collection of 'pages', 'blog posts', 'articles' etc.
    - Tree: Multiple pieces of content arranged in hierarchical order from parents to children and so on.
7. Let's use the 'Collection' content for this. Click on 'Collection' that is under 'Create Model'. 
8. In the new page, give it a name, display name, group name and info/description then select the form fields that will go with this content. Click 'Create Model' and, voila, you have just created your first content section. NOTE: The 'Name' is very critical here. It will be used in accessing the content model via an API endpoint. Let's give the name 'Blog' to this new collection. 

9. Finally, let's test to see if our 'Public API User' works. Head over to 'API & Security'. There are 2 ways Cockpit CMS' exposes content to the outside world: via REST API and via GraphQL. You can use any. We will use the REST API since it is the most common and well known. Click on 'Playground' and you have a overlay section with the various API endpoints presented to you. Since we only gave permissions to the 'Content' section to the 'Public API' role we will use the 'Content' API endpoints. Click on one endpoint like the 'GET - /content/item/{model}'. Fill in the details in the form on the right together with the 'Name' you gave your content model above. Then click 'Send Request'. For those who have used Bruno/Postman this is not new. If the response returned is successful - usually Status 200 - then it means your user and API are working correctly.

Congrats! You have created your first headless CMS instance using Cockpit CMS. In the next tutorial we will add some content to the 'Blog' model you created above.