Skip to content

Commit 21f04eb

Browse files
adityajha2005adityajha2005
authored
docs(guides): add Deployment section with Docker and Vercel guides (#343)
* docs(guides): add Deployment section with Docker and Vercel guides * docs: remove deployment backup files * docs(guides): update Vercel API hosting recommendations to reflect recent improvements
1 parent bc7ff11 commit 21f04eb

File tree

4 files changed

+163
-0
lines changed

4 files changed

+163
-0
lines changed

‎apps/docs/docs/guides/deployment/_category_.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"label": "Deployment",
3+
"position": 6,
4+
"link": {
5+
"type": "generated-index",
6+
"title": "Deployment",
7+
"description": "How to deploy Open Self Service using Docker and Vercel."
8+
}
9+
}
10+
11+

‎apps/docs/docs/guides/deployment/docker.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: Deploy with Docker
3+
description: Build and run Open Self Service using Docker and Docker Compose.
4+
---
5+
6+
This project ships with production-ready Dockerfiles for both apps and a `docker-compose.yml` at the repository root.
7+
8+
Prerequisites:
9+
10+
- Docker 24+
11+
- Docker Compose v2+
12+
13+
Recommended approach: use the provided `docker-compose.yml` to run both services together.
14+
15+
Create a shared network (first time only):
16+
17+
```bash
18+
docker network create app_network
19+
```
20+
21+
Start both services:
22+
23+
```bash
24+
docker compose up -d --build
25+
```
26+
27+
This will:
28+
29+
- Build `apps/frontend/Dockerfile` and expose it on `http://localhost:3000`
30+
- Build `apps/api-harmonization/Dockerfile` and expose it on `http://localhost:3001`
31+
32+
Environment variables
33+
34+
The `docker-compose.yml` includes sane defaults. Adjust as needed (especially external API keys).
35+
36+
- Frontend (Next.js):
37+
- `NEXT_PUBLIC_BASE_URL` (e.g. `http://localhost:3000`)
38+
- `NEXT_PUBLIC_API_URL` (public API URL, e.g. `http://localhost:3001/api`)
39+
- `NEXT_PUBLIC_API_URL_INTERNAL` (internal container URL, e.g. `http://api-harmonization:3001/api`)
40+
- `NEXT_PUBLIC_DEFAULT_LOCALE`, `NEXT_PUBLIC_SUPPORTED_LOCALES`
41+
- Optional logging: `NEXT_PUBLIC_LOG_LEVEL`, `NEXT_PUBLIC_LOG_FORMAT`, `NEXT_PUBLIC_LOG_COLORS_ENABLED`
42+
- Auth (optional): `AUTH_SECRET`, `AUTH_TRUST_HOST`, `AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET`, `AUTH_GOOGLE_ID`, `AUTH_GOOGLE_SECRET`, `AUTH_DATABASE_URL`, `AUTH_DEFAULT_USER_ROLE`
43+
44+
- API (NestJS):
45+
- `PORT` (e.g. `3001`)
46+
- `API_PREFIX` (e.g. `api`)
47+
- `FRONT_BASE_URLS` (comma-separated, e.g. `http://localhost:3000`)
48+
- Optional logging: `LOG_LEVEL`, `LOG_FORMAT`, `LOG_COLORS_ENABLED`
49+
- Integrations: see `/docs/integrations` for provider-specific variables (e.g. `CMS_STRAPI_BASE_URL`, `ALGOLIA_*`, `MEDUSAJS_*`, `CACHE_*`, etc.)
50+
51+
Useful commands
52+
53+
```bash
54+
# View logs
55+
docker compose logs -f frontend
56+
docker compose logs -f api-harmonization
57+
58+
# Rebuild after changes
59+
docker compose build --no-cache frontend api-harmonization
60+
61+
# Stop
62+
docker compose down
63+
```
64+
65+
Build images manually (optional)
66+
67+
```bash
68+
# from repo root
69+
docker build -t o2s-frontend -f apps/frontend/Dockerfile .
70+
docker build -t o2s-api -f apps/api-harmonization/Dockerfile .
71+
72+
docker run --rm -p 3000:3000 --network app_network \
73+
-e NEXT_PUBLIC_BASE_URL=http://localhost:3000 \
74+
-e NEXT_PUBLIC_API_URL=http://localhost:3001/api \
75+
-e NEXT_PUBLIC_API_URL_INTERNAL=http://api-harmonization:3001/api \
76+
o2s-frontend
77+
78+
docker run --rm -p 3001:3001 --network app_network \
79+
-e PORT=3001 -e API_PREFIX=api -e FRONT_BASE_URLS=http://localhost:3000 \
80+
o2s-api
81+
```
82+
83+
**Note:** The Dockerfiles use Turborepo's `turbo prune` with `@dxp/frontend` and `@dxp/api-harmonization` package names internally. This is handled automatically by the build process.
84+
85+
Example Dockerfiles
86+
87+
See the repository for maintained examples:
88+
89+
- `apps/frontend/Dockerfile`
90+
- `apps/api-harmonization/Dockerfile`
91+
92+

‎apps/docs/docs/guides/deployment/overview.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Overview
3+
description: How to deploy Open Self Service using Docker and Vercel.
4+
---
5+
6+
This guide walks you through deploying Open Self Service in production.
7+
8+
- Docker: Build and run the `frontend` and `api-harmonization` services locally or on your own infrastructure.
9+
- Vercel: Deploy the `frontend` app with a monorepo setup. The API should be deployed via Docker or another container platform.
10+
11+
Get started:
12+
13+
- Docker: See [Deploy with Docker](./docker)
14+
- Vercel: See [Deploy on Vercel](./vercel)
15+
16+

‎apps/docs/docs/guides/deployment/vercel.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
title: Deploy on Vercel
3+
description: Configure a monorepo deployment of the Next.js frontend to Vercel.
4+
---
5+
6+
This section covers deploying the Next.js `frontend` app to Vercel. The NestJS API is best deployed as a container (see [Deploy with Docker](./docker)).
7+
8+
Project settings
9+
10+
1) Import the GitHub repository into Vercel.
11+
2) In Project Settings → General:
12+
- Root Directory: `apps/frontend`
13+
- Framework Preset: Next.js
14+
3) In Project Settings → Build & Development Settings:
15+
- Install Command: `npm ci` (Vercel default is OK)
16+
- Build Command (monorepo with Turborepo): `npx turbo run build --filter=frontend`
17+
- Output Directory: (handled by Next.js)
18+
19+
Environment variables
20+
21+
Add these variables in Project Settings → Environment Variables for Preview and Production:
22+
23+
- `NEXT_PUBLIC_BASE_URL` → your Vercel domain, e.g. `https://your-app.vercel.app`
24+
- `NEXT_PUBLIC_API_URL` → your public API URL, e.g. `https://api.your-domain.com/api`
25+
- `NEXT_PUBLIC_API_URL_INTERNAL` → optional, for SSR-to-API traffic inside your network; for Vercel, use the same as `NEXT_PUBLIC_API_URL` unless you route via private networking
26+
- `NEXT_PUBLIC_DEFAULT_LOCALE`, `NEXT_PUBLIC_SUPPORTED_LOCALES`
27+
- Optional logging: `NEXT_PUBLIC_LOG_LEVEL`, `NEXT_PUBLIC_LOG_FORMAT`, `NEXT_PUBLIC_LOG_COLORS_ENABLED`
28+
- Auth (optional): `AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET`, `AUTH_GOOGLE_ID`, `AUTH_GOOGLE_SECRET`, `AUTH_SECRET`, `AUTH_DEFAULT_USER_ROLE`
29+
30+
Notes
31+
32+
- API hosting: Historically, Vercel Serverless was not recommended for the NestJS API in this repository. However, Vercel has recently added improved backend support (including NestJS). For now we recommend deploying the API as a container (Docker on VM/Kubernetes/Fly.io/Render/etc.) and exposing a public URL consumed by the frontend, but this is under evaluation and may change. We plan to investigate first-class Vercel API hosting and update this guide accordingly.
33+
- CORS: Ensure the API’s `FRONT_BASE_URLS` includes your Vercel domains (both Preview and Production), e.g. `https://your-app.vercel.app,https://your-branch-your-team.vercel.app`.
34+
- Images and headers: If you use custom headers or remote images, configure them in `apps/frontend/next.config.ts`.
35+
36+
Production checks
37+
38+
After the first deployment:
39+
40+
1) Visit the Vercel URL (`NEXT_PUBLIC_BASE_URL`) and confirm app loads.
41+
2) Verify client→API requests target `NEXT_PUBLIC_API_URL` and succeed (200s).
42+
3) Confirm i18n defaults via `NEXT_PUBLIC_DEFAULT_LOCALE` and `NEXT_PUBLIC_SUPPORTED_LOCALES`.
43+
44+

0 commit comments

Comments
 (0)