Skip to content

Local Development Setup (Recommended)

Jump to bottom
Anas edited this page Oct 15, 2026 · 3 revisions

This project uses Docker and VS Code Dev Containers to standardize the development environment. This eliminates manual setup and ensures the project runs identically for every developer, on any OS.

1. Prerequisites

Ensure you have the following installed and configured:

  1. Docker, installed and running before you begin:
    • Docker Desktop (Windows, macOS, Linux), or
    • on macOS without Docker Desktop: brew install colima docker docker-compose and then colima start --cpu 4 --memory 6
  2. Visual Studio Code
  3. Dev Containers Extension extension installed in VS Code

2. Installation & Setup

Linux / macOS

  1. Clone the repository: You can use GitHub Desktop or this command: 
    git clone https://github.com/CosmosTUe/Cosmos.git
  2. Open the folder in VS Code.
  3. Click "Reopen in Container" in the bottom-right pop-up.
    • If the pop-up is missing, press F1 -> Dev Containers: Reopen in Container.

Windows

Do NOT clone this repository manually. It will result in an unusably slow environment. Instead, use the following VS Code feature:

  1. Open a new, empty VS Code window
  2. Press F1 (or Ctrl+Shift+P)
  3. Select: Dev Containers: Clone Repository in Container Volume
  4. Paste the repository URL: https://github.com/CosmosTUe/Cosmos.git

This process will set up an isolated, high-performance environment automatically.

3. First Run (Automated)

The first container build takes several minutes. A setup script runs automatically and handles:

  • Copying dev.secrets.json to /etc/secrets.json
  • Installing the exact Python (Pipenv) and Node.js dependency versions from the lock files
  • Running database migrations
  • Creating a default superuser

Wait for the terminal to display: SETUP FINISHED!

Next to the website, the container starts PostgreSQL 17 and Redis 7 (the versions production uses) and Mailpit.

4. Running the Server

  1. Press F5 (or click the Green Play button in the "Run and Debug" tab)
  2. Open http://localhost:8000 in your browser

Admin Login

You can access the Django admin interface to manage the database, create users, and perform administrative tasks.

  • URL: http://localhost:8000/admin/
  • Username: admin
  • Password: admin

Emails

The site never sends real email in development. Everything it sends (registration, password reset, ...) is caught by Mailpit at http://localhost:8025.

5. Before you open a pull request

GitHub checks every pull request with black, isort, flake8 and the test suite. Run the same checks in the container's terminal:

pipenv run black .
pipenv run isort .
pipenv run flake8 .
pipenv run python manage.py test

To have black, isort and flake8 run automatically on every commit, install the hooks once with pipenv run pre-commit install.

Pull requests go to the staging branch. After merging they are live on the staging site; see STAGING.md.

Troubleshooting

  • Starting over: F1 -> Dev Containers: Rebuild Container. The database lives in a Docker volume and survives a rebuild. To wipe it too, remove the cosmos_devcontainer_postgres_data volume (docker volume rm cosmos_devcontainer_postgres_data) and rebuild.
  • Port 8000 or 8025 already in use: something on your computer already uses that port (for example a local PostgreSQL). Stop it, or change the port on the left side in .devcontainer/docker-compose.yml.

Clone this wiki locally