Setting up your development environment#

Ready to contribute? Here’s how to set up your development environment for CHORAS. We always recommend creating a fork of the repository you would like to contribute to. This allows you to freely develop and test your changes without affecting the main repository until you’re ready to submit a pull request.

Fork the repository you want to contribute to (e.g., choras-org/backend). Please make sure that you enable giving maintainers access to your fork, so we can help you if you run into issues.
Clone your forked main repository to your local machine:
```
git clone https://github.com/<your-username>/CHORAS
cd CHORAS
```
If you only want to contribute to the frontend/backend, you can instead clone the original repository.
Navigate into the CHORAS directory and initialize the three (frontend-v2, backend, and simulation-backend) submodules:
```
cd CHORAS
git submodule update --init --recursive
```
Update the remote URL of the submodules to point to your forked repositories. For example, for the backend submodule:
```
cd backend
git remote set-url origin https://github.com/<your-username>/backend
```
If you prefer to use SSH instead of HTTPS, the command would be:
```
git remote set-url origin git@github.com:<your-username>/backend.git
```
Optionally, you can also set up the upstream remote to keep your fork in sync with the original repository:
```
git remote add upstream https://github.com/choras-org/backend
```
Finally, create a new branch for your changes:
```
git checkout -b my-feature-branch
```
Install dependencies
```
uv sync --group dev
```
Now you’re ready to start developing. Follow the instructions on the next page to start implementing an interface for your simulation method.

Running the Backend Locally#

From the backend directory:

Create or update the .env file:

# APP configuration
APP_NAME=CHORAS Backend
APP_ENV=develop

# Flask configuration
FLASK_APP=app:app
FLASK_DEBUG=true
APP_SETTINGS_MODULE=config.DevelopConfig
APP_TEST_SETTINGS_MODULE=config.TestingConfig

FLASK_RUN_HOST=0.0.0.0
FLASK_RUN_PORT=5000

# Database (optional — omit to use the default SQLite3 database)
DATABASE_URL=postgresql://db_user:db_password@localhost/db_dev
DATABASE_TEST_URL=postgresql://db_user:db_password@localhost/db_test

Create database tables and seed initial data:
```
flask create-db
```
Run the development server:
```
flask run
```

Start the Celery worker (only needed if using async jobs):

celery -A app.celery worker --loglevel=info -P eventlet

Flask CLI Reference#

Create all tables and seed initial data:
```
flask create-db
```
Delete all tables:
```
flask drop-db
```
Reset the database (drop + recreate + seed):
```
flask reset-db
```

Database Migrations#

The backend uses Flask-Migrate for schema migrations.

Initialise the migration repository:
```
flask db init
```
Generate a migration version:
```
flask db migrate -m "Description"
```
Apply the migration:
```
flask db upgrade
```