Deploy Docusaurus with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it ideal for serving a Docusaurus documentation site with minimal infrastructure.

This guide walks you through deploying a pre-built Docusaurus static site using Nginx as the web server, with automatic HTTPS. Since Docusaurus generates static HTML at build time, the deployment is lightweight and fast.

Prerequisites

• A VPS with at least 1 vCPU, 512 MB RAM, and 5 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., docs.yourdomain.com) with DNS A record pointing to your server's IP
• A pre-built Docusaurus site (the build output directory) or a Git repository containing your Docusaurus project

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  docusaurus:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ../files/docusaurus-build:/usr/share/nginx/html:ro
      - ../files/docusaurus-nginx.conf:/etc/nginx/conf.d/default.conf:ro
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:80/ || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

Create the Nginx configuration file at ../files/docusaurus-nginx.conf (upload via Dokploy's file manager or SSH):

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript image/svg+xml;
}

Note: Docusaurus is a static site generator — you build it locally or in CI and deploy the output. Upload your Docusaurus build/ directory contents to ../files/docusaurus-build via SCP, Dokploy's file manager, or a CI pipeline. For automated builds, consider using Dokploy's Git deployment with a custom Dockerfile that builds the site.

Environment Variables

No environment variables are required for serving a static Docusaurus site. The Nginx container serves files directly from the mounted volume.

If you're using a custom Dockerfile to build Docusaurus from source, you may need:

Variable	Purpose	Example
DOCUSAURUS_URL	Base URL for the site	https://docs.yourdomain.com

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/docusaurus-build — The Docusaurus static build output (HTML, CSS, JS)
• ../files/docusaurus-nginx.conf — Custom Nginx configuration for SPA routing and caching

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/docusaurus) because Dokploy may clean them during redeployment.

To update the site, rebuild Docusaurus locally and upload the new build/ contents to the same volume path. The Nginx container will serve the updated files immediately.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., docs.yourdomain.com)
3. Set the container port to 80
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to the Nginx container.

Verifying the Deployment

1. Upload your Docusaurus build output to ../files/docusaurus-build on the server
2. Upload the Nginx config to ../files/docusaurus-nginx.conf
3. In Dokploy, go to your project's Deployments tab and click Deploy
4. Check the Logs tab for the docusaurus service. Look for Nginx startup messages
5. Open https://docs.yourdomain.com in your browser — you should see your Docusaurus site
6. Test navigation between pages to confirm the SPA fallback routing works

Troubleshooting

Blank page or 403 Forbidden Ensure the ../files/docusaurus-build directory contains the Docusaurus build output (an index.html at the root). If the directory is empty or missing, Nginx returns an error. Build your Docusaurus site with npm run build and upload the build/ contents.

Page refresh returns 404 on sub-routes The Nginx config must include try_files $uri $uri/ /index.html to handle client-side routing. Ensure the docusaurus-nginx.conf file is correctly mounted and contains the SPA fallback rule.

CSS/JS not loading or broken styles Check that the Docusaurus baseUrl configuration matches your deployment path. If serving from the domain root, baseUrl should be /. Verify files exist in the build directory with the expected paths.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about Docusaurus in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Docusaurus.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.