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
backend traffic is served from qlockify.ir under /api and /admin
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

Behavior:

www.qlockify.ir redirects to qlockify.ir
http redirects to https
frontend is served from qlockify.ir
backend traffic is proxied from qlockify.ir/api and qlockify.ir/admin

Before production startup:

Point DNS records for qlockify.ir and www.qlockify.ir to the server.
Make sure 80 and 443 are open on the server firewall.
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=qlockify.ir,www.qlockify.ir
CORS_ALLOWED_ORIGINS=https://qlockify.ir,https://www.qlockify.ir
CSRF_TRUSTED_ORIGINS=https://qlockify.ir,https://www.qlockify.ir
BASE_URL=https://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://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=/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

Backup the deployed data:

chmod +x ./scripts/backup.sh
./scripts/backup.sh

By default, backup archives are written to ./backups/. Each archive contains:

PostgreSQL data from the db service
media files from the Docker media volume
.env files from the deployment, backend, and frontend projects

Restore a backup archive on another machine:

chmod +x ./scripts/restore.sh
./scripts/restore.sh ./backups/qlockify-backup-YYYYMMDD-HHMMSS.tar.gz
docker compose up -d --build

Restore is destructive for the database by default. To restore only part of an archive, use:

RESTORE_SKIP_DB=1 ./scripts/restore.sh ./backups/qlockify-backup-YYYYMMDD-HHMMSS.tar.gz
RESTORE_SKIP_MEDIA=1 ./scripts/restore.sh ./backups/qlockify-backup-YYYYMMDD-HHMMSS.tar.gz
RESTORE_SKIP_ENV=1 ./scripts/restore.sh ./backups/qlockify-backup-YYYYMMDD-HHMMSS.tar.gz

CI/CD with Gitea Actions

This repository now ships with a Gitea Actions deployment workflow in:

.gitea/workflows/deploy.yml

The backend and frontend repositories each ship with their own workflow files:

backend: .gitea/workflows/backend.yml
frontend: .gitea/workflows/frontend.yml

Deployment behavior:

backend repo push to main: runs backend CI, then updates the backend checkout on the server and rebuilds backend, celery, and celery-beat
frontend repo push to main: runs frontend lint/build, then updates the frontend checkout on the server and rebuilds frontend
deployment repo push to main: validates deployment files, then updates the deployment checkout on the server and rebuilds nginx plus the app services

The remote deploy entrypoint is:

./scripts/deploy.sh

One-Time Server Bootstrap

Before Actions can deploy automatically, make sure the server is prepared once.

Clone all three repositories on the server into the expected layout:

~/qlockify-deployment
~/qlockify-deployment/backend/qlockify-backend-deployment
~/qlockify-deployment/frontend/qlockify-frontend-deployment

Make sure the server can git fetch all three repositories non-interactively.

Recommended approach:

add a deploy SSH key on the server
add the public key to Gitea as a deploy key or a machine-user SSH key
switch the server-side git remotes to SSH URLs

Pull the latest deployment repo once so the server has scripts/deploy.sh.
Make the deploy script executable:

chmod +x ~/qlockify-deployment/scripts/deploy.sh

Make sure the deploy user can run Docker Compose on the server.

Gitea Runner Setup

Gitea Actions requires a trusted runner. Gitea's official docs describe the runner and label model here:

Actions overview: https://docs.gitea.com/usage/actions/overview
Act Runner: https://docs.gitea.com/usage/actions/act-runner

Recommended label setup for this project:

qlockify-python:docker://python:3.14-bookworm
qlockify-node:docker://node:22-bookworm
qlockify-deploy:docker://ubuntu:24.04

Example non-interactive runner registration:

./act_runner register \
  --no-interactive \
  --instance https://git.amiirkhl.ir \
  --token <runner_registration_token> \
  --name qlockify-runner \
  --labels "qlockify-python:docker://python:3.14-bookworm,qlockify-node:docker://node:22-bookworm,qlockify-deploy:docker://ubuntu:24.04"

Then start the runner daemon:

./act_runner daemon

Gitea Secrets

Create these Actions secrets either at the Qlockify organization level or per repository.

SSH_PRIVATE_KEY
- private key used by the workflow to SSH into the deployment server
SSH_KNOWN_HOSTS
- output of:

ssh-keyscan -H <your-server-hostname-or-ip>

Do not create GITEA_TOKEN manually. Gitea provides a built-in job token and exposes it as ${{ secrets.GITEA_TOKEN }}. See:

https://docs.gitea.com/usage/actions/token-permissions

Gitea Variables

Create these Actions variables in the Gitea UI:

DEPLOY_HOST
DEPLOY_PORT
DEPLOY_USER
DEPLOY_PATH
DEPLOY_BRANCH
BACKEND_BRANCH
FRONTEND_BRANCH

Suggested values for your current server layout:

DEPLOY_HOST=h9arjloaye
DEPLOY_PORT=22
DEPLOY_USER=ubuntu
DEPLOY_PATH=/home/ubuntu/qlockify-deployment
DEPLOY_BRANCH=main
BACKEND_BRANCH=main
FRONTEND_BRANCH=main

Gitea variables are available in workflows through ${{ vars.NAME }}. Gitea documents that here:

https://docs.gitea.com/usage/actions/actions-variables

Recommended UI Setup

If all three repositories live under the same Qlockify organization, the cleanest setup is:

Add one organization-level runner to Qlockify
Add organization-level variables for the shared deploy target
Add organization-level secrets for the SSH key and known hosts

This keeps the three repositories consistent and avoids copying the same values three times.

First Deploy Check

After creating the runner, variables, and secrets:

push the deployment repository first
confirm the deployment workflow succeeds
then push backend or frontend changes and confirm their repo-specific workflows deploy only the affected services

If a workflow fails on the server step, first check:

runner logs
repository Actions logs
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f celery
docker compose logs -f celery-beat

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.

README.md

Qlockify Deployment

Related Repositories