VPS deploy instructions
This commit is contained in:
Ovidiu U
415
docs/ops/deployment.md
Normal file
415
docs/ops/deployment.md
Normal file
@@ -0,0 +1,415 @@
|
|||||||
|
# VPS Deployment Runbook — FuelAlert
|
||||||
|
|
||||||
|
How to deploy and run this app on the IONOS VPS (Nginx + PHP-FPM + MySQL + Redis).
|
||||||
|
|
||||||
|
Two parts:
|
||||||
|
- **First-time setup** (§1–§7) — done once when provisioning the server.
|
||||||
|
- **Every deploy** (§8) — the short sequence you repeat each time you ship.
|
||||||
|
|
||||||
|
If something breaks after deploy, jump to **§10 Troubleshooting** — most live
|
||||||
|
problems are one of four things.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 0. Server prerequisites
|
||||||
|
|
||||||
|
Install these once on the VPS:
|
||||||
|
|
||||||
|
| Software | Why | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| **PHP 8.4** + FPM | runs the app | extensions: `mbstring, pdo_mysql, redis, intl, bcmath, curl, xml, zip, gd` |
|
||||||
|
| **Composer 2** | PHP deps | |
|
||||||
|
| **Node 22 + npm** | builds the Vue SPA assets | only needed to run `npm run build` |
|
||||||
|
| **MySQL 8** | database | InnoDB |
|
||||||
|
| **Redis** | queue + cache | |
|
||||||
|
| **Nginx** | web server | serves `public/` |
|
||||||
|
| **Git** | pulls the code | |
|
||||||
|
| **Certbot** | HTTPS cert | Sanctum cookie auth requires HTTPS |
|
||||||
|
| **Supervisor** *or* systemd | keeps the queue worker alive | systemd shown below |
|
||||||
|
|
||||||
|
Quick check after install: `php -v`, `composer -V`, `node -v`, `redis-cli ping` (→ `PONG`), `mysql --version`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Get the code
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /var/www
|
||||||
|
git clone <your-gitea-repo-url> fuel-alert
|
||||||
|
cd fuel-alert
|
||||||
|
git checkout main # main = live (see §9 for tagging releases)
|
||||||
|
```
|
||||||
|
|
||||||
|
The app lives at `/var/www/fuel-alert`. Adjust paths below if you use another location.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Create the production `.env`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
php artisan key:generate # sets APP_KEY
|
||||||
|
```
|
||||||
|
|
||||||
|
Then edit `.env`. **The values below are the ones that matter for production** —
|
||||||
|
see §11 for the full reference table.
|
||||||
|
|
||||||
|
### Critical — app
|
||||||
|
|
||||||
|
```dotenv
|
||||||
|
APP_NAME=FuelAlert
|
||||||
|
APP_ENV=production
|
||||||
|
APP_DEBUG=false # NEVER true on live — leaks stack traces + secrets
|
||||||
|
APP_URL=https://fuel-alert.co.uk
|
||||||
|
```
|
||||||
|
|
||||||
|
### Critical — SPA cookie/session auth (the #1 "login broke on live" trap)
|
||||||
|
|
||||||
|
This app is a Vue SPA using Sanctum cookie auth. If these don't match your real
|
||||||
|
domain over HTTPS, login/registration fail with 419/401 even though the rest of
|
||||||
|
the site looks fine:
|
||||||
|
|
||||||
|
```dotenv
|
||||||
|
SESSION_DRIVER=redis
|
||||||
|
SESSION_DOMAIN=.fuel-alert.co.uk
|
||||||
|
SESSION_SECURE_COOKIE=true
|
||||||
|
SANCTUM_STATEFUL_DOMAINS=fuel-alert.co.uk
|
||||||
|
```
|
||||||
|
|
||||||
|
### Critical — database / redis / queue / cache
|
||||||
|
|
||||||
|
```dotenv
|
||||||
|
DB_CONNECTION=mysql
|
||||||
|
DB_HOST=127.0.0.1
|
||||||
|
DB_PORT=3306
|
||||||
|
DB_DATABASE=fuel_alert
|
||||||
|
DB_USERNAME=fuel_alert
|
||||||
|
DB_PASSWORD=<strong-password>
|
||||||
|
|
||||||
|
REDIS_CLIENT=phpredis
|
||||||
|
REDIS_HOST=127.0.0.1
|
||||||
|
REDIS_PORT=6379
|
||||||
|
REDIS_PASSWORD=null
|
||||||
|
|
||||||
|
QUEUE_CONNECTION=redis # a worker MUST run — see §6
|
||||||
|
CACHE_STORE=redis
|
||||||
|
```
|
||||||
|
|
||||||
|
### Critical — your own API gate
|
||||||
|
|
||||||
|
```dotenv
|
||||||
|
API_SECRET_KEY=<long-random-string>
|
||||||
|
```
|
||||||
|
|
||||||
|
`API_SECRET_KEY` gates the station-search API (`VerifyApiKey` middleware). The SPA
|
||||||
|
sends the matching key. If it's missing/wrong, `GET /api/stations` returns 401 and
|
||||||
|
the search page shows nothing.
|
||||||
|
|
||||||
|
### Mail (Ionos SMTP)
|
||||||
|
|
||||||
|
```dotenv
|
||||||
|
MAIL_MAILER=smtp
|
||||||
|
MAIL_HOST=smtp.ionos.co.uk
|
||||||
|
MAIL_PORT=587
|
||||||
|
MAIL_SCHEME=tls
|
||||||
|
MAIL_USERNAME=<ionos-mailbox>
|
||||||
|
MAIL_PASSWORD=<ionos-password>
|
||||||
|
MAIL_FROM_ADDRESS=hello@fuel-alert.co.uk
|
||||||
|
MAIL_FROM_NAME=FuelAlert
|
||||||
|
```
|
||||||
|
|
||||||
|
### External data APIs (the product needs these to have live data)
|
||||||
|
|
||||||
|
```dotenv
|
||||||
|
FUEL_FINDER_CLIENT_ID=
|
||||||
|
FUEL_FINDER_CLIENT_SECRET=
|
||||||
|
FUEL_FINDER_BASE_URL=https://www.fuel-finder.service.gov.uk/api/v1
|
||||||
|
FRED_API_KEY=
|
||||||
|
ANTHROPIC_API_KEY=
|
||||||
|
ANTHROPIC_MODEL=claude-haiku-4-5-20251001
|
||||||
|
EIA_API_KEY=
|
||||||
|
```
|
||||||
|
|
||||||
|
### Notification providers (fill when those channels go live)
|
||||||
|
|
||||||
|
```dotenv
|
||||||
|
ONESIGNAL_APP_ID=
|
||||||
|
ONESIGNAL_API_KEY=
|
||||||
|
VONAGE_KEY=
|
||||||
|
VONAGE_SECRET=
|
||||||
|
VONAGE_WHATSAPP_FROM=
|
||||||
|
VONAGE_SMS_FROM=
|
||||||
|
```
|
||||||
|
|
||||||
|
### Stripe — can be deferred
|
||||||
|
|
||||||
|
If launching free-only first, leave Stripe **test** keys and don't promote paid
|
||||||
|
plans. When you go live with payments, see §7.
|
||||||
|
|
||||||
|
```dotenv
|
||||||
|
CASHIER_CURRENCY=gbp
|
||||||
|
STRIPE_KEY=
|
||||||
|
STRIPE_SECRET=
|
||||||
|
STRIPE_WEBHOOK_SECRET=
|
||||||
|
STRIPE_PRICE_BASIC_MONTHLY=
|
||||||
|
STRIPE_PRICE_BASIC_ANNUAL=
|
||||||
|
STRIPE_PRICE_PLUS_MONTHLY=
|
||||||
|
STRIPE_PRICE_PLUS_ANNUAL=
|
||||||
|
STRIPE_PRICE_PRO_MONTHLY=
|
||||||
|
STRIPE_PRICE_PRO_ANNUAL=
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Remember:** after ANY `.env` change on a cached production box, re-run
|
||||||
|
> `php artisan config:cache` or the change won't take effect (see §8).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Install dependencies & build
|
||||||
|
|
||||||
|
```bash
|
||||||
|
composer install --no-dev --optimize-autoloader
|
||||||
|
npm ci && npm run build # compiles the Vue SPA into public/build
|
||||||
|
```
|
||||||
|
|
||||||
|
`--no-dev` skips dev-only packages. `npm run build` is required — without it the
|
||||||
|
SPA has no compiled assets and you get a blank page / Vite manifest error.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Database: migrate + seed plans
|
||||||
|
|
||||||
|
```bash
|
||||||
|
php artisan migrate --force # --force = run in production non-interactively
|
||||||
|
php artisan db:seed --class=PlanSeeder --force # REQUIRED
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Do not** run `migrate:fresh`, `migrate:reset`, or `db:wipe` on the server —
|
||||||
|
> they destroy data. Only `migrate` (forward) is safe.
|
||||||
|
|
||||||
|
`PlanSeeder` populates the `plans` table. The entire tier/entitlement system
|
||||||
|
(`PlanFeatures`) resolves through these rows — skip it and features misbehave for
|
||||||
|
every user. It's idempotent, so it's safe to re-run.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Storage link + production caches
|
||||||
|
|
||||||
|
```bash
|
||||||
|
php artisan storage:link
|
||||||
|
|
||||||
|
php artisan config:cache
|
||||||
|
php artisan route:cache
|
||||||
|
php artisan view:cache
|
||||||
|
php artisan event:cache
|
||||||
|
```
|
||||||
|
|
||||||
|
The cache commands make production fast. Trade-off: cached config ignores later
|
||||||
|
`.env` edits until you re-run `config:cache`.
|
||||||
|
|
||||||
|
### File permissions
|
||||||
|
|
||||||
|
The web user (usually `www-data`) must be able to write to two dirs:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo chown -R www-data:www-data storage bootstrap/cache
|
||||||
|
sudo find storage -type d -exec chmod 775 {} \;
|
||||||
|
sudo find storage -type f -exec chmod 664 {} \;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Background processes (the part everyone forgets)
|
||||||
|
|
||||||
|
The app is not just web requests. Two things must run continuously or the product
|
||||||
|
silently stops working.
|
||||||
|
|
||||||
|
### 6a. Scheduler (cron) — keeps prices & predictions fresh
|
||||||
|
|
||||||
|
The app schedules the entire data pipeline: `fuel:poll`, `oil:fetch`,
|
||||||
|
`forecast:llm-overlay`, `beis:import`, `forecast:resolve-outcomes`,
|
||||||
|
`forecast:evaluate-volatility`, `fuel:archive`, plus morning/evening WhatsApp jobs.
|
||||||
|
Without cron, live data goes stale.
|
||||||
|
|
||||||
|
Add ONE cron entry (`crontab -e` as the app user):
|
||||||
|
|
||||||
|
```cron
|
||||||
|
* * * * * cd /var/www/fuel-alert && php artisan schedule:run >> /dev/null 2>&1
|
||||||
|
```
|
||||||
|
|
||||||
|
Laravel's scheduler decides internally which task runs when — you only need this
|
||||||
|
one line.
|
||||||
|
|
||||||
|
### 6b. Queue worker — sends notifications, processes polling jobs
|
||||||
|
|
||||||
|
Notifications and polling run as queued jobs. No worker = nothing ever sends.
|
||||||
|
Run it as a systemd service so it restarts on crash/reboot.
|
||||||
|
|
||||||
|
Create `/etc/systemd/system/fuelalert-worker.service`:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[Unit]
|
||||||
|
Description=FuelAlert queue worker
|
||||||
|
After=network.target redis.service mysql.service
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
User=www-data
|
||||||
|
Group=www-data
|
||||||
|
Restart=always
|
||||||
|
RestartSec=3
|
||||||
|
WorkingDirectory=/var/www/fuel-alert
|
||||||
|
ExecStart=/usr/bin/php artisan queue:work redis --queue=notifications,default --tries=3 --max-time=3600
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=multi-user.target
|
||||||
|
```
|
||||||
|
|
||||||
|
Enable it:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo systemctl daemon-reload
|
||||||
|
sudo systemctl enable --now fuelalert-worker
|
||||||
|
sudo systemctl status fuelalert-worker # should be "active (running)"
|
||||||
|
```
|
||||||
|
|
||||||
|
> The `notifications` queue is listed first so alerts get priority over default jobs.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Nginx + HTTPS
|
||||||
|
|
||||||
|
Server block (`/etc/nginx/sites-available/fuel-alert`):
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name fuel-alert.co.uk www.fuel-alert.co.uk;
|
||||||
|
root /var/www/fuel-alert/public;
|
||||||
|
|
||||||
|
index index.php;
|
||||||
|
charset utf-8;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
try_files $uri $uri/ /index.php?$query_string;
|
||||||
|
}
|
||||||
|
|
||||||
|
location ~ \.php$ {
|
||||||
|
fastcgi_pass unix:/run/php/php8.4-fpm.sock;
|
||||||
|
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
|
||||||
|
include fastcgi_params;
|
||||||
|
}
|
||||||
|
|
||||||
|
location ~ /\.(?!well-known).* { deny all; }
|
||||||
|
client_max_body_size 20M;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo ln -s /etc/nginx/sites-available/fuel-alert /etc/nginx/sites-enabled/
|
||||||
|
sudo nginx -t && sudo systemctl reload nginx
|
||||||
|
sudo certbot --nginx -d fuel-alert.co.uk -d www.fuel-alert.co.uk # HTTPS — required for secure cookies
|
||||||
|
```
|
||||||
|
|
||||||
|
`root` points at `public/`, never the project root. The SPA routing is handled by
|
||||||
|
Laravel's catch-all in `routes/web.php` via `index.php`, so the standard
|
||||||
|
`try_files … /index.php` block is all you need.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Every deploy (the repeatable sequence)
|
||||||
|
|
||||||
|
After the first-time setup, each deploy is just this. Save it as
|
||||||
|
`deploy.sh` in the project root (`chmod +x deploy.sh`) and run `./deploy.sh`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/usr/bin/env bash
|
||||||
|
set -euo pipefail
|
||||||
|
cd /var/www/fuel-alert
|
||||||
|
|
||||||
|
php artisan down --render="errors::503" # maintenance mode (optional)
|
||||||
|
|
||||||
|
git fetch --tags
|
||||||
|
git checkout "${1:-main}" # ./deploy.sh v0.2.0 → deploy a tag; no arg → main
|
||||||
|
git pull --ff-only || true
|
||||||
|
|
||||||
|
composer install --no-dev --optimize-autoloader
|
||||||
|
npm ci && npm run build
|
||||||
|
|
||||||
|
php artisan migrate --force
|
||||||
|
|
||||||
|
# refresh caches (config:cache picks up any .env changes)
|
||||||
|
php artisan config:cache
|
||||||
|
php artisan route:cache
|
||||||
|
php artisan view:cache
|
||||||
|
php artisan event:cache
|
||||||
|
|
||||||
|
php artisan queue:restart # workers reload the NEW code
|
||||||
|
php artisan up
|
||||||
|
|
||||||
|
php artisan about # sanity check: env=production, debug=false
|
||||||
|
```
|
||||||
|
|
||||||
|
> `queue:restart` is important: long-running workers keep the OLD code in memory
|
||||||
|
> until told to restart. Skip it and your new code won't run in queued jobs.
|
||||||
|
>
|
||||||
|
> Only run `db:seed --class=PlanSeeder --force` again if you changed plan/feature
|
||||||
|
> definitions — it's safe (idempotent) but usually unnecessary per deploy.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Tagging a release (rollback points)
|
||||||
|
|
||||||
|
`main` is live. Tag the commit you actually deploy so you have a named, verified
|
||||||
|
rollback point:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# locally, once the deploy is confirmed working:
|
||||||
|
git tag -a v0.1.0 -m "first live version"
|
||||||
|
git push origin v0.1.0
|
||||||
|
```
|
||||||
|
|
||||||
|
Roll back by deploying an older tag: `./deploy.sh v0.1.0`. List tags: `git tag`.
|
||||||
|
Bump the middle number for meaningful releases, the last for small fixes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Troubleshooting — the four usual suspects
|
||||||
|
|
||||||
|
| Symptom | Likely cause | Fix |
|
||||||
|
|---|---|---|
|
||||||
|
| Login/register fails with **419** or **401** | SPA cookie domains wrong | Check `APP_URL`, `SESSION_DOMAIN`, `SANCTUM_STATEFUL_DOMAINS`, `SESSION_SECURE_COOKIE` in `.env`, then `config:cache` |
|
||||||
|
| Station search returns **401 / empty** | `API_SECRET_KEY` missing or mismatched | Set it in `.env`, `config:cache`, rebuild SPA if the key is baked into the build |
|
||||||
|
| Prices/predictions are **stale or empty** | scheduler cron not running | Verify the `* * * * *` cron line; test with `php artisan schedule:run` manually |
|
||||||
|
| Notifications **never arrive** | queue worker not running | `systemctl status fuelalert-worker`; check `storage/logs/laravel.log` |
|
||||||
|
| `.env` change **had no effect** | config is cached | `php artisan config:cache` |
|
||||||
|
| **Blank page** / "Vite manifest not found" | assets not built | `npm ci && npm run build` |
|
||||||
|
| **500** right after deploy | permissions on storage | re-run the `chown`/`chmod` in §5; check `storage/logs/laravel.log` |
|
||||||
|
|
||||||
|
Useful commands: `php artisan about` (env summary), `tail -f storage/logs/laravel.log`
|
||||||
|
(live errors), `redis-cli ping`, `sudo systemctl status fuelalert-worker`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Environment variable reference
|
||||||
|
|
||||||
|
Keys that need real production values (from `.env.example`):
|
||||||
|
|
||||||
|
**App:** `APP_NAME` `APP_ENV=production` `APP_KEY` `APP_DEBUG=false` `APP_URL`
|
||||||
|
**Session/SPA:** `SESSION_DRIVER` `SESSION_DOMAIN` `SESSION_SECURE_COOKIE` `SANCTUM_STATEFUL_DOMAINS`
|
||||||
|
**Database:** `DB_CONNECTION` `DB_HOST` `DB_PORT` `DB_DATABASE` `DB_USERNAME` `DB_PASSWORD`
|
||||||
|
**Redis/queue/cache:** `REDIS_CLIENT` `REDIS_HOST` `REDIS_PORT` `REDIS_PASSWORD` `QUEUE_CONNECTION` `CACHE_STORE`
|
||||||
|
**Your API gate:** `API_SECRET_KEY`
|
||||||
|
**Mail (Ionos):** `MAIL_MAILER` `MAIL_HOST` `MAIL_PORT` `MAIL_SCHEME` `MAIL_USERNAME` `MAIL_PASSWORD` `MAIL_FROM_ADDRESS` `MAIL_FROM_NAME`
|
||||||
|
**Fuel data:** `FUEL_FINDER_CLIENT_ID` `FUEL_FINDER_CLIENT_SECRET` `FUEL_FINDER_BASE_URL` `FRED_API_KEY` `EIA_API_KEY`
|
||||||
|
**LLM:** `ANTHROPIC_API_KEY` `ANTHROPIC_MODEL` `LLM_PREDICTION_PROVIDER`
|
||||||
|
**Notifications:** `ONESIGNAL_APP_ID` `ONESIGNAL_API_KEY` `VONAGE_KEY` `VONAGE_SECRET` `VONAGE_WHATSAPP_FROM` `VONAGE_SMS_FROM`
|
||||||
|
**Stripe (deferrable):** `STRIPE_KEY` `STRIPE_SECRET` `STRIPE_WEBHOOK_SECRET` `CASHIER_CURRENCY` `STRIPE_PRICE_*`
|
||||||
|
|
||||||
|
### Stripe go-live (when payments launch)
|
||||||
|
|
||||||
|
1. Swap in live `STRIPE_KEY` / `STRIPE_SECRET` and all six `STRIPE_PRICE_*` IDs.
|
||||||
|
2. In the Stripe dashboard, add a webhook endpoint:
|
||||||
|
`https://fuel-alert.co.uk/stripe/webhook`
|
||||||
|
3. Copy its signing secret into `STRIPE_WEBHOOK_SECRET`.
|
||||||
|
4. `php artisan config:cache`.
|
||||||
|
5. Configure Stripe dashboard retries (days 1/3/5, cancel after final) for the
|
||||||
|
grace-period dunning flow.
|
||||||
Reference in New Issue
Block a user