Skip to main content

Deploying Your Documentation

This guide explains how to publish this documentation site on your own custom domain — for example docs.yourdomain.com.

Before You Deploy​

First, update the site URL in the configuration file. Open apps/docs/docusaurus.config.ts and change:

url: 'https://docs.yourdomain.com',

Replace yourdomain.com with your actual domain name.

Option 1 — Deploy With Vercel (Recommended)​

Vercel is the simplest way to deploy and keep the documentation up to date automatically. It's free for most use cases and redeploys automatically every time you push an update.

Steps​

1. Push the code to GitHub Make sure your repository (or monorepo) is pushed to a GitHub account.

2. Connect to Vercel

  • Go to vercel.com and sign in with your GitHub account
  • Click Add New Project and select your repository

3. Configure the project settings

  • Set Root Directory to apps/docs
  • Vercel auto-detects Docusaurus and sets the correct build settings

4. Add your custom domain

  • In your Vercel project, go to Settings → Domains
  • Click Add Domain and enter docs.yourdomain.com
  • Vercel will provide the DNS records you need to add

5. Update your DNS

  • Log in to your domain registrar (e.g., GoDaddy, Namecheap, Cloudflare)
  • Add a CNAME record:
    • Name / Host: docs
    • Value / Points to: cname.vercel-dns.com
  • DNS changes typically take effect within a few minutes to a few hours

Once configured, every time you push updated documentation files, Vercel automatically rebuilds and republishes the site.

Option 2 — Self-Hosted With nginx​

If you prefer to host the documentation on your own server (a VPS or dedicated server), follow these steps.

Step 1 — Build the Site​

On your local machine or CI/CD pipeline:

cd apps/docs
pnpm install
pnpm run build

This generates a build/ folder containing the complete static site (HTML, CSS, and JavaScript).

Step 2 — Upload to Your Server​

Copy the contents of the build/ folder to your server. Using rsync:

rsync -avz apps/docs/build/ user@yourserver.com:/var/www/docs/

Step 3 — Configure nginx​

Create a new nginx configuration file at /etc/nginx/sites-available/docs:

server {
    listen 80;
    server_name docs.yourdomain.com;

    root /var/www/docs;
    index index.html;

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

Enable the site:

sudo ln -s /etc/nginx/sites-available/docs /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 4 — Enable HTTPS​

Use Certbot for a free SSL certificate:

sudo certbot --nginx -d docs.yourdomain.com

Step 5 — Point Your DNS​

Add a DNS record at your domain registrar:

  • Type: A
  • Name / Host: docs
  • Value: Your server's public IP address

Option 3 — Deploy With Netlify​

Netlify works very similarly to Vercel:

  1. Connect your GitHub repository at netlify.com
  2. Set the Base directory to apps/docs
  3. Set Build command to pnpm run build
  4. Set Publish directory to apps/docs/build
  5. Add your custom domain in the Netlify domain settings

Protecting Internal Developer Documentation​

Docusaurus does not include built-in authentication, so it is not possible to password-protect a section of the site natively. For internal developer documentation that requires access control, we recommend one of these approaches:

Cloudflare Access (Free — Recommended)​

If your domain uses Cloudflare DNS, you can use Cloudflare Access to restrict specific URL paths (e.g., /dev/*) to authorized email addresses only. This is free for up to 50 users and requires no changes to the documentation code.

nginx Basic Auth (Self-Hosted)​

If you're using the nginx option, add HTTP Basic Authentication to a specific path:

location /dev {
    auth_basic "Developer Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    try_files $uri $uri/ /index.html;
}

Generate the password file with:

sudo htpasswd -c /etc/nginx/.htpasswd devuser

Separate Deployment​

Keep developer documentation in a completely separate repository or deployment, accessible only from specific IP addresses or via a private URL.

Running the Documentation Locally​

To preview the documentation on your own computer before publishing:

cd apps/docs
pnpm install
pnpm run start

Open http://localhost:3000 in your browser.

To preview the Spanish version:

pnpm run start -- --locale es

Updating the Documentation​

To update any page:

  1. Edit the relevant Markdown file in apps/docs/docs/
  2. For Spanish translations, edit the corresponding file in apps/docs/i18n/es/docusaurus-plugin-content-docs/current/
  3. Preview locally with pnpm run start
  4. Push your changes — the site redeploys automatically if using Vercel or Netlify