Skip to content

Installation

This guide covers deploying MeterBase on your own infrastructure. Choose between Docker Compose (recommended) or manual setup.

Prerequisites

Dependency Minimum Version Purpose
Python 3.11+ Backend API server
Node.js 18+ Frontend build and dev server
PostgreSQL 15+ Primary database
Redis 7+ Caching, rate limiting, job queue
Docker 24+ Container deployment (optional)
Docker Compose 2.20+ Multi-container orchestration (optional)

The fastest way to get a complete MeterBase environment running.

1. Clone the Repository

git clone https://github.com/your-org/meterbase.git
cd meterbase

2. Configure Environment

cp .env.example .env

Edit .env with your configuration. At minimum, set these values:

SECRET_KEY=your-random-secret-key-here
ANTHROPIC_API_KEY=sk-ant-...
DATABASE_URL=postgresql://meterbase:meterbase@db:5432/meterbase
REDIS_URL=redis://redis:6379/0

Secret Key

Generate a strong random secret key for production. Use python -c "import secrets; print(secrets.token_urlsafe(64))" to create one.

See the Configuration Reference for all available variables.

3. Start Services

docker compose up -d

This starts:

  • backend -- FastAPI server on port 8000
  • frontend -- Next.js server on port 3000
  • db -- PostgreSQL 15 on port 5432
  • redis -- Redis 7 on port 6379
  • worker -- Background job processor (bill analysis, charge posting)

4. Initialize the Database

docker compose exec backend alembic upgrade head

5. Seed Tariff Data

Load the tariff database (62,700+ tariffs, 2,866 utilities, 120,015 ZIP mappings):

docker compose exec backend python scripts/bulk_import.py

Import Duration

The initial tariff import takes 10-15 minutes depending on your hardware. Progress is logged to stdout.

6. Create an Admin User

docker compose exec backend python scripts/create_admin.py \
  --email admin@yourcompany.com \
  --password your-secure-password \
  --name "Admin User"

7. Verify

Open http://localhost:3000 in your browser. Log in with the admin credentials you just created.

Option B: Manual Setup

For development or environments where Docker is not available.

1. Clone the Repository

git clone https://github.com/your-org/meterbase.git
cd meterbase

2. Run the Setup Script

The setup script installs Python and Node dependencies, creates config files, and validates prerequisites:

chmod +x scripts/setup.sh
./scripts/setup.sh

This script will:

  • Create a Python virtual environment in venv/
  • Install Python dependencies from requirements.txt
  • Install Node dependencies via npm install in the frontend/ directory
  • Copy .env.example to .env if it does not exist
  • Validate that PostgreSQL and Redis are reachable

3. Configure Environment

cp .env.example .env
# Edit .env with your database URL, API keys, etc.

4. Set Up the Database

Create the PostgreSQL database and run migrations:

createdb meterbase
source venv/bin/activate
alembic upgrade head

5. Seed Tariff Data

source venv/bin/activate
python scripts/bulk_import.py

The bulk import script loads data from:

  • OpenEI -- Utility tariff rate data
  • EIA -- Utility company directory
  • Internal mappings -- ZIP code to utility associations

6. Start the Backend

source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

7. Start the Frontend

In a separate terminal:

cd frontend
npm run dev

The frontend starts on http://localhost:3000 and proxies API calls to the backend on port 8000.

8. Start the Worker (Optional)

For background job processing (async bill analysis, charge posting):

source venv/bin/activate
python -m app.worker

Database Schema

MeterBase uses 22 PostgreSQL tables. Key tables include:

Table Purpose
users User accounts and authentication
portfolios Property groupings
properties Individual multifamily properties
bills Utility bill records
tariffs Rate schedule definitions
tariff_rates Individual rate components within a tariff
utilities Utility company directory
zip_utilities ZIP code to utility mappings
units Individual dwelling units within a property
tenant_charges Calculated RUBS charges
savings_analyses Savings comparison results
propexo_connections PMS integration configuration

Migrations are managed with Alembic. Never modify the database schema directly.

Verifying the Installation

Run the health check to confirm all services are operational:

curl http://localhost:8000/api/health

Expected response:

{
  "status": "healthy",
  "database": "connected",
  "redis": "connected",
  "tariff_count": 62700,
  "utility_count": 2866
}

Upgrading

To upgrade an existing installation:

# Docker Compose
docker compose pull
docker compose up -d
docker compose exec backend alembic upgrade head

# Manual
git pull origin main
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
cd frontend && npm install && npm run build

Always Run Migrations

After upgrading, always run alembic upgrade head to apply any new database migrations. Skipping this step may cause errors.

Troubleshooting

Database connection refused

Ensure PostgreSQL is running and the DATABASE_URL in .env is correct. For Docker Compose, the hostname should be db, not localhost.

Redis connection error

Verify Redis is running on the configured port. For Docker Compose, the hostname should be redis.

Tariff import fails

Check that OPENEI_API_KEY and EIA_API_KEY are set in .env. The import script requires network access to fetch tariff data from external APIs.

Frontend cannot reach backend

Confirm the backend is running on port 8000. Check that NEXT_PUBLIC_API_URL in the frontend environment points to the correct backend URL.