Skip to main content

Source: ebisu/docs/guides/setup/development-setup.md | ✏️ Edit on GitHub

Ebisu Development Setup Guide

Complete guide for setting up Ebisu database for local development and production deployment

Quick Start​

# 1. Copy environment template
cp .env.example .env

# 2. Start the database
make up

# 3. Run migrations
make migrate

# 4. Verify setup
make status
make psql

Environment Configuration​

Local Development (.env)​

# Database connection
POSTGRES_HOST=db                    # 'db' for Docker
POSTGRES_PORT=5432
POSTGRES_DB=ebisu
POSTGRES_USER=ebisu_user
POSTGRES_PASSWORD=ebisu_password
POSTGRES_SSL_MODE=prefer

# Import configuration
IMPORT_BATCH_SIZE=1000
IMPORT_LOG_LEVEL=INFO
VESSEL_MATCH_THRESHOLD=0.85

# Environment
ENVIRONMENT=development

Docker Compose Settings​

Local development uses these settings (port 5433 to avoid conflicts):

  • Host: localhost
  • Port: 5433
  • Database: ebisu
  • User: ebisu_user
  • Password: ebisu_password

Production (Crunchy Bridge)​

# Database connection
POSTGRES_HOST=p.xxxxx.db.postgresbridge.com
POSTGRES_PORT=5432
POSTGRES_DB=ebisu
POSTGRES_USER=u_xxxxx
POSTGRES_PASSWORD=<from-crunchy-bridge>
POSTGRES_SSL_MODE=require           # Required for Crunchy Bridge

# Environment
ENVIRONMENT=production

Docker Development​

Standard Commands​

# Start services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f

# Stop services
docker compose down

# Clean everything (including volumes)
docker compose down -v

Container Access​

# Database container
docker exec -it ebisu-db psql -U ebisu_user -d ebisu

# Importer container
docker exec -it ebisu-importer bash

Running Migrations​

# Using make
make migrate

# Direct command
docker exec -i ebisu-db psql -U ebisu_user -d ebisu < migrations/V1__initial_schema.sql

Database Connection​

Connection String​

postgresql://ebisu_user:ebisu_password@localhost:5433/ebisu

Using psql​

psql postgresql://ebisu_user:ebisu_password@localhost:5433/ebisu

Using DBeaver/TablePlus​

  • Host: localhost
  • Port: 5433
  • Database: ebisu
  • Username: ebisu_user
  • Password: ebisu_password

Import System​

Running Imports​

# Import from Git LFS data
./import-sources/docker-import.sh rfmo/iccat

# Import with specific file
./import-sources/docker-import.sh country/usa-alaska data.csv

# Check import status
./scripts/import/vessels/check_import_status.sh

Environment Variables for Imports​

The importer container needs these environment variables:

export POSTGRES_HOST=ebisu-db
export POSTGRES_PORT=5432
export POSTGRES_DB=ebisu
export POSTGRES_USER=ebisu_user
export POSTGRES_PASSWORD=ebisu_password

Makefile Commands​

make up         # Start database
make down       # Stop database
make restart    # Restart services
make status     # Check status
make logs       # View logs
make psql       # Connect to database
make migrate    # Run migrations
make clean      # Clean everything

Troubleshooting​

Port Conflicts​

If port 5433 is in use:

# Check what's using the port
lsof -i :5433

# Change port in docker-compose.yml
ports:
  - "5434:5432"  # Use 5434 instead

Connection Issues​

# Check if container is running
docker ps | grep ebisu-db

# Check container logs
docker logs ebisu-db

# Test connection
pg_isready -h localhost -p 5433 -U ebisu_user -d ebisu

Migration Failures​

# Check current schema version
SELECT version FROM schema_version ORDER BY installed_rank DESC LIMIT 1;

# Run specific migration
docker exec -i ebisu-db psql -U ebisu_user -d ebisu < migrations/V2__specific_migration.sql

Import Issues​

# Check importer logs
docker logs ebisu-importer

# Verify environment variables
docker exec ebisu-importer env | grep POSTGRES

# Run import with debug
docker exec ebisu-importer bash -x /app/scripts/import/vessels/import.sh

Security Notes​

  1. Never commit .env files - Use .env.example as template
  2. Use strong passwords in production - Generated by password manager
  3. Enable SSL for production - Set POSTGRES_SSL_MODE=require
  4. Restrict database access - Use firewall rules in production
  5. Regular backups - Set up automated backups for production

Next Steps​

  1. Import vessel data
  2. Understand the intelligence platform
  3. Review vessel trust scoring

Last updated: 2025-10-01