Deploy the Docs Site

This runbook covers everything needed to host ygc-docs.redtechitsolutions.com so that ./scripts/deploy.sh works on first run.

Target stack: Ubuntu + Apache + LetsEncrypt, matching the tbpc18-docs deployment style.

:::note Current ygc-docs server uses root SSH The documented standard below (and on tbpc18-docs) uses an unprivileged ubuntu user with the doc root chown'd to ubuntu:www-data. The current ygc-docs.redtechitsolutions.com host instead deploys as root for operational simplicity — see scripts/deploy.sh SSH_TARGET. The runbook below remains the recommended pattern for new docs hosts; if you stand up a new server, prefer the unprivileged-user approach. :::

1. DNS

Point an A record at the production server's public IP:

ygc-docs.redtechitsolutions.com.   A   <server-public-ip>

Verify resolution before continuing:

dig +short ygc-docs.redtechitsolutions.com
# should return the server IP

If the domain resolves but you can't SSH in yet, that's fine — the cert step below needs DNS to resolve, not SSH.

2. SSH access

The deploy script uses port 1005 as ubuntu@ygc-docs.redtechitsolutions.com.

On the server:

• Confirm sshd_config includes Port 1005 (or change to the port you want and update scripts/deploy.sh accordingly)
• Add the operator's public key to /home/ubuntu/.ssh/authorized_keys

On your laptop, test:

ssh -p 1005 ubuntu@ygc-docs.redtechitsolutions.com 'echo ok'

3. Install Apache and required modules

sudo apt update
sudo apt install -y apache2

# Modules needed by the vhost:
sudo a2enmod ssl headers rewrite
sudo systemctl reload apache2

ssl for HTTPS, headers for Cache-Control rules, rewrite for the catch-all fallback.

4. Create the doc root with correct permissions

The deploy script rsyncs into /var/www/ygc17-docs/build as the ubuntu user. Apache reads it as www-data. Set ownership and group bits so ubuntu can write and www-data can read:

sudo mkdir -p /var/www/ygc17-docs/build
sudo chown -R ubuntu:www-data /var/www/ygc17-docs/build
sudo chmod -R g+rwX /var/www/ygc17-docs/build
sudo find /var/www/ygc17-docs/build -type d -exec chmod g+s {} +

The g+s setgid bit on directories ensures any new files inherit the www-data group, so subsequent rsync deploys don't need sudo.

5. Issue the LetsEncrypt certificate

Install Certbot:

sudo apt install -y certbot python3-certbot-apache

Issue the cert:

sudo certbot certonly --apache -d ygc-docs.redtechitsolutions.com

Choose the standalone or apache plugin per your preference. The cert lands at:

/etc/letsencrypt/live/ygc-docs.redtechitsolutions.com/fullchain.pem
/etc/letsencrypt/live/ygc-docs.redtechitsolutions.com/privkey.pem

These exact paths are referenced in the vhost config below. Auto-renewal is set up by certbot's systemd timer.

6. Deploy the Apache vhost

Copy the vhost from the repo to the server:

# From your laptop
scp -P 1005 \
    /Users/jsalinga/odoo/odoo17/custom/ygc17/ygc17-docs/scripts/ygc-docs.redtechitsolutions.com.conf \
    ubuntu@ygc-docs.redtechitsolutions.com:/tmp/

# On the server
sudo mv /tmp/ygc-docs.redtechitsolutions.com.conf /etc/apache2/sites-available/
sudo a2ensite ygc-docs.redtechitsolutions.com
sudo apache2ctl configtest
sudo systemctl reload apache2

configtest should report Syntax OK before you reload.

7. First deploy

From your laptop, in the docs site root:

cd /Users/jsalinga/odoo/odoo17/custom/ygc17/ygc17-docs
./scripts/deploy.sh

This:

1. Runs npm run build locally
2. rsyncs build/ to ubuntu@ygc-docs.redtechitsolutions.com:/var/www/ygc17-docs/build/

Open https://ygc-docs.redtechitsolutions.com/ to verify.

8. Subsequent deploys

Just ./scripts/deploy.sh — that's the entire workflow. The --delete rsync flag ensures removed pages don't linger on the server.

Troubleshooting

Symptom	Likely cause	Fix
Could not resolve host on first SSH	DNS hasn't propagated	Wait or set /etc/hosts entry temporarily
Permission denied (publickey)	SSH key not in authorized_keys	Add the operator's pubkey on the server
404 on every page after deploy	FallbackResource directive missing	Confirm mod_rewrite enabled and vhost has the directive
Mixed-content warnings	Site loaded over HTTP	The :80 vhost should permanent-redirect to :443; confirm both VirtualHost blocks are enabled
Cert renewal fails	Apache wasn't reloaded after install	sudo certbot renew --dry-run to test; add a cron/post-hook
403 Forbidden	Doc-root owner/perm issue	Re-run the chown/chmod from step 4
Stale assets after deploy	Browser cached aggressively	Hard refresh; vhost already sets immutable cache headers on hashed assets, no-cache on HTML

Server prerequisites checklist

Quick sanity check before first deploy:

• DNS A record resolves to the server
• SSH on port 1005 works as ubuntu
• apache2, mod_ssl, mod_headers, mod_rewrite installed and enabled
• /var/www/ygc17-docs/build/ exists with correct ownership (ubuntu:www-data, group setgid)
• LetsEncrypt cert issued for the domain
• Vhost dropped in sites-available/, enabled, and apache2ctl configtest is clean
• apache2 reloaded