Skip to main content

Deploying Updates

Deployments happen automatically when you push to the master branch on GitHub. A webhook listener on the server detects the push and runs the full deployment pipeline — no SSH required.

Simply push your changes to master:

git add .
git commit -m "Update documentation"
git push origin master

That's it. Within a few minutes, the site will be rebuilt and live at https://docs.rhinogroup.com.

How It Works​

GitHub Push → Webhook POST → docs.rhinogroup.com/webhook
    → Node.js listener validates HMAC signature
    → Filters for master branch pushes only
    → Spawns update-docs.sh (all 7 steps)

Monitoring Auto-Deploy​

Check the webhook log on the server:

ssh docsrhinogroup@vps3
tail -f ~/webhook.log

The log shows accepted/rejected requests, deploy start/finish, and exit codes.

Manual Deployment (Fallback)​

If the webhook is down or you need to trigger a deploy manually:

Prerequisites:

  • SSH access to vps3 as docsrhinogroup user
# 1. SSH into the server
ssh docsrhinogroup@vps3

# 2. Run the deployment script
update-docs.sh

Full Pinecone Reindex​

To force a complete vector reindex (all ~200 pages, takes 20-30 minutes):

update-docs.sh --reindex-all

Deployment Steps​

The update-docs.sh script performs these steps automatically:

StepActionPurpose
1git stashSave any uncommitted local changes
2git pullFetch latest changes from GitHub master branch
3npm run buildBuild the Docusaurus static site
4cp -R build/* /home/docsrhinogroup/public_html/Deploy built files to web root
5Typesense scraperRe-index search with updated content
6Pinecone indexingUpdate vector embeddings (optional, if API key set)
7Cloudflare cache purgeClear CDN cache (optional, if credentials set)

Logging: All deployment activity is logged to ~/update-docs.log

What Happens During Each Step​

Step 1-2: Git Operations​

  • Stashes any local changes (preserves server-side edits if needed)
  • Pulls the latest documentation from the master branch
  • Important: Changes must be committed and pushed to GitHub first

Step 3: Build​

  • Compiles all markdown and React pages into static HTML/CSS/JS in build/
  • Runs the docsearch-meta-plugin postBuild hook, which injects client_tag and site_tag meta tags
  • Reports any broken links as warnings
  • Auto-retries with npm install if build fails

Step 4: Deploy​

  • Clears the web root (preserving .htaccess and .htpasswd)
  • Copies all built files to /home/docsrhinogroup/public_html/

Step 5: Typesense Search Indexing​

  • Starts the DocSearch scraper Docker container
  • Scrapes the built site's HTML and indexes into the rhino-docs collection
  • Picks up docsearch:client_tag and docsearch:site_tag meta attributes as faceted fields
  • Skipped if: Docker is not available

Step 6: Pinecone Vector Indexing​

  • Detects changed documentation pages using git diff
  • Generates vector embeddings for new/modified pages
  • Updates the Pinecone vector database for semantic search
  • Skipped if: PINECONE_API_KEY not set in .env file

Step 7: Cloudflare Cache Purge​

  • Purges all cached content from Cloudflare CDN
  • Ensures users see the latest documentation immediately
  • Skipped if: CLOUDFLARE_ZONE_ID or CLOUDFLARE_API_TOKEN not set in .env file

Environment Configuration​

Optional features require environment variables in /home/docsrhinogroup/docs/.env:

# Pinecone vector database (optional)
PINECONE_API_KEY=your_api_key_here

# Cloudflare cache purging (optional)
CLOUDFLARE_ZONE_ID=aaed4ff0f779214003efc38da6f6576a
CLOUDFLARE_API_TOKEN=your_token_here

See .env.example for the template.

Verifying a Deployment​

After deployment:

  1. Open https://docs.rhinogroup.com and verify the homepage loads
  2. Navigate to any recently changed page to confirm updates are live
  3. Test search — try filtering by client and site
  4. Check that new clients/sites appear in the search dropdown filters
  5. Review ~/update-docs.log for any warnings or errors

Troubleshooting​

Build Fails​

  • Check ~/update-docs.log for the error message
  • The script automatically runs npm install and retries once
  • Verify the commit builds successfully locally: npm run build

Search Not Updated​

  • Check if Docker is running: docker ps
  • Verify Typesense container is up: docker ps | grep typesense
  • Review scraper logs in the deployment output

Cloudflare Cache Not Cleared​

  • Verify .env file has both CLOUDFLARE_ZONE_ID and CLOUDFLARE_API_TOKEN
  • Check the Cloudflare API token has Zone.Cache Purge permission
  • Review the purge API response in the deployment log

Manual Deployment (Legacy)​

If both the webhook and update-docs.sh are unavailable, you can deploy step-by-step:

cd /home/docsrhinogroup/docs
git pull
npm install
npm run build
cp -R build/* /home/docsrhinogroup/public_html/
./typesense/scrape.sh

Note: This skips Pinecone indexing and Cloudflare cache purging.

Webhook Troubleshooting​

Webhook Not Triggering​

  1. Check the service is running: 
    sudo systemctl status docs-webhook
  2. Verify GitHub delivery succeeded: GitHub → Repository → Settings → Webhooks → Recent Deliveries
  3. Check the webhook log for errors: 
    tail -20 ~/webhook.log

Restarting the Webhook Service​

sudo systemctl restart docs-webhook
sudo systemctl status docs-webhook

Deploy Stuck (Lockfile)​

If a deploy crashes mid-run, the lockfile may prevent new deploys:

rm /tmp/docs-deploy.lock

Rollback​

If a deployment causes issues:

cd /home/docsrhinogroup/docs
git log --oneline -5          # Find the previous good commit
git checkout <commit-hash>
update-docs.sh                 # Re-deploy the previous version

Or revert the commit on GitHub and run update-docs.sh again.