How to build a headless CMS with Strapi and Astro

Traditional content management systems like WordPress bundle your content, templates and frontend code into a single application. This creates performance bottlenecks and limits how you can deliver content across different platforms.

You will build a headless CMS setup using Strapi to manage content and Astro to generate your frontend. This separation gives you faster page loads, better security and the flexibility to use your content anywhere. We will deploy both applications on a VPS using Docker containers.

Create your Docker Compose configuration

Docker Compose lets you define both Strapi and its database in a single configuration file. This approach keeps your applications isolated and makes deployment repeatable.

1. Connect to your VPS.
   Use SSH to access your server: ssh username@your-server-ip replacing username with your actual username and your-server-ip with your VPS IP address.
2. Create a project directory.
   Run mkdir ~/astro-strapi && cd ~/astro-strapi to create and enter a new directory for your project files.
3. Create the Docker Compose file.
   Run nano docker-compose.yml to open a new file in the text editor.
4. Add the configuration.
   Copy the following configuration into the file. This defines Strapi, PostgreSQL database and persistent storage volumes.

File: docker-compose.yml

version: '3'
services:
  strapi:
    image: strapi/strapi:latest
    environment:
      DATABASE_CLIENT: postgres
      DATABASE_HOST: db
      DATABASE_PORT: 5432
      DATABASE_NAME: strapi
      DATABASE_USERNAME: strapi
      DATABASE_PASSWORD: your-secure-password
    ports:
      - '1337:1337'
    volumes:
      - ./app:/srv/app
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      POSTGRES_DB: strapi
      POSTGRES_USER: strapi
      POSTGRES_PASSWORD: your-secure-password
    volumes:
      - ./data:/var/lib/postgresql/data

5. Replace the database password.
   Change your-secure-password in both locations to a strong password. This secures your database connection.
6. Save and exit.
   Press Ctrl+X, then Y, then Enter to save the file and close the editor.
7. Start the containers.
   Run docker-compose up -d to download the images and start both services in the background.

Strapi is now running on port 1337. The database stores its data in the ./data directory, which persists between container restarts.

Configure Strapi and create content

You need to complete Strapi’s initial setup and create a content type before you can build your Astro frontend. This establishes the API structure that Astro will consume.

1. Access the Strapi admin.
   Open your browser and navigate to http://your-server-ip:1337/admin replacing your-server-ip with your VPS IP address.
2. Create an admin account.
   Fill in the registration form with your details. This creates your first admin user and completes the setup.
3. Create a content type.
   In the left sidebar, click Content-Type Builder, then click Create new collection type. Name it “Article” and add fields for title (text), content (rich text) and published date.
4. Make the API public.
   Navigate to Settings → Users & Permissions plugin → Roles → Public. Under Article, enable find and findOne permissions. This allows Astro to fetch your content without authentication.
5. Add sample content.
   Click Content Manager in the sidebar, select Article, then click Create new entry. Add a title and content, then click Save and Publish.

Your content is now available via Strapi’s REST API at http://your-server-ip:1337/api/articles. Astro will fetch from this endpoint to build your pages.

Build and deploy your Astro frontend

Astro fetches content from Strapi during the build process and generates static HTML files. You will create a basic site structure and configure it to pull from your Strapi API.

1. Create an Astro project.
   In your project directory, run npm create astro@latest frontend and follow the prompts. Choose the “Empty” template when asked.
2. Install dependencies.
   Run cd frontend && npm install to install the required packages.
3. Create a page template.
   Run nano src/pages/index.astro and add code to fetch and display your articles from the Strapi API.
4. Configure the API URL.
   Create a .env file with STRAPI_URL=http://your-server-ip:1337 to store your Strapi endpoint. Replace your-server-ip with your actual IP address.
5. Build the site.
   Run npm run build to generate static files in the dist directory. Astro fetches your content and creates HTML pages at build time.
6. Serve the files.
   Copy the contents of dist to your web server directory or configure Nginx to serve them. Your static site is now live.

When you publish new content in Strapi, rebuild your Astro site to regenerate the static files with updated content. Your setup now separates content management from frontend delivery.

Wrapping up

You have deployed a modern website using Strapi for content management and Astro for frontend delivery. Your setup separates content from presentation, generates static HTML for fast loading and keeps your admin interface isolated from your public site.

Monitor your Docker containers with docker-compose logs and set up automated backups of the ./data directory. Our VPS hosting gives you full control over your server environment for custom deployments like this.

If you run into any trouble, get in touch and our team will be happy to help.