Setting up a local development environment

This guide explains how to set up a local environment for developing custom services or states for PERSEUS. It covers the directory structure, dependencies, and how to run both the backend (core) and frontend components locally.

Directory Structure

We recommend checking out the PERSEUS repositories in a shared project directory like this:

my-perseus-dev/
├── core/            ← PERSEUS core (Python - FastAPI)
├── frontend/        ← PERSEUS frontend (TypeScript - React)
└── my-extension/    ← Your custom states/services

In your custom repo (my-extension/), you can define:

• Custom services: my-extension/services/
• Custom states: my-extension/states/

Then link them into the core project using symbolic links:

# Inside core/
ln -s ../../my-extension/services/ perseus/services/custom
ln -s ../../my-extension/states/   perseus/states/custom

This allows the core service to discover and load your custom components automatically during development.

---

Running MongoDB (via Docker)

PERSEUS requires a MongoDB instance. For local development, the easiest option is to run MongoDB in a Docker container:

docker

docker run -d \
  --name perseus-mongo \
  -p 27017:27017 \
  mongo:7

podman

podman run -d \
  --name perseus-mongo \
  -p 27017:27017 \
  mongo:7

This exposes MongoDB on localhost:27017.

Setting Up the Core (Backend)

The core service is written in Python using FastAPI, and uses Pipenv to manage dependencies.

1. Install dependencies

Inside the core/ directory:

pip install pipenv
pipenv install --dev

Python version

Make sure you’re using a Python version compatible with PERSEUS (3.12 or newer).

2. Create and configure .env

You need to create a .env file to define environment variables. At a minimum, you should set the MongoDB connection string:

MONGODB_URI=mongodb://localhost:27017
MONGODB_DATABASE_NAME=perseus
MONGODB_DATABASE_GRID_FS_NAME=perseus_fs

Other variables like FIRST_OWNER, DEMO, or LDAP-related values can also be added. Read more about the other configuration options here.

3. Start the development server

source .env
pipenv run fastapi dev perseus/main.py

This will start the core on http://localhost:8000.

---

Setting Up the Frontend (React + Vite)

The frontend is a React + TypeScript project powered by Vite.

1. Install dependencies

Inside the frontend/ directory:

npm install

Node.js version

Make sure you’re using a Node.js version compatible with PERSEUS (22 or newer).

2. Configure local development domain

For local development and proxying to the backend, we recommend using perseus.localhost as the local domain. Add the following line to your /etc/hosts file:

127.0.0.1 perseus.localhost

This allows the frontend to be served under a custom domain, avoiding CORS issues.

3. Configure Vite proxy

The frontend will automatically load a file called vite.proxy.local.ts if it exists.

Create the file frontend/vite.proxy.local.ts with the following content:

import type { ProxyOptions } from "vite";

export const proxy: Record<string, string | ProxyOptions> = {
    "/api": {
        target: "http://perseus.localhost:8000",
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ""),
    },
};

Replace perseus.localhost with the domain where your local core service is running (default: localhost:8000).

4. Start the frontend

npx vite serve --host perseus.localhost --port 5173

You can now access the frontend in your browser at:

http://perseus.localhost:5173

It will proxy API requests to the backend at /api.

---

Development Tips

• To reload your FastAPI backend automatically on code changes, make sure to use fastapi dev (not uvicorn) and install your dependencies in --dev mode.
• Both frontend and core are hot-reload capable if started with the commands above.
• You can run MongoDB with a persistent volume using -v perseus-mongo:/data/db if needed.

---

Summary

Component	Tech Stack	Start Command
MongoDB	Docker	docker run -p 27017:27017 mongo:7
Backend (core)	FastAPI + Pipenv	source .env && pipenv run fastapi dev perseus/main.py
Frontend	React + Vite + TypeScript	npx vite serve --host perseus.localhost --port 5173