Skip to main content

CLI Setup

For experienced administrators or automated deployments, Vidra can be configured entirely through environment variables and CLI commands — no wizard needed.

1. Clone and Build​

git clone https://github.com/yosefgamble/athena.git vidra
cd vidra

# Build from source
make build

# Or use Docker
docker compose build

2. Create the Environment File​

Copy the example configuration and edit it:

cp .env.example .env

Required Variables​

# Database
DATABASE_URL=postgres://vidra:yourpassword@localhost:5432/vidra?sslmode=disable

# Cache
REDIS_URL=redis://localhost:6379/0

# Security
JWT_SECRET=$(openssl rand -base64 32)

# Mark setup as complete (skip wizard)
SETUP_COMPLETED=true

Full Configuration Reference​

# === Database ===
POSTGRES_MODE=external              # docker | external
DATABASE_URL=postgres://user:pass@host:5432/dbname?sslmode=disable

# === Cache ===
REDIS_MODE=external                 # docker | external
REDIS_URL=redis://localhost:6379/0

# === Server ===
PORT=8080
HOSTNAME=localhost
PROTOCOL=http                       # http | https
TLS_MODE=none                       # none | self-signed | letsencrypt
LETSENCRYPT_EMAIL=admin@example.com

# === Storage ===
STORAGE_PATH=./data/storage
BACKUP_ENABLED=true
BACKUP_TARGET=local                 # local | s3 | sftp
BACKUP_SCHEDULE=0 2 * * *           # Cron expression (daily at 2 AM)
BACKUP_RETENTION_DAYS=7
BACKUP_LOCAL_PATH=./backups

# === Email ===
ENABLE_EMAIL=true
EMAIL_MODE=external                 # docker | external | disabled
SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_USERNAME=postmaster@mg.example.com
SMTP_PASSWORD=your-smtp-password
SMTP_FROM_ADDRESS=noreply@vidra.example.com
SMTP_FROM_NAME=Vidra

# === Security ===
JWT_SECRET=your-32-char-minimum-secret-key-here
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your-secure-password

# === Optional: IPFS ===
IPFS_ENABLED=false
IPFS_MODE=docker                    # docker | external
IPFS_API_URL=http://localhost:5001

# === Optional: IOTA Payments ===
IOTA_ENABLED=false
IOTA_NETWORK=testnet                # testnet | mainnet
IOTA_MODE=docker                    # docker | external
IOTA_NODE_URL=http://localhost:14265

# === Optional: ClamAV ===
CLAMAV_ENABLED=false                # Requires 2GB+ RAM

# === Optional: Whisper ===
WHISPER_ENABLED=false               # Requires 4GB+ RAM, GPU recommended

3. Set Up the Database​

Option A: Docker-managed PostgreSQL​

# Start PostgreSQL and Redis via Docker
docker compose up -d postgres redis

Option B: External PostgreSQL​

# Create the database
createdb -h localhost -U postgres vidra

# Apply migrations
make migrate-up

4. Start the Server​

# Start all services
docker compose up -d

# View logs
docker compose logs -f vidra

Binary​

# Run the built binary
make run

# Or directly
./bin/athena --port 8080

5. Create the Admin User​

If you set ADMIN_USERNAME, ADMIN_EMAIL, and ADMIN_PASSWORD in .env, the admin account is created automatically on first startup.

Alternatively, create an admin via the API after startup:

# Register a user
curl -X POST http://localhost:8080/api/v1/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "email": "admin@example.com",
    "password": "your-secure-password"
  }'

6. Verify the Installation​

# Health check
curl http://localhost:8080/health
# Expected: {"status":"ok"}

# Server configuration
curl http://localhost:8080/api/v1/config
# Returns public server configuration

# Check service status
docker compose ps

Docker Compose Profiles​

Vidra uses Docker Compose profiles to manage optional services:

# Core services only (PostgreSQL + Redis)
docker compose up -d

# With IPFS
docker compose --profile ipfs up -d

# With all optional services
docker compose --profile ipfs --profile clamav --profile whisper up -d

# Development with email testing (Mailpit)
docker compose --profile mail up -d
# Access Mailpit UI at http://localhost:8025

Environment-Specific Configurations​

Development​

# .env
POSTGRES_MODE=docker
REDIS_MODE=docker
HOSTNAME=localhost
PORT=8080
PROTOCOL=http
EMAIL_MODE=docker       # Uses Mailpit
SETUP_COMPLETED=true

Production​

# .env
POSTGRES_MODE=external
DATABASE_URL=postgres://vidra:securepass@db.internal:5432/vidra?sslmode=require
REDIS_MODE=external
REDIS_URL=redis://cache.internal:6379/0
HOSTNAME=vidra.example.com
PORT=443
PROTOCOL=https
TLS_MODE=letsencrypt
LETSENCRYPT_EMAIL=admin@example.com
EMAIL_MODE=external
SMTP_HOST=smtp.mailgun.org
SETUP_COMPLETED=true

Makefile Commands​

make build              # Build the binary
make run                # Build and run
make test               # Run all tests
make lint               # Run golangci-lint
make fmt                # Format code
make migrate-up         # Apply all pending migrations
make migrate-down       # Rollback last migration
make migrate-status     # Show migration status
make validate-all       # Full validation suite
make docker             # Build Docker image

Troubleshooting​

Server won't start​

# Check if ports are in use
lsof -i :8080

# Verify database connection
psql "$DATABASE_URL" -c "SELECT 1"

# Check Redis
redis-cli -u "$REDIS_URL" ping

Migrations fail​

# Check migration status
make migrate-status

# Reset and re-apply (development only!)
make migrate-down
make migrate-up

Docker services unhealthy​

# Check individual service logs
docker compose logs postgres
docker compose logs redis

# Restart a specific service
docker compose restart postgres