From 4a534a8007fb08304841beec683374ada2421b2b Mon Sep 17 00:00:00 2001 From: nobswebdev Date: Wed, 28 Oct 2026 22:07:32 +0100 Subject: [PATCH] Add production deployment guide and restrict CORS to development. Document clearnet, TLS, and Tor setup; enable Nest CORS only in development and skip CORS_ORIGINS validation in production. --- README.md | 2 + backend/src/config/validate.spec.ts | 8 ++ backend/src/config/validate.ts | 3 +- backend/src/main.ts | 12 ++- deploy/DEPLOYMENT_GUIDE.md | 135 ++++++++++++++++++++++++++++ 5 files changed, 155 insertions(+), 5 deletions(-) create mode 100644 deploy/DEPLOYMENT_GUIDE.md diff --git a/README.md b/README.md index 21712f1..9c4274c 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ Self-hosted, privacy-focused image hosting. Images are metadata-stripped and encrypted in the browser before upload. Supports **zero-knowledge** viewer links and **hotlink** mode for embeds. +For production deployment, see the [deployment guide](deploy/DEPLOYMENT_GUIDE.md). + ## Development ### Start dev environment diff --git a/backend/src/config/validate.spec.ts b/backend/src/config/validate.spec.ts index c266bb4..62cdb4e 100644 --- a/backend/src/config/validate.spec.ts +++ b/backend/src/config/validate.spec.ts @@ -35,4 +35,12 @@ describe('validate', () => { expect(() => validate(validConfig({ ALTCHA_ENABLED: 'yes' }))).toThrow(); expect(() => validate(validConfig({ POSTGRES_MIGRATIONS_RUN: '1' }))).toThrow(); }); + + it('does not require CORS_ORIGINS in production', () => { + const { CORS_ORIGINS: _removed, ...productionBase } = validConfig({ + NODE_ENV: 'production' + }); + + expect(() => validate(productionBase)).not.toThrow(); + }); }); diff --git a/backend/src/config/validate.ts b/backend/src/config/validate.ts index 298f535..5126bc7 100644 --- a/backend/src/config/validate.ts +++ b/backend/src/config/validate.ts @@ -1,5 +1,5 @@ import { plainToClass } from 'class-transformer'; -import { IsEnum, IsIn, IsNotEmpty, IsNumber, IsString, Max, Min, validateSync } from 'class-validator'; +import { IsEnum, IsIn, IsNotEmpty, IsNumber, IsString, Max, Min, ValidateIf, validateSync } from 'class-validator'; import { BOOLEAN_STRING_VALUES } from '../consts/booleanStringValues'; import type { BooleanStringValue } from '../types/BooleanStringValue'; import { NodeEnv } from '../types/NodeEnv'; @@ -41,6 +41,7 @@ class EnvironmentVariables { @IsIn(BOOLEAN_STRING_VALUES) POSTGRES_MIGRATIONS_RUN: BooleanStringValue; + @ValidateIf((config: EnvironmentVariables) => config.NODE_ENV === NodeEnv.Development) @IsNotEmpty() @IsString() CORS_ORIGINS: string; diff --git a/backend/src/main.ts b/backend/src/main.ts index b167d5d..ecce0c9 100644 --- a/backend/src/main.ts +++ b/backend/src/main.ts @@ -8,6 +8,7 @@ import { altchaMiddleware } from './middlewares/altchaMiddleware'; import { AltchaService } from './modules/altcha/services/AltchaService'; import { Config } from './types/config/Config'; import { HttpMethod } from './types/HttpMethod'; +import { NodeEnv } from './types/NodeEnv'; async function bootstrap() { const app = await NestFactory.create(AppModule, { bodyParser: false }); @@ -21,6 +22,7 @@ async function bootstrap() { const { port, + nodeEnv, corsOrigins, validation: { upload: { maxRequestBodyBytes } @@ -52,10 +54,12 @@ async function bootstrap() { }) ); - app.enableCors({ - origin: corsOrigins, - credentials: true - }); + if (nodeEnv === NodeEnv.Development) { + app.enableCors({ + origin: corsOrigins, + credentials: true + }); + } app.set('trust proxy', 1); diff --git a/deploy/DEPLOYMENT_GUIDE.md b/deploy/DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000..f04ea25 --- /dev/null +++ b/deploy/DEPLOYMENT_GUIDE.md @@ -0,0 +1,135 @@ +# Deployment guide + +## 1. Requirements + +- Ubuntu 22.04+ or similar Linux with Docker Engine and the Compose plugin — follow [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository). Tested and recommended on Ubuntu 22.04 LTS. +- A domain name pointing at your server (A records for apex and `www`) + +## 2. Server setup + +Deploy as **root** on the VPS. Docker Engine and Compose plugin must be installed — [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository). + +Verify: + +```bash +docker compose version +``` + +## 3. Clone the repository + +```bash +cd /root +git clone https://git.nobswebdev.com/nobswebdev/private_image.git private_image +cd private_image +``` + +## 4. Configure environment + +```bash +cd /root/private_image +cp .env.example .env.prod +chmod 600 .env.prod +``` + +Edit `.env.prod`. Mandatory configuration: + +| Variable | Production value | +| --- | --- | +| `COMPOSE_PROJECT_NAME` | `private_image_prod` | +| `POSTGRES_PASSWORD` | strong random password | +| `POSTGRES_MIGRATIONS_RUN` | `true` | +| `PGADMIN_DEFAULT_PASSWORD` | strong random password | +| `NODE_ENV` | `production` | +| `CLEARNET_DOMAIN` | `your-domain.com` | +| `ONION_HOSTNAME` | set after step 8 (Tor); use placeholder until then | +| `ALTCHA_HMAC_KEY` | strong random secret | +| `VITE_API_BASE_URL` | `/api` | +| `VITE_CLEARNET_SCHEME` | `https` | +| `VITE_CLEARNET_DOMAIN` | `your-domain.com` (same host as `CLEARNET_DOMAIN`) | +| `VITE_ONION_HOSTNAME` | same as `ONION_HOSTNAME` after step 8 | + +Keep `VITE_VALIDATION_*` and `VITE_UPLOAD_*` aligned with backend `VALIDATION_*` caps in the same file. + +## 5. Bootstrap TLS certificates + +Nginx needs certificate files before it can start on port 443. For the **first** deploy, create a temporary self-signed pair (replaced after Let's Encrypt): + +```bash +./deploy/scripts/bootstrap-certs.sh +``` + +After the stack is running, obtain real certificates (step 7). + +## 6. Start the stack + +```bash +./deploy/scripts/deploy.sh +``` + +Wait until `backend` and `nginx` are healthy: + +```bash +docker compose --env-file .env.prod -f docker-compose.prod.yml ps +``` + +## 7. Issue Let's Encrypt certificates + +Remove the temporary bootstrap certificates under `deploy/certs/live/` (Certbot cannot issue into the layout created by `bootstrap-certs.sh`): + +```bash +rm -rf deploy/certs/live/* +``` + +Request the real certificate (apex + www): + +```bash +./deploy/scripts/issue-certs.sh --email you@example.com +``` + +Reload nginx: + +```bash +docker compose --env-file .env.prod -f docker-compose.prod.yml exec nginx nginx -s reload +``` + +### Automatic renewal + +Open root's crontab: + +```bash +crontab -e +``` + +Add a weekly job (`/root/private_image` is the standard deploy path): + +```cron +0 3 * * 0 /root/private_image/deploy/scripts/renew-certs.sh >> /var/log/private_image-cert-renew.log 2>&1 +``` + +Save and exit the editor. Optional — run once manually to verify: + +```bash +/root/private_image/deploy/scripts/renew-certs.sh +``` + +## 8. Tor onion address + +```bash +./deploy/scripts/show-onion.sh +``` + +Copy the hostname into `.env.prod` as `ONION_HOSTNAME` and `VITE_ONION_HOSTNAME`, then rebuild and recreate nginx (frontend share links and `Onion-Location` are baked at build / entrypoint): + +```bash +docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --build --force-recreate nginx +``` + +Tor Browser will then show ".onion available" when visitors open the clearnet site over HTTPS. + +## 9. Updates + +```bash +./deploy/scripts/update.sh +``` + +This pulls the latest code and rebuilds the stack (`deploy.sh`).