Local Development Setup (Recommended) - CosmosTUe/Cosmos GitHub Wiki

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 Desktop must be installed and running before you begin
  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 Python (Pipenv) and Node.js dependencies
  • Running database migrations
  • Creating a default superuser

Wait for the terminal to display: SETUP FINISHED!

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