Two kinds of work: the mechanical renames, which one script does, and the decisions, which it cannot make for you. Do both before the first release — renaming a bucket, a database or a registry image later means migrating data.
# GitHub → "Use this template" → clone, then:
scripts/new_project.sh # derives names from `git remote origin`
scripts/new_project.sh --slug acme-shop --owner acme --name "Acme Shop" # or explicit
git diff && git commit -am "[INIT] start acme-shop from project-template"
make initWhat it rewrites, consistently, everywhere (compose files, .env.example, settings,
pyproject.toml + uv.lock, package.json + lockfile, index.html, docs):
| Template identifier | Becomes | Used for |
|---|---|---|
igorkhaylov/project-template |
<owner>/<repo> |
ghcr.io/<owner>/<repo>/{backend,frontend} image defaults |
project-template |
<slug> |
Compose project name (containers, volumes, network), MinIO bucket/user, package names |
project_template |
<slug> with _ |
Postgres database and user |
ProjectTemplate |
PascalCase slug | DJANGO_APP_NAME (admin titles, API title), <title> |
Project Template |
--name or title-cased slug |
README heading |
8050 (APP_PORT) |
--port or a stable hash of the slug in 8100-8999 |
the stack's host port in .env.example, compose defaults, the Vite proxy target and docs — distinct per project, so clones on one machine do not collide |
It is idempotent and never touches .env, .git, node_modules. If you had already run
make init, delete .env and run it again (it never overwrites an existing .env), or
edit PROJECT_NAME / APP_PORT / POSTGRES_* / MINIO_* by hand.
The one URL it leaves alone on purpose: the django-stdimage fork in
backend/pyproject.toml is a dependency, not a template identifier.
| Where | Decide |
|---|---|
CODEOWNERS |
replace @OWNER/backend-team / @OWNER/frontend-team with real teams or users |
LICENSE |
the template is MIT with the author's copyright line |
README.md |
first paragraph; keep the operational sections, they stay true |
.github/workflows/deploy.yml |
GitHub Environments prod / dev with the SSH + GHCR secrets (deploy.md); set the repo variable AUTO_DEPLOY=true when you want deploy-on-merge (until then the auto job shows as skipped, which is expected) |
.vscode/settings.json |
optional: spell-check dictionary only |
| Setting | File | Template default |
|---|---|---|
TIME_ZONE |
backend/config/settings/base.py |
Asia/Tashkent |
LANGUAGE_CODE, LANGUAGES, MODELTRANSLATION_* |
base.py |
en default + ru; keep modeltranslation first in INSTALLED_APPS. Changing the language set also changes the (en|ru) prefix in ops/nginx/*.conf and frontend/vite.config.ts |
REST_FRAMEWORK |
third_party.py |
closed by default: DEFAULT_PERMISSION_CLASSES = IsAuthenticated, and no authentication class is enabled, so every non-public endpoint answers 403 until you choose one (session for a same-origin SPA, JWT, …) in DEFAULT_AUTHENTICATION_CLASSES. Public endpoints say AllowAny explicitly and are listed in PUBLIC_API_ROUTES (backend/tests/test_api_access.py); the suite fails if the two disagree. No throttling is configured: add DEFAULT_THROTTLE_CLASSES before exposing login/registration endpoints. |
SPECTACULAR_SETTINGS (DESCRIPTION, VERSION, SERVE_PERMISSIONS) |
third_party.py |
placeholder description; Swagger UI requires admin login |
DATA_UPLOAD_MAX_MEMORY_SIZE / FILE_UPLOAD_MAX_MEMORY_SIZE |
base.py |
10 MB; the edge allows 500 MB bodies on backend paths (client_max_body_size) |
| Celery limits, queues, concurrency | backend/config/celery.py, compose celery command |
3 h task limit, single celery queue, 2 processes |
GUNICORN_WORKERS |
.env |
2 — scale by replicas |
users.User is a custom AbstractBaseUser (username login, optional verified emails in
UserEmail). Before the first release:
- Activation.
is_activedefaults toFalse; nothing in the template activates a regular user (intended trigger: OTP/email verification, markedTODO(OTP)inusers/models.py). Implement the flow or flip the default. - Fields. Add/remove, then
make dev makemigrations. To start from a single clean initial migration, delete0001_initial.py, regenerate it,make dev down-v— only before the first deploy.test_migrations_in_syncfails the suite on any drift.
| Where | Decide |
|---|---|
frontend/index.html, public/favicon.svg |
title (already renamed) and icon |
frontend/src/pages/home/HomePage.tsx |
replace the starter screen; keep calls going through src/shared/api/client.ts; layers and naming in frontend/docs/architecture.md |
| libraries | Tailwind is in; router, data cache, forms, state, i18n are added per project — frontend/docs/architecture.md |
| Vite SPA vs Next.js | the default is a static SPA; the Next.js variant is documented in frontend/README.md |
APP_API_BASE_URL |
keep empty (same origin). Set it only if the API is served from a different host — then also set DJANGO_CORS_ALLOWED_ORIGINS |
| Feature | How to turn on |
|---|---|
| Firebase push notifications | firebase-admin is an extra: uv sync --extra push, add --extra push to every uv sync in backend/Dockerfile and Dockerfile.dev, put the service-account JSON in firebase_credentials/ (git- and docker-ignored), import common.firebase once at startup |
| Scheduled DB backups (prod) | COMPOSE_PROFILES=backup in the server's .env (backup.md) |
| WebSockets through the edge | commented location /ws/ block in ops/nginx/nginx.conf; add ws to the prefix lists |
| Debug toolbar | on in ENVIRONMENT=dev when the dev dependency group is installed; /__debug__/ |
| GitLab CI | not shipped; the GitHub workflows translate 1:1 (rules: changes: per component, GitLab Container Registry, Deploy Token for the server) |
ops/nginx/nginx.confdoes not setX-Forwarded-Proto. The external TLS proxy does; re-setting it here would create a redirect loop underSECURE_SSL_REDIRECT./healthz/and/readyz/are middleware, not URLs. They must answer beforeALLOWED_HOSTSvalidation (Kubernetes probes send the pod IP asHost).- Migrations are not in the web process.
release.shruns them once per deploy;entrypoint.shonly starts gunicorn. ENVIRONMENT=productionis rejected on purpose. Onlydev | test | stage | prod.- Static files live in the bucket, even in dev. No filesystem fallback;
collectstaticis what makes the admin render with CSS. - MinIO is not in
ops/compose/*.yml. One shared host container serves every project (make minio); prod points at managed storage. make dev updoes not serve HTTP. The backend container idles;make dev runstarts the server. The frontend dev server runs on the host (make fe-dev).api/openapi.yamlandfrontend/src/shared/api/schema.d.tsare generated. Never hand-edit;make api-schema.