From 5ef7f18f778a7de90ad9c091e86a4cb8be6e0f49 Mon Sep 17 00:00:00 2001 From: Amirhossein Khalili Date: Fri, 1 May 2026 10:49:38 +0330 Subject: [PATCH] chore(readme): add README.md --- README.md | 254 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 207 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index e517fed..8745e2f 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,250 @@ # Qlockify Deployment -This repository is the deployment layer only. +Main deployment and operations repository for Qlockify. + +This repo is the entrypoint for running the full product stack in production. + +## Related Repositories + +- Deployment repository declared by `origin`: `https://git.amiirkhl.ir/Qlockify/qlockify-core-deployment.git` +- Backend repository declared by its `origin`: `https://git.amiirkhl.ir/Qlockify/qlockify-backend-deployment.git` +- Frontend repository declared by its `origin`: `https://git.amiirkhl.ir/Qlockify/qlockify-frontend-deployment.git` + +Use this repo for: + +- Docker Compose orchestration +- Nginx +- SSL certificate mounting +- domain routing +- environment layout +- production service startup + +Use the backend and frontend repos for application-level implementation details. + +## What This Repo Contains + +- `docker-compose.yml` +- Nginx config +- Postgres support files +- Dockerfiles for production images +- deployment environment samples +- container networking and volume wiring + +## Architecture + +Main deployed services: + +- `nginx` +- `frontend` +- `backend` +- `celery` +- `celery-beat` +- `redis` +- `db` + +Traffic pattern: + +- `qlockify.ir` serves the frontend +- `api.qlockify.ir` serves the backend API, admin, docs, static, and media +- Nginx terminates TLS and proxies requests to the frontend and backend containers + +## Expected Repository Layout + +Docker builds read from nested application directories inside this repository: -Docker builds now read from nested application source directories inside this repository: - `./backend/qlockify-backend-deployment` - `./frontend/qlockify-frontend-deployment` -Those directories are expected to contain the backend and frontend application source before you build for deployment. - -## Local structure - -The expected deployment layout is: +Expected layout: ```text qlockify-deployment/ backend/ + Dockerfile + .env.sample qlockify-backend-deployment/ frontend/ + Dockerfile + .env.sample qlockify-frontend-deployment/ nginx/ postgres/ docker-compose.yml ``` -## Deployment flow +## Deployment Flow -1. Put your application source into: - - `./backend/qlockify-backend-deployment` - - `./frontend/qlockify-frontend-deployment` -2. Configure deployment env files: - - `./.env` - - `./backend/qlockify-backend-deployment/.env` - - `./frontend/qlockify-frontend-deployment/.env` -3. From `qlockify-deployment`, build and start the stack: +### 1. Place application source + +Put the app repos into: + +- `./backend/qlockify-backend-deployment` +- `./frontend/qlockify-frontend-deployment` + +### 2. Configure env files + +Create and fill: + +- `./.env` +- `./backend/qlockify-backend-deployment/.env` +- `./frontend/qlockify-frontend-deployment/.env` + +### 3. Build and run ```powershell -docker compose up --build +docker compose up -d --build ``` -The backend container runs database migrations and `collectstatic` on startup, then serves Django with Gunicorn using `config.wsgi:application`. +The backend container runs: -## Domain setup +- database migrations +- `collectstatic` +- Gunicorn startup + +## Domain and Routing + +Configured domains: -The Nginx config is prepared for: - `qlockify.ir` - `www.qlockify.ir` - `api.qlockify.ir` -Requests to `www.qlockify.ir` are redirected to `qlockify.ir`. -Backend traffic is served from `api.qlockify.ir`. +Behavior: -Before bringing the stack up in production: -1. Point the DNS `A` or `AAAA` records for `qlockify.ir`, `www.qlockify.ir`, and `api.qlockify.ir` to your server. -2. Set the backend env values in `./backend/qlockify-backend-deployment/.env`: - - `DJANGO_ALLOWED_HOSTS=api.qlockify.ir,qlockify.ir,www.qlockify.ir` - - `CORS_ALLOWED_ORIGINS=https://qlockify.ir,https://www.qlockify.ir` - - `CSRF_TRUSTED_ORIGINS=https://api.qlockify.ir,https://qlockify.ir,https://www.qlockify.ir` - - `BASE_URL=https://api.qlockify.ir` -3. Set the frontend env value in `./frontend/qlockify-frontend-deployment/.env`: - - `VITE_API_BASE_URL=https://api.qlockify.ir/api` +- `www.qlockify.ir` redirects to `qlockify.ir` +- `http` redirects to `https` +- frontend is served from `qlockify.ir` +- backend traffic is served from `api.qlockify.ir` -## SSL certificates +Before production startup: -HTTPS is configured through Nginx if you place these files in: +1. Point DNS records for `qlockify.ir`, `www.qlockify.ir`, and `api.qlockify.ir` to the server. +2. Make sure `80` and `443` are open on the server firewall. +3. Make sure the TLS certificate covers all required names. + +## SSL Certificates + +Place certificate files here: ```text ./nginx/certs/fullchain.pem ./nginx/certs/privkey.pem ``` -The repo keeps `./nginx/certs/.gitkeep` only. Actual certificate files are ignored by git. +The repository intentionally keeps only: -With the current Nginx config: -- `http://qlockify.ir` redirects to `https://qlockify.ir` -- `http://www.qlockify.ir` redirects to `https://qlockify.ir` -- `https://www.qlockify.ir` redirects to `https://qlockify.ir` -- `http://api.qlockify.ir` redirects to `https://api.qlockify.ir` -- the main site is served from `https://qlockify.ir` -- the backend API, admin, docs, media, and static files are served from `https://api.qlockify.ir` +- `./nginx/certs/.gitkeep` -Make sure port `443` is open on the server firewall before starting the stack. +Real certificate files are ignored by git. -## SSE Notifications +## Required Backend Environment -Notifications now use Server-Sent Events at `/api/notifications/stream/`. +Set these in: -- Nginx disables buffering and cacheing for the SSE endpoint. -- The current Gunicorn setup can serve SSE for MVP traffic, but each live stream consumes a worker while connected. -- If notification concurrency grows, move the SSE endpoint to an async worker class or a dedicated ASGI process. +```text +./backend/qlockify-backend-deployment/.env +``` + +Core production values: + +- `DJANGO_ALLOWED_HOSTS=api.qlockify.ir,qlockify.ir,www.qlockify.ir` +- `CORS_ALLOWED_ORIGINS=https://qlockify.ir,https://www.qlockify.ir` +- `CSRF_TRUSTED_ORIGINS=https://api.qlockify.ir,https://qlockify.ir,https://www.qlockify.ir` +- `BASE_URL=https://api.qlockify.ir` +- `POSTGRES_HOST=db` +- `REDIS_HOST=redis` +- `REDIS_URL=redis://redis:6379/0` +- `CELERY_BROKER_URL=redis://redis:6379/0` +- `CELERY_RESULT_BACKEND=redis://redis:6379/1` + +Google OAuth values: + +- `GOOGLE_OAUTH_CLIENT_ID=...` +- `GOOGLE_OAUTH_CLIENT_SECRET=...` +- `GOOGLE_OAUTH_REDIRECT_URI=https://api.qlockify.ir/api/users/oauth/google/callback/` +- `GOOGLE_OAUTH_FRONTEND_CALLBACK_URL=https://qlockify.ir/auth/google/callback` + +## Required Frontend Environment + +Set this in: + +```text +./frontend/qlockify-frontend-deployment/.env +``` + +```text +VITE_API_BASE_URL=https://api.qlockify.ir/api +``` + +## Background Workers + +This stack includes: + +- `celery` for async jobs +- `celery-beat` for scheduled jobs + +If background scheduling stops working, inspect: + +```powershell +docker compose logs -f celery +docker compose logs -f celery-beat +``` + +## Notifications and SSE + +Notifications use Server-Sent Events at `/api/notifications/stream/`. + +Current behavior: + +- Nginx disables buffering for the SSE endpoint +- Gunicorn is tuned to tolerate connected streams for current traffic +- if concurrency grows materially, move SSE to async workers or a dedicated ASGI service + +## Useful Operations + +Build/rebuild: + +```powershell +docker compose up -d --build +``` + +Restart a subset: + +```powershell +docker compose up -d --build nginx backend frontend +``` + +Inspect running services: + +```powershell +docker compose ps +``` + +Follow logs: + +```powershell +docker compose logs -f nginx +docker compose logs -f backend +docker compose logs -f celery +docker compose logs -f celery-beat +``` + +Stop everything: + +```powershell +docker compose down +``` + +## Scope Boundary + +This repo should document: + +- infrastructure +- runtime topology +- domains +- Nginx +- Docker Compose +- SSL +- operational startup and troubleshooting + +It should not duplicate the application-specific implementation details already documented in the backend and frontend repositories.