Local Development — Running on Your Computer

Prerequisites

  • Python 3.11+ (python --version)
  • Git (git --version)

Step 1: Get the Code

git clone [your-repository-url]
cd dsl_15_simple_node

Step 2: Set Up a Virtual Environment

python -m venv venv

# Mac/Linux:
source venv/bin/activate

# Windows:
venv\Scripts\activate

You'll see (venv) in your prompt.

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Run the Application

# Use your application's name, e.g. container_tracking, road_maintenance
python server/run.py <app_name>

Then open: http://localhost:<port> — each app's port is set in applications.yaml

The database is created automatically on first run — there is nothing to initialise manually.

To list all available apps:

python server/run.py --list

To run the control panel (manages multiple apps at once):

python server/control_panel.py
# Opens at http://localhost:5000

Stopping the Server

Press Ctrl+C in the terminal.

Common Commands

# Run an application (replace <app_name>, e.g. container_tracking, road_maintenance)
python server/run.py <app_name>

# View the database directly
sqlite3 apps/<app_name>/data/<app_name>.db
.tables
.quit

# Regenerate all JSON/model files from the DSL schema
python -m codegen.cli all <app_name>

Troubleshooting

"Address already in use"

Port 5016 is taken by another process.

# Mac/Linux — find and kill it:
lsof -i :5016 | grep LISTEN | awk '{print $2}' | xargs kill

# Windows:
netstat -ano | findstr :5016
taskkill /PID <PID> /F

"Module not found"

pip install -r requirements.txt

Make sure your virtual environment is activated ((venv) in prompt).

"Database is locked"

The app is probably already running in another terminal. Stop that instance first (Ctrl+C), then restart.

Database tables missing

Just start the app — SQLAlchemy creates all tables on first run.

Environment Variables (optional)

Create a .env file in the project root if needed:

FLASK_DEBUG=1           # Auto-reload on code changes
SECRET_KEY=change-me    # Session security

Google OAuth credentials (if using Google login) go in .env too — never commit this file.

See Environment Variables for the full list.

Next Steps