Skip to main content

Setup From Scratch

This guide walks through provisioning a new VPS to host the Rhino Group Documentation Platform, including nginx, Typesense via Docker, HTTP Basic Auth, and the Docusaurus site.

Prerequisites​

  • A Linux VPS (Ubuntu 22.04+ or similar) with a public IP address
  • SSH access with sudo privileges
  • A domain record pointing to the instance
  • Node.js ≥ 20 installed
  • Docker and Docker Compose installed

Phase 1 — System Essentials​

# Update the system
sudo apt update && sudo apt upgrade -y

# Install nginx, Node.js 20+, Git, and Docker
sudo apt install -y nginx git curl
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Phase 2 — Clone the Repository​

cd ~
git clone https://github.com/Rhino-Group/docs.git
cd docs
npm install

Phase 3 — Start Typesense​

Typesense runs via Docker on the same server.

cd ~/docs/typesense

# Create the .env file from the template
cp .env.example .env
# Edit .env and set a strong TYPESENSE_API_KEY
nano .env

# Start Typesense
docker compose up -d typesense

# Verify health
curl http://localhost:8108/health
# Expected: {"ok":true}

Phase 4 — Build the Site​

cd ~/docs
npm run build
Swap Memory

If the build hangs or crashes on a small instance, add 1 GB of swap:

sudo dd if=/dev/zero of=/swapfile bs=128M count=8
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Phase 5 — Configure nginx​

Set up HTTP Basic Auth credentials​

sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd admin
# Enter a strong password when prompted

Create site config​

sudo nano /etc/nginx/sites-available/docs
server {
    listen 80;
    server_name your-docs-domain.com;

    # Typesense proxy — exempt from Basic Auth
    location /typesense/ {
        proxy_pass http://localhost:8108/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Docusaurus static files — Basic Auth required
    location / {
        auth_basic "Private Documentation";
        auth_basic_user_file /etc/nginx/.htpasswd;
        root /var/www/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
}
sudo ln -s /etc/nginx/sites-available/docs /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl restart nginx

Phase 6 — Deploy the Site​

sudo mkdir -p /var/www/html
sudo chown -R $USER:$USER /var/www/html
rm -rf /var/www/html/*
cp -R ~/docs/build/* /var/www/html/

Phase 7 — Run the Search Scraper​

cd ~/docs
./typesense/scrape.sh

This indexes all built HTML pages into Typesense with client and site faceted fields.

Phase 8 — Verify​

  1. Open the domain in a browser — a login dialog should appear.
  2. Log in with the credentials set in Phase 5.
  3. The homepage should load with client cards.
  4. Use the search bar to confirm Typesense is returning results.
  5. Test the client/site dropdown filters in the search modal.

Ongoing Updates​

After initial setup, deploy changes by:

cd ~/docs
git pull
npm install
npm run build
cp -R build/* /var/www/html/
./typesense/scrape.sh

See Deploying Updates for a full walkthrough.