Operations & Deployment Manual

Branching Strategy

• ai-tabs: The active development and production branch. All changes are committed here and deployed to the remote host.
• main: Archived/Backup branch. Do not commit new features here.

1. Directory Structure

Location	Path	Description
Local Root	<local_root>	Development workspace.
Remote Root	/var/www/html	Production web root on <remote_host>.
Docs Source	.../documentation	Docusaurus source code.
Docs Build	.../documentation/build	Static HTML output.
Remote Docs	/var/www/html/documentation	Production docs directory.

2. WordPress Deployment

To sync the entire site or specific plugins to production:

Full Site Sync:

rsync -avz --progress <local_root>/ root@<remote_host>:/var/www/html/

Plugin Sync (posts-ai-chatboxes):

rsync -avz --progress \
  <local_root>/wp-content/plugins/posts-ai-chatboxes/ \
  root@<remote_host>:/var/www/html/wp-content/plugins/posts-ai-chatboxes/

3. Documentation Deployment

The documentation site is a static build generated by Docusaurus.

Step 1: Clean & Build It is critical to clean the cache to prevent stale artifacts.

cd documentation
npm run clear
npm run index
npm run build

Step 2: Sync to Remote Important: Use --delete to remove outdated pages (e.g., deleted tutorials). Exclude custom utility scripts (reindex_docs.php, ip_debug.php) to prevent them from being deleted.

rsync -avz --delete \
  --exclude 'reindex_docs.php' \
  --exclude 'ip_debug.php' \
  --exclude 'whereami.php' \
  -e "ssh -o StrictHostKeyChecking=no" \
  <local_root>/documentation/build/ \
  root@<remote_host>:/var/www/html/documentation/

Remote Reindexing

After deployment, the semantic search index (llms.txt) must be regenerated on the remote server if the RAG agent needs to read the latest docs.

• Endpoint: https://vania-novikau.me/documentation/reindex_docs.php?key=vania_docs_secret
• VS Code Task: Run task "Reindex Remote Docs".
• Agent Tool: The RAG agent can call reindex_documentation to trigger this autonomously.

4. RAG Stack Deployment

The semantic search infrastructure runs on Docker.

Requirements

• Docker & Docker Compose (V2) installed on the remote server.
• OpenAI API Key: Required for the embedding indexer.

Architecture

• Service: rag-service (Python/FastMCP)
• Database: rag-postgres (pgvector)
• Port: Host 8082 (Container 8080)

Deployment Steps

1. Sync Code:

   rsync -avz --exclude 'node_modules' --exclude '.env' <local_root>/ root@<remote_host>:/var/www/html/

2. Start Services:

   Note: The remote server uses docker compose (Command compose v2), not docker-compose.

   ssh root@<remote_host>
   cd /var/www/html
   docker compose up -d --build

3. Run Indexer: The indexer needs the API key to generate embeddings.

   export OPENAI_API_KEY=sk-your-key-here
   docker compose run -e OPENAI_API_KEY=$OPENAI_API_KEY --rm rag-service python indexer.py

5. Documentation Docker Container

Architecture

The documentation site is served by a Docker container (html-docusaurus-1) running nginx.

Detail	Value
Container Name	html-docusaurus-1
Host Port	3002 → Container 80
Nginx Root	/usr/share/nginx/html/
Bind Mount	❌ None — files are baked at image build time

Critical: Because there is no bind mount, rsync deploys to the host filesystem are not picked up by the live container. Files must be copied in separately (see below) or the container must be rebuilt.

Current Deploy Workaround (docker cp)

After running rsync, push the new build into the running container:

ssh root@<remote_host> "\
  docker cp /var/www/html/documentation/docs/. html-docusaurus-1:/usr/share/nginx/html/documentation/docs/ && \
  docker cp /var/www/html/documentation/assets/. html-docusaurus-1:/usr/share/nginx/html/documentation/assets/ && \
  docker cp /var/www/html/documentation/llms.txt html-docusaurus-1:/usr/share/nginx/html/documentation/llms.txt && \
  docker cp /var/www/html/documentation/llms-full.txt html-docusaurus-1:/usr/share/nginx/html/documentation/llms-full.txt"

Note: This hotfix is non-persistent — changes revert on container restart/rebuild.

Permanent Fix (Recommended)

Add a bind mount to docker-compose.yml:

docusaurus:
  ...
  volumes:
    - /var/www/html/documentation/build:/usr/share/nginx/html/documentation

With this, rsync deploys to the host are immediately reflected in the container with no restart needed.

6. Access Control Configuration (Review)

The documentation directory is protected by .htaccess rules on the remote server.

File Location: /var/www/html/documentation/.htaccess

Current Rules:

• Allow: Tailscale IPs (100.x.x.x)
• Allow: IPv6 Mapped Tailscale (::ffff:100.x.x.x)
• Allow: User VPN Subnet (156.146.61.0/24)
• Allow: AWS / external exception subnet (15.160.115.0/24)
• Deny: All others (HTTP 403)

Update Command: To update the whitelist, SSH into the server and edit the .htaccess file directly or overwrite it using cat and ssh.