Local development setup¶

Note

This page is the canonical runbook, maintained at guides/LOCAL_DEV_SETUP.md in the repository root. It is transcluded here so the docs site stays in sync. If the content looks out of date, edit the source file in guides/, not this page.

This guide takes a developer from a clean machine to a running Midsummer V2 instance at http://localhost:8082/.

Midsummer is a multi-app Django + Angular suite. In local dev you run the Python/Django backend natively (in a virtualenv) while PostgreSQL and MinIO (S3-compatible storage) run in Docker, and the Angular frontends are built into Django static files.

Linux/macOS only. Windows is not supported (see README.md).

1. Prerequisites¶

Tool	Version	Notes
Python	3.12+	Production Docker image uses 3.14; 3.12 is fine locally
Node.js	24.x	Required to build the Angular frontends
Docker (or Podman)	recent	Runs PostgreSQL 17 + MinIO
git	any

You also need a working pip/venv and, on macOS, the Xcode command-line tools (xcode-select --install) because the UI build scripts use rsync and sed.

2. Get the code¶

git clone <repo-url> midsummer
cd midsummer

All commands below assume you are in the project root.

3. Configure environment¶

Copy the example environment file and adjust as needed:

cp .env.example .env

The defaults are already wired for local development (Postgres user midsummer, MinIO on localhost:9000, debug on). The one value worth randomizing is the Django secret:

# Generate and drop a fresh SECRET_KEY into .env, e.g.
python -c "import secrets; print(secrets.token_urlsafe(50))"

Key variables (all pre-set by .env.example):

MIDSUMMER_PROD=false — keeps you in dev mode. Always leave this false locally.
DB_* / POSTGRES_* — PostgreSQL credentials used by both Django and the Docker container.
S3_* / S3_ENDPOINT_URL — points Django at the local MinIO container.

Do not commit .env (it is gitignored).

4. Set up the Python backend¶

Create a virtualenv in the repo (this is the layout the project’s tooling expects) and install dependencies:

python3 -m venv .venv
./.venv/bin/pip install --upgrade pip
./.venv/bin/pip install -r requirements.txt

Tip: either prefix every python/manage.py command with ./.venv/bin/ or activate the environment first (source .venv/bin/activate) so the remaining commands in this guide resolve to the right interpreter.

5. Install frontend dependencies¶

There are two Angular projects: ui/ (the main event app) and tenantui/ (the tenant/admin app). The helper script installs both:

./install-frontend-deps.sh

Kendo UI license: the ui build activates a Kendo license (npx kendo-ui-license activate). If you do not have a Kendo license key available, the build may emit license warnings. Reach out to the team for a key if builds fail on Kendo components.

6. Start support services (PostgreSQL + MinIO)¶

Bring up the database and object storage in the background. The midsummer-minio-init one-shot container creates the storage bucket if it does not already exist:

docker compose up midsummer-db midsummer-minio midsummer-minio-init -d

Wait a few seconds, then confirm both are healthy:

docker compose ps

You should see midsummer-db and midsummer-minio running.

Redis / Celery: Celery is configured against redis://localhost:6379/0 (see .env). Redis is not currently part of docker-compose.yaml, so background tasks will not run out of the box. If you need Celery locally, run a Redis container separately, e.g. docker run -d -p 6379:6379 --name midsummer-redis redis:7.

7. Initialize the database¶

Run the shared schema migrations:

python manage.py migrate_schemas --shared

Now seed the application. There are two supported paths — pick one.

Option A — Barebone interactive setup (recommended for real dev)¶

This creates a fresh default tenant (defaultdev), a default event, and a superuser that you choose. It will prompt you for an email, a password, and optionally a Stripe key:

python manage.py init_seed_data
python manage.py all_tenants_command event__generate_properties

The convenience script ./dev-reset-env.sh does steps 6 + 7 for you in one go (it tears down the Docker volumes first, so it wipes existing data).

Option B — Pre-seeded simulated event (fastest to a working login)¶

This loads dev/seed.sql, which ships with a ready-made tenant, event, and admin user:

./dev-bootstrap-start.sh   # wipes + rebuilds the DB volume and imports seed.sql

Use these credentials after it finishes:

URL: http://localhost:8082/
User: dev@midsummer.cloud
Password: goMS2026#

8. Build the frontend into Django static files¶

The Angular apps are compiled and copied into front/static/ and tenant/static/ so Django can serve them:

./render-ui-elements.sh && ./render-tenant-ui-elements.sh

This is the slowest step (full Angular build of both projects). You only need to re-run it when frontend code changes.

9. Run the dev server¶

Start the Hypercorn ASGI server on port 8082:

export MIDSUMMER_PROD=false
./entrypoint.sh

entrypoint.sh runs collectstatic, re-applies shared migrations, and then launches Hypercorn. Open the app:

http://localhost:8082/

Verification checklist¶

docker compose ps shows midsummer-db and midsummer-minio up.
python manage.py migrate_schemas --shared exits cleanly.
http://localhost:8082/ loads the Midsummer UI.
You can log in with the credentials from your chosen seed path.

Day-to-day workflow¶

# Start support services (if they aren't already running)
docker compose up midsummer-db midsummer-minio -d

# Activate your env
source .venv/bin/activate

# Run the dev server
export MIDSUMMER_PROD=false
./entrypoint.sh

Convenience scripts¶

Script	What it does
`./dev-reset-env.sh`	Wipe DB/MinIO volumes, bring services up, migrate, and run the interactive `init_seed_data` (Option A, end-to-end).
`./dev-bootstrap-start.sh`	Wipe + rebuild volumes and import the simulated-event seed (Option B, data only — does not start the server).
`./dev-launch.sh`	Bring up DB + MinIO, rebuild the main `ui` frontend, and start the dev server.
`./install-frontend-deps.sh`	`npm install` for both `ui/` and `tenantui/`.
`./render-ui-elements.sh`	Build `ui/` and copy it into Django static.
`./render-tenant-ui-elements.sh`	Build `tenantui/` and copy it into Django static.

Full rebuild helper (the canonical run command)¶

When in doubt, this single invocation rebuilds both frontends and starts the server:

export MIDSUMMER_PROD=false && ./render-ui-elements.sh && ./render-tenant-ui-elements.sh && ./entrypoint.sh

Common tasks¶

Reset everything back to a clean slate:

docker compose down
docker volume rm midsummer_midsummer-db midsummer_midsummer-minio
./dev-reset-env.sh

Rebuild only the frontend (after editing Angular code):

./render-ui-elements.sh && ./render-tenant-ui-elements.sh

Add a Stripe key to the seeded event: re-run python manage.py init_seed_data (it prompts), or use python manage.py event__add_stripe_key.

Troubleshooting¶

relation ... does not exist / migration errors: the shared schema is not migrated. Run python manage.py migrate_schemas --shared (note: it is migrate_schemas, not migrate, because of django-tenants).
Port 8082 already in use: another Hypercorn/Django process is running. Find and stop it, or check that you didn’t already start the server.
Static files 404 / UI looks unstyled: you skipped the render step. Run ./render-ui-elements.sh && ./render-tenant-ui-elements.sh, then python manage.py collectstatic --noinput.
MinIO / S3 errors on upload: confirm the MinIO container and the midsummer-minio-init bucket-creation job both succeeded (docker compose logs midsummer-minio-init).
Kendo license warnings during UI build: see the note in section 5.
Celery/background tasks silently not running: Redis is not running locally (see the Redis note in section 6).

Port reference¶

Port	Service
8082	Midsummer app (Hypercorn ASGI)
5432	PostgreSQL
9000	MinIO S3 API
9001	MinIO web console
6379	Redis (Celery broker — run your own)