Chakra is a Component Content Management System (CCMS) built for IIT Roorkee. It enables editors to build pages using UI-kit components, generates XML representations, and renders/serves websites using a transpiler + backend services.
This repository (chakra-docker) is the Docker + orchestration layer for running the Chakra stack locally (and as a base for deployment): Postgres, RabbitMQ, Memcached, Django backend (Gunicorn + Daphne + Celery), Next.js frontend, and Nginx config templates.
chakra-backend(Django): APIs, auth/permissions, file manager, XML/HTML workflows. Runs Gunicorn (HTTP) + Daphne (ASGI) + Celery (worker) undersupervisord.chakra-frontend(Next.js): Editor/UI to build pages and generate XML.chakra-core(Scala + Python/Flask): Transpiler and supporting services for turning XML into static HTML (and some dynamic component support).- Postgres: Primary database.
- RabbitMQ: Message broker (Celery).
- Memcached: Caching.
- Nginx templates: Reverse proxy config templates under
nginx/(not started bydocker-compose.ymlin this repo).
Upstream repos are cloned into this repo’s ./codebase/ directory by scripts in this repo.
docker-compose.yml: Brings up database, backend, frontend, memcached, rabbitmq (host-networked).scripts/clone.sh: Cloneschakra-core,chakra-backend,chakra-frontend,chakra-libraryinto./codebase/.scripts/build/*: Builds Docker images and generates env files from stencils.postgres/,rabbitmq/,memcached/,django/,next/: Docker build contexts.nginx/: Nginx config templates (TLS server block + upstreams + includes).chakrabackup-script/: Backup scripts (seechakrabackup-script/README.md).
- Docker + Docker Compose
- git
- Node.js + yarn (used by
scripts/build/next.shto install deps before building the image) - Python 3.9 (required) (for running
chakra-coreFlask server locally inscripts/prod.sh/scripts/development.sh)
If you work on the transpiler itself:
- Scala + sbt (see
chakra-core/README.mdonce cloned)
From the root of this repo:
./scripts/clone.shThis creates:
codebase/
chakra-backend/
chakra-frontend/
chakra-core/
chakra-library/
This repo uses “stencil” env files that you copy/fill once.
Generate postgres/database.env from postgres/database_stencil.env:
bash ./scripts/build/postgres.shGenerate rabbitmq/message_broker.env from rabbitmq/message_broker_stencil.env:
bash ./scripts/build/rabbitmq.shInside the cloned backend repo, create:
codebase/chakra-backend/chakra_backend/.env
Start from the backend stencil:
cp codebase/chakra-backend/chakra_backend/stencil.env codebase/chakra-backend/chakra_backend/.envThen edit values in .env (database creds, oauth creds, core server URL, allowed hosts, cache + rabbitmq creds, etc.). The stencil lives here:
codebase/chakra-backend/chakra_backend/stencil.env
Create:
codebase/chakra-core/.env
From:
cp codebase/chakra-core/stencil.env codebase/chakra-core/.envchakra-core/.env needs:
SECRET_FLASKCODEBASE_PATH(path to thecodebase/directory)
Install Chakra core Python dependencies (used by flask run):
cd codebase/chakra-core
python3 -m venv chakra-core-env
source chakra-core-env/bin/activate
pip install -r requirements.txt
cd ../../From repo root:
bash ./scripts/build/postgres.sh
bash ./scripts/build/rabbitmq.sh
bash ./scripts/build/memcached.sh
bash ./scripts/build/django.sh
bash ./scripts/build/next.shThis repo provides a convenience script that:
- starts all Docker services via Compose
- then runs
chakra-core(Flask) locally
./scripts/prod.shFor core-only development (starts just Postgres + chakra-core):
./scripts/development.shIf you prefer manual Compose:
CURRENT_UID="$(id -u):$(id -g)" docker-compose up -d
# or (Compose v2)
CURRENT_UID="$(id -u):$(id -g)" docker compose up -dAll services in docker-compose.yml use network_mode: host, so they bind directly on your host.
Common ports:
- Postgres:
5432 - Backend (Gunicorn):
8000 - Backend (Daphne / ASGI):
8001 - Frontend (Next.js):
3000 - RabbitMQ (AMQP):
5672(and Management UI is typically15672) - Memcached:
11211 - Chakra core (Flask):
5000(default Flask port)
Because the backend runs in Docker, run management commands inside the container:
docker compose exec chakra-backend bash
source chakra_backend/.env
python3 manage.py makemigrations
python3 manage.py migrate
python3 manage.py createsuperuserAfter running migrations, seed the required root folders (HTML, XML, JoshUsers) and the full WEBSITE_NODE_STRUCTURE (all departments, sections, etc.) using the seed_website management command.
Local (non-Docker) setup:
cd codebase/chakra-backend
source chakra_backend/.env
# Seed root folders + full website node tree only
./chakra-backend-env/bin/python manage.py seed_website
# Seed root folders + full tree + a TestDept XMLPage (useful for dev/preview testing)
./chakra-backend-env/bin/python manage.py seed_website --test-pageInside Docker:
docker compose exec chakra-backend bash
source chakra_backend/.env
python3 manage.py seed_website
# or with test page:
python3 manage.py seed_website --test-pageThe command is idempotent — safe to re-run if folders already exist on disk or in the DB.
The --test-page flag additionally creates:
XML/TestDept/index.xmlandHTML/TestDept/index.htmlwith a minimal valid chakra-core XML page- Corresponding
File,Page,XMLPage, andMenuDB records so the preview endpoint works immediately
If you use legacy Compose:
docker-compose exec chakra-backend bashImportant: source the backend .env before running manage.py.
The production-ish container runs next/start.sh, which runs yarn build only when the checkout changed since the last build, then yarn start. For local development, the frontend repo also ships a helper that runs Next.js dev mode inside Docker on a high port:
cd codebase/chakra-frontend
./scripts/run-dev.sh -d 60000 -p 61000If you change Scala transpiler code in codebase/chakra-core, you’ll commonly need to re-pack:
cd codebase/chakra-core
./pack.shIf you’re running everything on your host (instead of Docker), the rough sequence is:
- Backend
- Create
chakra-backend/chakra_backend/.env pip install -r requirements.txt- Setup Postgres user/db (example: user
naruto, dbchakradb) - Run
python3 manage.py makemigrations && python3 manage.py migrate - Create admin user:
python3 manage.py createsuperuser - Run generator scripts (example mentioned:
node_gen_util.py) - Run:
python3 manage.py runserver 60000
- Create
- Celery
celery -A chakra_backend worker --loglevel=INFO
- Frontend
./scripts/run-dev.sh -d 60000 -p 61000
- Chakra core
- Create venv, install requirements, set
.env, runflask run
- Create venv, install requirements, set
- Services
- Start Memcached + RabbitMQ + Postgres
Note: changing pg_hba.conf auth to trust is convenient for local dev but unsafe on shared machines. Prefer proper local passwords / md5/scram auth where possible.
In production, updates are usually applied via Jenkins jobs. If Jenkins is unavailable, use the manual commands below as a fallback.
- Avoid putting credentials in shell history: prefer Jenkins credentials bindings, deploy keys, or a GitHub token injected as an env var in CI.
- Be careful with
git reset --hard: it will wipe any server-local changes (for Chakra core this often includes secrets/config likecomponents.json).
- Preferred: run the existing Jenkins job for
chakra-backend. - Manual fallback (from the
chakra-dockerrepo root on the server):
cd /path/to/chakra-docker/codebase/chakra-backend &&
git pull "https://${USER}:${PW}@github.com/IMGIITRoorkee/chakra-backend.git" master --rebase &&
docker restart chakra-docker_chakra-backend_1- Preferred: run the existing Jenkins job for
chakra-core. - Manual fallback (use with caution; see note about
components.jsonabove):
cd /path/to/chakra-docker/codebase/chakra-core &&
source chakra-core-env/bin/activate &&
git fetch "https://${USER}:${PW}@github.com/IMGIITRoorkee/chakra-core.git" &&
git reset --hard FETCH_HEAD &&
./pack.shIf Chakra core changes don’t reflect (or Flask is stuck), restart the Flask process (often running in a tmux session). If needed, stop it with Ctrl+C and start it again so it binds on port 5000:
flask run --host=0.0.0.0 --port=5000- Preferred: run the existing Jenkins job for
chakra-frontend. - Manual fallback:
cd /path/to/chakra-docker/codebase/chakra-frontend &&
git pull "https://${USER}:${PW}@github.com/IMGIITRoorkee/chakra-frontend.git" master --rebase &&
docker restart chakra-docker_chakra_frontend_1- Preferred: run the existing Jenkins job for
chakra-library. - Manual fallback (repo location may differ per server):
cd /path/to/chakra-library &&
sudo git pull origin staging --rebaseFrom the chakra-docker repo root on the server:
docker-compose up -d
# or (Compose v2)
docker compose up -d-
./codebasemissing: run./scripts/clone.sh. -
Permissions issues on bind mounts: bring up compose via
./scripts/prod.shor setCURRENT_UID="$(id -u):$(id -g)"when runningdocker-compose. -
Backend can’t talk to core: confirm
SERVER_URLin backend.envpoints to your Flask server (typicallyhttp://127.0.0.1:5000). -
Ports already in use: because containers use host networking, stop conflicting services or change ports in the upstream app configs.
-
macOS
sed -ierrors when running build scripts: some scripts expect GNUsed. Installgnu-sed(Homebrew) and usegsed, or run the build steps on Linux. -
More troubleshooting: see chakra-troubleshooting.md.