qlockify-core-deployment/README.md

Qlockify Deployment

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:

• ./backend/qlockify-backend-deployment
• ./frontend/qlockify-frontend-deployment

Expected layout:

qlockify-deployment/
  backend/
    Dockerfile
    .env.sample
    qlockify-backend-deployment/
  frontend/
    Dockerfile
    .env.sample
    qlockify-frontend-deployment/
  nginx/
  postgres/
  docker-compose.yml

Deployment Flow

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

docker compose up -d --build

The backend container runs:

• database migrations
• collectstatic
• Gunicorn startup

Domain and Routing

Configured domains:

• qlockify.ir
• www.qlockify.ir
• api.qlockify.ir

Behavior:

• 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

Before production startup:

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:

./nginx/certs/fullchain.pem
./nginx/certs/privkey.pem

The repository intentionally keeps only:

• ./nginx/certs/.gitkeep

Real certificate files are ignored by git.

Required Backend Environment

Set these in:

./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:

./frontend/qlockify-frontend-deployment/.env

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:

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:

docker compose up -d --build

Restart a subset:

docker compose up -d --build nginx backend frontend

Inspect running services:

docker compose ps

Follow logs:

docker compose logs -f nginx
docker compose logs -f backend
docker compose logs -f celery
docker compose logs -f celery-beat

Stop everything:

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.