416 lines
12 KiB
Markdown
416 lines
12 KiB
Markdown
# 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.
|