Local setup

The Information below is for projects started with the backend template from June 2025. For earlier projects, review the following documentation

Our backend template uses Poetry, Docker, Just, and Django for local development and deployment. Follow the steps below to set up your environment.

📦 Prerequisites

Ensure you have the following installed:

📁 Project Structure Overview

justfile — Task runner using just
docker-compose.yml — Base Docker config
docker-compose.local.yml — Local overrides
docker-compose.stack.yml — Extended services (Celery, MinIO, Redis)
.env.example — Sample environment config
scripts/ — Helper shell scripts
src/ — Django application

🔧 Getting Started

Every comamnd in this tutorial assumes you're on the backend folder of the repository

There are two ways to run this locally:

With all auxiliary services (Minio, Firebase, Redis, Postgres)
Only the core django app (Django, Celery, Celery beat, Nginx)

Using the second option means you have to provide the values for environment variables of those services yourself.

By default, all the services are run. If you'd like to disable this, set USE_FULL_STACK=false in your shell environment.

If there's only one or two services you must use from the auxiliary options, run the full stack. The auxiliary services should not hog your resources

Now, onto the setup.

1. Install dependencies

This is not actually needed if you're running docker, but it makes autocomplete work in teh code editor.

poetry install

2. Create your environment file

Copy the example .env and customize it:

cp .env.example .env

Ensure sensitive values like SECRET_KEY are set. Please read the comments in the example .env carefully for your use case!

3. Start the app

If everything looks right with your environment, run:

just postbuild

This will do a few things:

Create the database on the specified host if it does not exist
Create and Run migrations
Run initversions, and create a django superuser
Ensure existence of the local s3 bucket if minio credentials are defined
Run collectstatic so the admin works

just start

This will spawn a few docker containers

Nginx pointing to django
Django
Celery
Celery beat
Redis
Minio (a local s3 of sorts)
A firebase emulator
Postgres

See the url's below for where things should be accessible

4. (Optional) Using aws credentials

Firstly, ensure you have setup an IAM user on your local aws cli. The name of the iam user must match the one specified in the justfile variable AWS_PROFILE.

The template has the capability to run docker containers as if on the AWS instance. To do this, it pulls the necessary iam role from pulumi. In order to use this capability, add a .pulumi_pass file to the iac/ directory. It must contain the project's passphrase, which can usually be found in 1password.

This means all secrets will be pulled from Parameter Store.

🌍 URLs

Service	URL
Django	http://localhost:8000
MinIO UI (s3 browser)	http://localhost:8901

Handling secrets

src/core/secrets.py has a utility function for retrieving secrets from AWS's parameter store.

Ideally, you'll store all your project secrets there for top notch security. If using parameter store is not an option at the moment, change the logic in secrets.py to your provider of choice, or simply use the environment variable fallback (search for any call to secret in the codebase for an example of this)

🛠️ In Case You’re Having Problems Running

If you run into issues during setup, check the following:

Copy the .env file before running any commands.
Delete the backend/.aws folder before running just postbuild.
If you need to create a new user in AWS, create it under the devops group.
Make sure the .pulumi_pass file is inside the iac/ directory and contains the correct credentials.
Credentials can be verified in 1Password.
Verify your AWS credentials are correct by checking:
```
code ~/.aws/credentials
```
If you are encountering a very unusual error, you can try deleting the local database. To do this:
- Stop Docker using just stop.
- Run rm -rf ./backend/_storage (this will drop your database).
- Run just postbuild.
- Then just start

FAQ

NGINX 503 on localhost

It's likely you tried to hit the django server before it had started. If a reload doesn't work, change anything in the url to force nginx to reload.

Otherwise, there might be something wrong with django's setup. Use the tail command described below or look into the django container logs in docker.

How do I add a package?

poetry add package-name
just install # Syncs to docker

Or for a dev dependency

poetry add --group dev package-name
just install # Syncs to docker

How can i generate a migration?

just makemigrations

I'm on windows and `command` doesn't work

This was not tested or made with Windows in mind. Everything should work on macOS or Linux though. Either use WSL or try to diagnose the issue on windows (likely a script or something in the justfile) and see if there's a workaround.

"Docker daemon not running" error

Run docker. Also set it to run when your computer starts

⚙️ Common Commands

Command	Description
`just start`	Start services
`just stop`	Stop services
`just exec`	Run a script in the existing django container
`just run "..."`	Run one-off command in Django container without starting it
`just tail`	Stream Django logs
`just attach`	Attach to Django container
`just migrate`	Apply DB migrations
`just makemigrations`	Create migrations
`just collectstatic`	Collect static files
`just shell`	Open Django shell
`just ssh`	Open a sheel in the Django container
`just export_env`	Export env vars (via `scripts/export_env.sh`)
`just deploy`	Deploy to Elastic Beanstalk
`just pulumi`	Run Pulumi in `iac/` directory
`just tail_beanstalk`	Tails logs from elastic beanstalk
`just exec_beanstalk`	Executes a command on elastic beanstalk
`just ssh_beanstalk`	Opens a shell inside of elastic beanstalk's docker container
`just clonedb`	Clone the database from AWS
`just test <module>`	Run tests for module. Omit module to run all tests

🐍 Using Poetry Locally (Optional)

You can run the app locally with Poetry instead of Docker:

poetry install
poetry shell
cp .env.example .env
python manage.py migrate
python manage.py runserver

🐳 Docker Compose (Manual)

Manual Docker Compose command:

docker compose --env-file .env \\
  -f docker-compose.yml \\
  -f docker-compose.local.yml \\
  up

Or use the just wrapper:

just compose up

📝 Notes

AWS credentials for Pulumi or S3 will be loaded automatically via get_instance_role before relevant commands. If pulumi is not configured, pulling these credentials will fail and AWS services will not work.
Adjust port variables in .env to avoid conflicts on your machine.
The default admin credentials are set via ADMIN_ID and ADMIN_PASS in .env.
Hot reload should work in the docker container just as it does on your machine.
If you'd like to reference ports on your machine from inside the docker container, use the host host.docker.internal.
- eg. to use a db on your machine instead of docker's POSTGRES_URL=postgres://postgres:Codeleap123@host.docker.internal:5432/template

📤 Deployment

To deploy to Elastic Beanstalk (if configured):

just deploy

Happy coding! 🚀

📦 Prerequisites​

📁 Project Structure Overview​

🔧 Getting Started​

1. Install dependencies​

2. Create your environment file​

3. Start the app​

4. (Optional) Using aws credentials​

🌍 URLs​

Handling secrets​

🛠️ In Case You’re Having Problems Running​

FAQ​

NGINX 503 on localhost​

How do I add a package?​

How can i generate a migration?​

I'm on windows and command doesn't work​

"Docker daemon not running" error​

⚙️ Common Commands​

🐍 Using Poetry Locally (Optional)​

🐳 Docker Compose (Manual)​

📝 Notes​

📤 Deployment​