docs: add server setup requirements for reverse proxy and CI/CD
This commit is contained in:
Kushal Gaywala
137
docs/server-setup.md
Normal file
137
docs/server-setup.md
Normal file
@@ -0,0 +1,137 @@
|
|||||||
|
# Server Setup
|
||||||
|
|
||||||
|
This document describes the requirements for hosting the BudgetWise monorepo deployments. It is intentionally tool-agnostic — any reverse proxy that meets the requirements below will work.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. SSH Deploy Access
|
||||||
|
|
||||||
|
CI pipelines connect to the server over SSH to transfer built files. A dedicated deploy user is required.
|
||||||
|
|
||||||
|
**Requirements:**
|
||||||
|
- A non-root system user (e.g. `deploy`) with shell access
|
||||||
|
- The CI deploy SSH public key added to that user's `~/.ssh/authorized_keys`
|
||||||
|
- SSH key must correspond to the `ssh_private_key` Woodpecker secret
|
||||||
|
|
||||||
|
**Deploy directory:**
|
||||||
|
- The deploy user must have read/write access to the base deploy path (the value of the `deploy_path` Woodpecker secret, e.g. `/var/www/budget-app`)
|
||||||
|
- The directory must exist before the first pipeline run
|
||||||
|
- Subdirectories `production/` and `staging/` must also exist and be writable
|
||||||
|
- PR preview directories (`mr-{number}/`) are created and deleted automatically by the CI — no pre-creation needed
|
||||||
|
|
||||||
|
```
|
||||||
|
/var/www/budget-app/ ← deploy_path (must exist, writable by deploy user)
|
||||||
|
production/ ← must exist
|
||||||
|
staging/ ← must exist
|
||||||
|
mr-42/ ← created by CI on PR open, deleted on PR close
|
||||||
|
mr-91/
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. DNS
|
||||||
|
|
||||||
|
Three types of hostnames are used:
|
||||||
|
|
||||||
|
| Hostname pattern | Environment | Example |
|
||||||
|
|---|---|---|
|
||||||
|
| `{domain}` | Production | `budget.kushalgaywala.com` |
|
||||||
|
| `staging.{domain}` | Staging | `staging.budget.kushalgaywala.com` |
|
||||||
|
| `{pr-number}.{domain}` | PR preview | `42.budget.kushalgaywala.com` |
|
||||||
|
|
||||||
|
**Requirements:**
|
||||||
|
- An A (or AAAA) record pointing `{domain}` to the server IP
|
||||||
|
- A wildcard A record `*.{domain}` pointing to the same server IP — this covers staging and all PR preview subdomains with a single record
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. TLS
|
||||||
|
|
||||||
|
**Requirements:**
|
||||||
|
- TLS certificates for `{domain}` and `*.{domain}` (wildcard)
|
||||||
|
- A wildcard certificate covers staging and all PR preview subdomains automatically, so no certificate management is needed per PR
|
||||||
|
- The wildcard certificate must be issued via a DNS-01 ACME challenge (HTTP-01 cannot validate wildcard domains)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Reverse Proxy
|
||||||
|
|
||||||
|
The reverse proxy sits in front of the deploy directories and routes incoming HTTPS requests to the correct static files.
|
||||||
|
|
||||||
|
### 4.1 Static file serving
|
||||||
|
|
||||||
|
Each environment maps a hostname to a directory of static HTML/JS/CSS files built by Vite.
|
||||||
|
|
||||||
|
| Hostname | Directory |
|
||||||
|
|---|---|
|
||||||
|
| `{domain}` | `{deploy_path}/production/` |
|
||||||
|
| `staging.{domain}` | `{deploy_path}/staging/` |
|
||||||
|
| `{pr-number}.{domain}` | `{deploy_path}/mr-{pr-number}/` |
|
||||||
|
|
||||||
|
### 4.2 SPA fallback routing
|
||||||
|
|
||||||
|
The app is a single-page application (React Router). Any request for a path that does not match a physical file must fall back to serving `index.html` from that environment's directory.
|
||||||
|
|
||||||
|
**Example:** A request for `/buckets/42` has no corresponding file on disk. The proxy must serve `index.html` instead of returning a 404, so React Router can handle the route client-side.
|
||||||
|
|
||||||
|
**Requirement:** For every environment, configure: "if the requested file does not exist, serve `index.html` from the same root directory."
|
||||||
|
|
||||||
|
### 4.3 Wildcard PR preview routing
|
||||||
|
|
||||||
|
The proxy must extract the PR number from the subdomain and map it to the correct directory dynamically — without needing a config change per PR.
|
||||||
|
|
||||||
|
**Requirement:** Match hostnames of the form `{number}.{domain}` and serve files from `{deploy_path}/mr-{number}/`, with the SPA fallback above applied.
|
||||||
|
|
||||||
|
**Note:** If a PR preview directory does not exist (e.g. the PR was closed and cleaned up), the proxy should return a 404 or a friendly error page rather than serving files from another environment.
|
||||||
|
|
||||||
|
### 4.4 HTTP → HTTPS redirect
|
||||||
|
|
||||||
|
**Requirement:** All plain HTTP requests must be redirected to HTTPS (301 or 308).
|
||||||
|
|
||||||
|
### 4.5 Headers (recommended)
|
||||||
|
|
||||||
|
| Header | Value | Reason |
|
||||||
|
|---|---|---|
|
||||||
|
| `X-Frame-Options` | `DENY` | Prevent clickjacking |
|
||||||
|
| `X-Content-Type-Options` | `nosniff` | Prevent MIME sniffing |
|
||||||
|
| `Referrer-Policy` | `strict-origin-when-cross-origin` | Limit referrer leakage |
|
||||||
|
| `Cache-Control` for `index.html` | `no-cache` | Ensure users get the latest app shell |
|
||||||
|
| `Cache-Control` for `assets/` | `public, max-age=31536000, immutable` | Vite hashes asset filenames, safe to cache forever |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Woodpecker CI
|
||||||
|
|
||||||
|
Woodpecker must be connected to the Gitea repo and have the following secrets configured under **Repository → Settings → Secrets**:
|
||||||
|
|
||||||
|
| Secret name | Description |
|
||||||
|
|---|---|
|
||||||
|
| `ssh_private_key` | Private SSH key for the deploy user |
|
||||||
|
| `deploy_host` | Server hostname or IP |
|
||||||
|
| `deploy_user` | SSH username on the server |
|
||||||
|
| `deploy_path` | Absolute base path, e.g. `/var/www/budget-app` |
|
||||||
|
| `prod_url` | Full production URL, e.g. `https://budget.kushalgaywala.com` |
|
||||||
|
| `prod_appwrite_endpoint` | Production Appwrite API endpoint |
|
||||||
|
| `prod_appwrite_project_id` | Production Appwrite project ID |
|
||||||
|
| `prod_appwrite_api_key` | Production Appwrite API key (`databases.write` + `collections.write` scopes) |
|
||||||
|
| `staging_url` | Full staging URL, e.g. `https://staging.budget.kushalgaywala.com` |
|
||||||
|
| `staging_appwrite_endpoint` | Staging Appwrite API endpoint |
|
||||||
|
| `staging_appwrite_project_id` | Staging Appwrite project ID |
|
||||||
|
| `staging_appwrite_api_key` | Staging Appwrite API key (same scopes) |
|
||||||
|
| `base_domain` | Base domain for PR previews, e.g. `budget.kushalgaywala.com` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. What CI Handles Automatically
|
||||||
|
|
||||||
|
Once the above is in place, no further manual server changes are needed for day-to-day use:
|
||||||
|
|
||||||
|
| Event | What happens automatically |
|
||||||
|
|---|---|
|
||||||
|
| Push to `main` | Web app built with production credentials and rsynced to `production/` |
|
||||||
|
| Push to `staging` | Web app built with staging credentials and rsynced to `staging/` |
|
||||||
|
| PR opened / updated | Web app built and deployed to `mr-{number}/` |
|
||||||
|
| PR closed | `mr-{number}/` directory removed from server |
|
||||||
|
| `apps/appwrite/**` changed on `main` | Appwrite schema deployed to production Appwrite project |
|
||||||
|
| `apps/appwrite/**` changed on `staging` | Appwrite schema deployed to staging Appwrite project |
|
||||||
Reference in New Issue
Block a user