Skip to main content

​
Running the Stack

This guide shows you how to start all the Maybern services and access your local development environment.

​
Required Services

Maybern consists of several services that need to run together:
ServicePortDescription
Django Server8000Main backend API
Celery Workers-Async task processing
AI Server8001AI chat functionality (optional)
Frontend3000React web application

​
Start the Backend

1

Activate the virtual environment

From the backend/ directory:
source .venv/bin/activate
2

Start Celery workers

Open a new terminal tab and run:
just run-celery
Celery workers handle async operations like PDF generation, calculations, and event processing.
3

Start the Django server

In another terminal tab:
just run-server
The server should start at http://localhost:8000. You’ll see log output indicating the server is ready.

​
Start the AI Server (Optional)

If you need AI chat functionality, start the AI server in a separate terminal: 
just run-server-ai
The AI server runs on port 8001 and provides WebSocket endpoints for the chat interface.
The AI server requires API keys for LLM providers (Anthropic, OpenAI, etc.). Check your .env file for the required configuration.

​
Start the Frontend

From the frontend/ directory, start the React development server: 
pnpm start
Open http://localhost:3000

​
Log In to Your Development Instance

1

Navigate to the login page

Open your browser to the frontend URL (either http://localhost:3000 or https://app.maybern.test:3000).
2

Access Developer Zone

Click on “DEVELOPER ZONE” at the bottom of the login page.
3

Use simple login

Click “Use simple login” to bypass Stytch authentication.
4

Enter credentials

Use the following test credentials:
  • Email: test-runner@maybern.com
  • Password: password1234
You should now see the Maybern dashboard. If the database is empty, you’ll see an empty state - proceed to load sample data.

​
Quick Reference: Just Commands

The project uses just as a command runner. Here are the most common commands:
CommandDescription
just run-serverStart Django development server
just run-celeryStart Celery workers
just run-server-aiStart AI chat server
just reset-dbReset database and load fixtures
just migrateRun database migrations
just makemigrationsCreate new migrations
just testRun backend tests
just lint checkCheck linting
just lint fixAuto-fix linting issues
just codegen schemasGenerate OpenAPI schema
just codegen clientsGenerate API clients
Run just without arguments from the project root to see all available commands.

​
Terminal Layout Recommendation

For efficient development, we recommend this terminal layout: 
┌─────────────────────┬─────────────────────┐
│   Django Server     │   Celery Workers    │
│   (just run-server) │   (just run-celery) │
├─────────────────────┼─────────────────────┤
│   Frontend          │   Git / General     │
│   (pnpm start)      │                     │
└─────────────────────┴─────────────────────┘

​
Next Steps

Loading Data

Load sample fund data to explore the application.

Troubleshooting

Common issues and how to resolve them.