#Local Deployment Guide (Docker Compose)

#Prerequisites

#Required API Keys

#Step-by-step Deployment

#1. Clone the repository

git clone <repo-url>
cd evi-run

#2. Create and configure .env

cp .env.example .env

Edit .env and fill in all required values. Pay attention to DATABASE_URL — it must use the Docker service name postgres as the host (not localhost):

DATABASE_URL=postgresql+psycopg://evi_user:YOUR_PASSWORD@postgres:5432/evi_db
REDIS_URL=redis://redis:6379

Important: Use the container-internal ports (5432 for PostgreSQL, 6379 for Redis), not the host-mapped ports (5434, 6380).

#3. Configure config.py

Edit config.py and set your Telegram user ID:

ADMIN_ID = 123456789              # Your Telegram ID
ADMINS_LIST = [123456789]         # List of admin Telegram IDs
TYPE_USAGE = 'private'            # 'private', 'free', or 'pay'

To find your Telegram ID, message @userinfobot.

#4. Build and start

docker compose up --build -d

#5. Verify

# Check all containers are running
docker compose ps

# Watch bot logs
docker compose logs -f bot

# Check database is healthy
docker compose logs postgres

#Architecture

The deployment runs 3 containers (4 if the optional payment module is enabled):

                 ┌─────────────┐
                 │   bot_agent  │
                 │  (Telegram)  │
                 └──────┬───┬──┘
                        │   │
            ┌───────────┘   └───────────┐
            ▼                           ▼
   ┌────────────────┐        ┌──────────────────┐
   │ postgres_agent  │        │   redis_agent     │
   │  (PostgreSQL)   │        │   (Redis)         │
   │  :5434 → :5432  │        │   :6380 → :6379   │
   └────────────────┘        └──────────────────┘

Data persistence:

• ./data/postgres/postgres_data — PostgreSQL data
• ./data/redis/data — Redis data
• ./data/images — Generated images

#Enabling the Payment Module (Optional)

The fastapi service is commented out by default because the payment_module/ directory is not included in the repository. If you have the payment module:

1. Place the payment_module/ directory in the project root
2. Uncomment the fastapi service block in docker-compose.yml
3. Add fastapi to the bot's depends_on section
4. Rebuild: docker compose up --build -d

#Troubleshooting

#Bot container keeps restarting

docker compose logs bot

Common causes:

• Invalid TELEGRAM_BOT_TOKEN
• Invalid API_KEY_OPENAI
• Database not ready (healthcheck should prevent this, but check docker compose logs postgres)

#Database connection errors

• Verify DATABASE_URL in .env uses postgres as host (not localhost)
• Verify POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB match between the .env values and DATABASE_URL

#Redis connection errors

• Verify REDIS_URL uses redis as host (not localhost)

#Rebuilding after .env changes

Environment variables are injected via env_file in docker-compose.yml, so a simple restart should pick up changes:

docker compose down && docker compose up -d

However, if you change dependencies or code, rebuild:

docker compose up --build -d

#Resetting everything

docker compose down -v
rm -rf data/postgres data/redis
docker compose up --build -d