# ProjectPay VPS deployment
Migrated November 3, 2026 from Heroku app `afterdark` to the existing VPS at
198.251.64.57. Public URL: https://payment.afterdarklabs.io.
The app is still MicroPie/ASGI. No application or payment logic changed during
this migration. `requirements-production.txt` pins the dependency versions
observed on the working Heroku dyno. The same MongoDB Atlas database remains in
use; projects, archived projects, payments, checkout records, webhook events,
number counters, and server-side sessions were not moved or reset. The existing
Stripe webhook URL and signing secret were retained.
## Runtime
- Service and socket: `projectpay.service`, `projectpay.socket`.
- Source: `/opt/apps/projectpay/current`, a symlink into
`/opt/apps/projectpay/releases/20261103T054534Z`.
- Virtual environment: `/opt/apps/projectpay/.venv`.
- Dedicated service user: `projectpay`, without an interactive login shell.
- Secrets: `/etc/projectpay/environment`, root-owned mode 0600. The production
environment was transferred privately from Heroku, not copied from the local
development `.env`. No credentials belong in this repository.
- One Uvicorn worker, a 50% single-core CPU cap, 384 MiB memory high watermark,
512 MiB hard memory cap, and 64 tasks. Observed memory after verification was
about 50 MB; the VPS had about 2.8 GiB available before deployment.
- Private Unix socket: `/run/projectpay/uvicorn.sock`, owner projectpay:www-data,
mode 0660. No public or loopback Python TCP port is opened. SocketBindDeny
prevents the service from explicitly binding IPv4/IPv6 ports.
- The app trusts proxy headers only on this private transport. nginx replaces
forwarded headers, and only official Cloudflare networks may supply client IPs.
- The service has read-only system/home protection, a private temporary directory,
no new privileges, and kernel/control-group restrictions. Invoice data remains
in Atlas, so the application needs no writable local data directory.
- Both service and socket are enabled for reboot.
## nginx and TLS
| Source file | VPS destination |
| --- | --- |
| projectpay.service | /etc/systemd/system/projectpay.service |
| projectpay.socket | /etc/systemd/system/projectpay.socket |
| projectpay-http.conf | /etc/nginx/conf.d/projectpay.conf |
| projectpay-cloudflare-realip.conf | /etc/nginx/snippets/projectpay-cloudflare-realip.conf |
| projectpay.nginx.conf | /etc/nginx/sites-available/projectpay |
`/etc/nginx/sites-enabled/projectpay` links to the vhost. Shared nginx.conf,
GitMan's vhost, and Wail's vhost were not modified. Their service PIDs remained
unchanged through migration; nginx was gracefully reloaded.
The dedicated vhost enforces TLS, HSTS, no-store responses, sanitized proxy
headers, 128 KiB form bodies, a separate 1 MiB Stripe webhook allowance, timeouts,
rate limits, and connection limits. Login POSTs and their trailing-slash aliases
share one per-client auth bucket, using nginx's normalized URI. Webhooks have a separate higher rate bucket
and are never retried automatically to another upstream. Existing application
CSP, frame protection, secure cookies, CSRF, and webhook verification remain active.
Invoice share links contain bearer tokens. nginx's dedicated
`/var/log/nginx/projectpay-access.log` deliberately omits URL paths, query strings,
cookies, request bodies, and authorization headers. Uvicorn access logs are off.
The system nginx logrotate wildcard covers this log.
The Cloudflare DNS record for payment.afterdarklabs.io is a proxied A record
pointing to 198.251.64.57. A host-specific Cloudflare rule uses Full (strict)
origin TLS; other host policies were preserved.
Certbot certificate name: `projectpay`. Its certificate and key are under
`/etc/letsencrypt/live/projectpay/`. Initial issuance used a temporary DNS
challenge before traffic moved. Renewal was then reconfigured and successfully
tested using HTTP webroot `/var/lib/projectpay-acme`; certbot.timer is enabled
and active. Successful renewal reloads nginx. No Cloudflare API token is stored
on the VPS. Keep both HTTP and HTTPS ACME locations available.
## Verification
Before cutover:
- All 20 existing application security tests passed in the new runtime.
- MongoDB connectivity and existing project/payment records were verified.
- HTTPS admin login, secure cookie flags, dashboard, and logout passed.
- Heroku accepted the VPS-created Mongo-backed admin session before DNS changed.
- An existing public invoice rendered and the existing live Stripe Product was
verified using a read-only API request. No price, Checkout Session, or charge
was created by migration tests.
- Unsigned Stripe webhook requests were rejected with HTTP 401.
- Counts of projects, deleted projects, payments, checkout sessions, and webhook
events stayed unchanged during the preview checks.
- nginx's user can connect to the private socket; an unrelated user cannot.
After cutover:
- Public HTTPS admin login/logout passed through Cloudflare to the VPS.
- A correctly signed probe deliberately lacking an event ID passed signature
validation and received the expected HTTP 400 before any payment/event writes.
- Certificate renewal validation passed and automatic renewal was configured.
- GitMan and Wail remained healthy with protected config hashes and PIDs unchanged.
- The old Heroku web formation was scaled to zero after public verification.
No Heroku add-ons were present. After the user confirmed the VPS was working,
the retired Heroku app, its config, and its Heroku domain attachment were deleted
on November 3, 2026. The local Heroku Git remote was removed.
## Operations and rollback
Useful checks:
```sh
systemctl status projectpay projectpay.socket
journalctl -u projectpay --since '15 minutes ago'
nginx -t
systemctl status certbot.timer
```
For a source update, stage a new release directory, install any intentionally
changed dependency pins, switch `current`, and restart projectpay.service. Run
application/security, database, public invoice, and webhook verification before
considering deployment complete. Keep credentials out of source archives and logs.
Migration backup on the VPS:
`/root/projectpay-releases/before-migration-20261103T054752Z/` contains the original
nginx archive, protected file hashes/PIDs, and `cutover.json` with the previous DNS
and Heroku formation. `/root/projectpay-releases/preview-verification.json` records
the read-only preview results.
Rollback while keeping the same Atlas data:
1. Use a known-good VPS release directory, or stage the known-good source and
dependency pins in a new release directory.
2. Point `/opt/apps/projectpay/current` at that release and restart projectpay.service.
3. Verify public admin access, customer invoice pages, and webhook validation.
4. Keep the domain pointing at the VPS. The old Heroku app and CNAME are retired
and cannot be used as a rollback destination.
Do not restore an old database snapshot or delete Atlas data during an application
rollback. Keep the root-only production environment and existing Stripe webhook
URL unchanged. The original cutover.json is a historical migration record, not a
current instruction to restore Heroku DNS.