From ceb8e28b7419e88f5b05867a9eb9488278717315 Mon Sep 17 00:00:00 2001
From: Davide Scaini <davide.scaini@alumni.cern>
Date: Fri, 10 Apr 2026 15:06:31 +0200
Subject: [PATCH] update deployment instructions

---
 docs/deployment/vps.md | 162 ++++++++++++++++++++++++-----------------
 1 file changed, 94 insertions(+), 68 deletions(-)

diff --git a/docs/deployment/vps.md b/docs/deployment/vps.md
index 570e214..326f39a 100644
--- a/docs/deployment/vps.md
+++ b/docs/deployment/vps.md
@@ -16,7 +16,7 @@ Code is deployed directly from your laptop via `git push` — no GitHub required
 
 ```bash
 apt update && apt upgrade -y
-apt install -y git curl nginx certbot python3-certbot-nginx sqlite3
+apt install -y git curl nginx certbot python3-certbot-nginx sqlite3 rsync
 ```
 
 **Node.js 20 LTS** (the Debian package is too old):
@@ -52,38 +52,88 @@ REPO=/opt/bincio-repo.git
 DEPLOY=/opt/bincio
 DATA=/var/bincio/data
 
-echo "--- Checking out code ---"
-git --work-tree=$DEPLOY --git-dir=$REPO checkout -f
+while read oldrev newrev refname; do
+  echo "--- Checking out $refname ---"
+  git --work-tree=$DEPLOY --git-dir=$REPO checkout -f $newrev
 
-echo "--- Syncing Python deps ---"
-cd $DEPLOY
-~/.local/bin/uv sync
+  echo "--- Syncing Python deps ---"
+  cd $DEPLOY
+  ~/.local/bin/uv sync --extra serve --extra strava
 
-echo "--- Syncing JS deps ---"
-cd $DEPLOY/site
-npm install --silent
+  echo "--- Syncing JS deps ---"
+  cd $DEPLOY/site
+  npm install --silent
 
-echo "--- Building site ---"
-cd $DEPLOY
-~/.local/bin/uv run bincio render --data-dir $DATA --site-dir $DEPLOY/site
+  echo "--- Building site ---"
+  cd $DEPLOY
+  ~/.local/bin/uv run bincio render --data-dir $DATA --site-dir $DEPLOY/site
 
-echo "--- Copying dist to webroot ---"
-rsync -a --delete $DEPLOY/site/dist/ /var/www/bincio/
+  echo "--- Copying dist to webroot ---"
+  rsync -a --delete $DEPLOY/site/dist/ /var/www/bincio/
 
-echo "--- Restarting API ---"
-systemctl restart bincio
+  echo "--- Restarting API ---"
+  systemctl restart bincio
 
-echo "--- Done ---"
+  echo "--- Done ---"
+done
 ```
 
 ```bash
 chmod +x /opt/bincio-repo.git/hooks/post-receive
-mkdir -p /var/www/bincio
+mkdir -p /var/www/bincio /var/bincio/data /var/bincio/sources
 ```
 
 ---
 
-## 3. First deploy from your laptop
+## 3. systemd service
+
+The hook restarts the `bincio` service on every deploy, so it must exist before the first push.
+
+Create `/etc/bincio/secrets.env`:
+
+```bash
+mkdir -p /etc/bincio
+chmod 700 /etc/bincio
+cat > /etc/bincio/secrets.env <<EOF
+STRAVA_CLIENT_ID=your_client_id
+STRAVA_CLIENT_SECRET=your_client_secret
+EOF
+chmod 600 /etc/bincio/secrets.env
+```
+
+Create `/etc/systemd/system/bincio.service`:
+
+```ini
+[Unit]
+Description=BincioActivity API
+After=network.target
+
+[Service]
+WorkingDirectory=/opt/bincio
+ExecStart=/root/.local/bin/uv run bincio serve \
+    --data-dir /var/bincio/data \
+    --site-dir /opt/bincio/site \
+    --host 127.0.0.1 \
+    --port 4041
+EnvironmentFile=/etc/bincio/secrets.env
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+systemctl daemon-reload
+systemctl enable --now bincio
+systemctl status bincio
+```
+
+---
+
+## 4. First deploy from your laptop
 
 Add the VPS as a git remote (run this locally, once):
 
@@ -106,7 +156,7 @@ git push vps mobile_app   # deploy any branch directly
 
 ---
 
-## 4. Initialise the instance
+## 5. Initialise the instance
 
 ```bash
 cd /opt/bincio
@@ -128,7 +178,7 @@ sqlite3 /var/bincio/data/instance.db \
 
 ---
 
-## 5. Prepare your own activities
+## 6. Prepare your own activities
 
 Source files (raw GPX/FIT) live separately from the BAS output:
 
@@ -168,52 +218,6 @@ ssh root@<vps> "cd /opt/bincio && \
 
 ---
 
-## 6. systemd service
-
-Create `/etc/systemd/system/bincio.service`:
-
-```ini
-[Unit]
-Description=BincioActivity API
-After=network.target
-
-[Service]
-WorkingDirectory=/opt/bincio
-ExecStart=/root/.local/bin/uv run bincio serve \
-    --data-dir /var/bincio/data \
-    --site-dir /opt/bincio/site \
-    --host 127.0.0.1 \
-    --port 4041
-EnvironmentFile=/etc/bincio/secrets.env
-Restart=always
-RestartSec=5
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Create `/etc/bincio/secrets.env`:
-
-```bash
-mkdir -p /etc/bincio
-chmod 700 /etc/bincio
-cat > /etc/bincio/secrets.env <<EOF
-STRAVA_CLIENT_ID=your_client_id
-STRAVA_CLIENT_SECRET=your_client_secret
-EOF
-chmod 600 /etc/bincio/secrets.env
-```
-
-Enable and start:
-
-```bash
-systemctl daemon-reload
-systemctl enable --now bincio
-systemctl status bincio
-```
-
----
-
 ## 7. nginx
 
 Create `/etc/nginx/sites-available/bincio`:
@@ -242,14 +246,36 @@ server {
 ```
 
 ```bash
+# disable the default nginx welcome page
+rm /etc/nginx/sites-enabled/default
 ln -s /etc/nginx/sites-available/bincio /etc/nginx/sites-enabled/
 nginx -t && systemctl reload nginx
 ```
 
+You can verify the site is served correctly by hitting the IP directly:
+`http://<your-vps-ip>/` — you should see the bincio activity feed, not the nginx welcome page.
+
 ---
 
 ## 8. SSL
 
+SSL requires the domain to be pointing at the VPS first. In your DNS provider, add:
+
+```
+Type:  A
+Name:  @
+Value: <your-vps-ip>
+TTL:   300
+```
+
+Verify propagation before running certbot:
+
+```bash
+dig yourdomain.com A +short   # must return your VPS IP
+```
+
+Then:
+
 ```bash
 certbot --nginx -d yourdomain.com
 # certbot edits the nginx config and sets up automatic renewal
@@ -320,4 +346,4 @@ cat /var/bincio/data/_feedback/pres.json | python3 -m json.tool
 
 - [Multi-user architecture](multi-user.md)
 - [CLI reference](../reference/cli.md)
-- [API reference](../reference/api.md)
+- [API reference](../reference/api.md)
\ No newline at end of file