Skip to Content
DocumentationGetting Started

Getting Started

Welcome to Eneo! This guide will help you get started whether you’re a municipal organization evaluating the platform or a developer looking to contribute.

Choose Your Path

🏛️ For Municipal Organizations

If you’re a public sector organization interested in deploying Eneo:

1. Learn & Evaluate

2. Test Drive

Set up a development instance to explore the platform:

git clone https://github.com/eneo-ai/eneo.git
cd eneo && code .
# Click "Reopen in Container" when prompted in VS Code

Nothing starts automatically inside the container. Open three terminals and run:

cd backend && uv run python init_db.py   # first run only: migrations + default user
cd backend && uv run start               # Terminal 1: API on port 8123
cd frontend && bun run dev               # Terminal 2: web app on port 3000
cd backend && uv run worker              # Terminal 3: uploads and crawls

Access your instance at http://localhost:3000  with default credentials:

  • Email: user@example.com
  • Password: ChangeMePassword1!

3. Deploy to Production

When you’re ready to deploy:

  1. Review the deployment guide
  2. Configure authentication with your identity provider
  3. Set up your AI providers
  4. Review audit logging practices in our audit logging guide

💻 For Developers

Contributing to Eneo? Here’s how to get started:

Prerequisites

  • Docker Desktop with DevContainers support
  • VS Code with Dev Containers extension
  • Git

Quick Setup (DevContainer - Recommended)

The fastest way to get started:

git clone https://github.com/eneo-ai/eneo.git
cd eneo
code .
# Click "Reopen in Container" when prompted

The DevContainer includes:

  • Python 3.11 with uv (backend dependencies installed with uv sync)
  • Bun for the frontend workspace (bun run setup installs and builds the packages)
  • PostgreSQL with pgvector and Redis as sidecar containers
  • backend/.env and frontend/apps/web/.env created from their templates, plus a generated development ENCRYPTION_KEY
  • pre-commit hooks

Services are not started for you. On the first run, initialize the database, then start the backend, frontend, and worker in three terminals:

cd backend && uv run python init_db.py   # first run only
 
cd backend && uv run start               # Terminal 1: Backend (port 8123)
cd frontend && bun run dev               # Terminal 2: Frontend (port 3000)
cd backend && uv run worker              # Terminal 3: Worker

Manual Setup

If you prefer manual setup or need more control:

Requirements:

  • Python 3.11 (the backend is pinned to >=3.11,<3.12) and uv 
  • Bun 1.3
  • PostgreSQL with the pgvector extension and Redis (for example in Docker)
  • libmagic and ffmpeg system packages
# Clone the repository
git clone https://github.com/eneo-ai/eneo.git
cd eneo
 
# Backend setup
cd backend
cp .env.template .env        # point POSTGRES_* and REDIS_* at your services
uv sync
uv run python init_db.py     # migrations + default tenant/user
 
# Frontend setup
cd ../frontend
cp apps/web/.env.example apps/web/.env
bun run setup                # bun install + builds the shared UI package
 
# Start services (requires 3 terminals)
# Terminal 1: Backend
cd backend && uv run start
 
# Terminal 2: Frontend
cd frontend && bun run dev
 
# Terminal 3: Worker
cd backend && uv run worker

Access Your Development Environment

Next Steps for Developers

  1. Read the Documentation

  2. Explore the Codebase

    • Backend: FastAPI with Python 3.11
    • Frontend: SvelteKit with TypeScript
    • Database: PostgreSQL with pgvector
    • Cache/Queue: Redis with ARQ

  3. Make Your First Contribution

    • Find an open issue on GitHub 
    • Fork the repository
    • Create a feature branch
    • Submit a pull request

Common Issues

DevContainer Issues

If the DevContainer fails to start:

  1. Ensure Docker Desktop is running and has free disk space
  2. Try rebuilding the container: Dev Containers: Rebuild Container

Database Connection Issues

If you can’t connect to the database:

  1. Ensure PostgreSQL is running
  2. Check POSTGRES_* and REDIS_* in backend/.env, and the backend URLs in frontend/apps/web/.env
  3. Verify port 5432 is not in use by another service (the DevContainer publishes PostgreSQL on it)

File Upload Issues

File uploads and web crawls require the worker service to be running:

cd backend && uv run worker

Get Help

What’s Next?

OverviewArchitecture