> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primo.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Self-host Primo on your own infrastructure or wait for Primo Cloud.

Primo offers two installation options: self-hosting for full control over your infrastructure, or our upcoming managed cloud platform.

<Tabs>
  <Tab title="Self-Hosted">
    ## Self-Hosted Installation

    Run Primo on your own infrastructure for complete control. Ideal for teams with specific security, compliance, or customization requirements.

    Primo's architecture is intentionally simple—a single monolithic application with a SQLite database. This means self-hosting requires minimal operational overhead. No complex microservices, separate database servers, or distributed systems to manage.

    <Warning>
      **Persistent Storage Required**: Primo stores uses a SQLite database that requires persistent disk storage. It will NOT work on some serverless platforms like Vercel, Netlify, or Cloudflare Pages.
    </Warning>

    ### Choose Your Hosting Path

    Select the approach that matches your technical comfort level and requirements. All options can run Primo for **\$5-7/month**.

    <Tip>
      **New to self-hosting?** Start with [Railway](https://railway.com/?referralCode=RCPU7k) or [Fly.io](https://fly.io) for the easiest setup. If you need more control or lower costs at scale, consider VPS hosting.
    </Tip>

    <Tabs>
      <Tab title="Managed Platforms (Easiest)">
        **What you get:** One-click deployment, automatic SSL, managed infrastructure. No server management required.

        **[Railway](https://railway.com/deploy/primo?referralCode=RCPU7k)** (Recommended)

        * Click deploy button, done in 5 minutes
        * From \$5/month with persistent volumes included
        * Automatic deployments and SSL certificates
        * **What you need:** Just a Railway account

        **[Fly.io](https://fly.io)**

        * Free tier includes 3GB persistent volume
        * Global edge deployment
        * Good for testing or small production sites
        * **What you need:** [Fly.io](https://fly.io) account + CLI installation
      </Tab>

      <Tab title="VPS Hosting (Most Control)">
        **What you get:** Full server access, complete customization, lowest cost at scale. Manage your own infrastructure.

        **[Hetzner Cloud](https://cloud.hetzner.com)**

        * From €4/month (CX22: 2 vCPU, 4GB RAM, 40GB disk)
        * Best price/performance ratio
        * European data centers (GDPR-friendly)
        * **What you need:** Docker, SSH, and Linux knowledge

        **[DigitalOcean](https://www.digitalocean.com)**

        * From \$6/month for basic droplets
        * Excellent documentation and tutorials
        * One-click Docker droplet available
        * **What you need:** Basic Docker and command line knowledge
      </Tab>
    </Tabs>

    <Info>
      **Quick start:** If you just want to try Primo, click the [Railway deploy button](https://railway.com/deploy/primo?referralCode=RCPU7k) for instant setup. For production sites or when you need full control, choose the VPS path.
    </Info>

    <Accordion title="Local Development (Optional)">
      For contributing to Primo or testing locally:

      * **devenv** ([install here](https://devenv.sh/)) or **Dev Container** compatible environment (VS Code)
      * **Git**

      **Local Development Steps:**

      <Steps>
        <Step title="Clone the repository">
          ```bash theme={null}
          git clone https://github.com/primocms/primo.git
          cd primo
          ```
        </Step>

        <Step title="Open the devenv shell">
          ```bash theme={null}
          devenv shell
          ```

          <Info>
            If you have configured direnvto automatically open the devenv shell, you may ignore this step.
          </Info>
        </Step>

        <Step title="Install dependencies">
          ```bash theme={null}
          npm install
          ```
        </Step>

        <Step title="Build the application">
          ```bash theme={null}
          npm run build
          ```

          <Info>
            Initial build is required before starting the dev server.
          </Info>
        </Step>

        <Step title="Start development server">
          ```bash theme={null}
          npm run dev
          ```
        </Step>

        <Step title="Access the application">
          * Main app (dev): [http://localhost:5173](http://localhost:5173)
          * Built app: [http://localhost:8090](http://localhost:8090)
          * PocketBase Admin: [http://localhost:8090/\_](http://localhost:8090/_)
        </Step>
      </Steps>

      <Warning>
        Local development is for testing only. All code and content is stored in local database under `pb_data` directory.
      </Warning>
    </Accordion>

    ### Manual Deployment (VPS & Custom Infrastructure)

    <Info>
      **Using [Railway](https://railway.com/?referralCode=RCPU7k) or [Fly.io](https://fly.io)?** You can skip this section - those platforms handle Docker deployment automatically.
    </Info>

    For VPS hosting (Hetzner, DigitalOcean, etc.) or custom infrastructure, deploy Primo as a Docker container using Docker Compose or by running Docker commands directly. See the [PocketBase production deployment guide](https://pocketbase.io/docs/going-to-production/) for additional information.

    <Steps>
      <Step title="Point your domain to the server">
        Configure your DNS to point your domain name to the server where you'll host Primo.
      </Step>

      <Step title="Prepare Docker deployment">
        Use Docker Compose (recommended) or run Docker commands directly. Use `ghcr.io/primocms/primo:latest` as the image.

        **Required volume**: Add a volume for the path `/app/pb_data`. This is where all files and the database will be stored.

        **Optional environment variables** (only take effect on first start):

        * `PRIMO_APP_URL` - Sets base URL used for generating links in the backend (e.g., emails)
        * `PRIMO_SUPERUSER_EMAIL` + `PRIMO_SUPERUSER_PASSWORD` - Creates initial superuser account for accessing PocketBase dashboard.
        * `PRIMO_USER_EMAIL` + `PRIMO_USER_PASSWORD` - Creates initial user account for accessing Primo.

        <CodeGroup>
          ```yaml compose.yaml theme={null}
          services:
            primo:
              image: ghcr.io/primocms/primo:latest
              restart: always
              ports:
                - 8080:8080
              volumes:
                - primo-data:/app/pb_data
              # Optional environment variables:
              # environment:
              #   - PRIMO_APP_URL=https://example.com
              #   - PRIMO_SUPERUSER_EMAIL=admin@example.com
              #   - PRIMO_SUPERUSER_PASSWORD=secure-password
              #   - PRIMO_USER_EMAIL=user@example.com
              #   - PRIMO_USER_PASSWORD=secure-password

          volumes:
            primo-data:
          ```

          ```bash docker run theme={null}
          docker run -d \
            --name primo \
            --restart always \
            -p 8080:8080 \
            -v primo-data:/app/pb_data \
            ghcr.io/primocms/primo:latest
          ```
        </CodeGroup>
      </Step>

      <Step title="Complete setup">
        Navigate to your domain name to complete setup. Setup only starts if a superuser was not created using environment variables in the previous step.
      </Step>

      <Step title="Configure PocketBase">
        Configure PocketBase settings by navigating to `https://your-domain.com/_/` (replace with your domain).
      </Step>

      <Step title="Create your first site">
        Create your first site by navigating to `https://your-domain.com/admin` (replace with your domain). Note that the site is created using the domain name used to access the CMS.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cloud">
    ## Primo Cloud

    <Note>
      **Coming Soon** — Primo Cloud is currently in development. We recommend [self-hosting](#self-hosted) for now, which takes just a few minutes with platforms like Railway or Fly.io.
    </Note>

    Primo Cloud will be a fully managed hosting solution that handles all the infrastructure for you—no installation, setup, or server management required.

    ### Planned Features

    * Dedicated server instance for your account
    * Automatic SSL certificates
    * Global CDN hosting
    * Automatic deployments when you publish changes
    * Built-in collaboration tools
    * Direct support for setup and troubleshooting
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="lightbulb" href="/getting-started/core-concepts">
    Learn the fundamental concepts behind Primo
  </Card>

  <Card title="Quickstart" icon="bolt" href="/getting-started/quickstart">
    Build your first site in minutes
  </Card>
</CardGroup>