Skip to content

MIGRATION.md

Latest commit

 

History

History
209 lines (145 loc) · 5.64 KB

MIGRATION.md

File metadata and controls

209 lines (145 loc) · 5.64 KB
Raw

Azurro Migration Guide

This guide explains how to move Azurro + its Memory Vault (Postgres/pgvector) from this EC2 box to any other Linux host.

For Azuro protocol stack changes (Graph → Toolkit REST, WebSocket gates, Backend API), see MIGRATION-AZURO.md.

The stack is intentionally portable: nothing is AWS‑specific as long as you have Python, Postgres and the pgvector extension.

1. What needs to move

  • Code + venv
    • The Azurro project directory (e.g. /home/ubuntu/Azurro).
    • The Python virtual environment can be recreated from requirements.txt on the new host.
  • Configuration
    • The .env file with API keys, wallet details, Postgres DSN, Telegram token, etc.
  • Database
    • The Postgres database that contains the Memory Vault, typically:
      • Database: azurro
      • Tables: memory_items (plus any others you added).
      • pgvector extension with vector(768) for the embedding column.
  • Services & schedulers
    • The azurro systemd service (if you use it to keep the bot running).
    • Cron jobs or timers for nightly/weekly reflection (reflection.py).

2. Prerequisites on the new host

On the new Linux server (Ubuntu/Debian‑style), install:

sudo apt update
sudo apt install -y python3 python3-venv python3-pip postgresql postgresql-contrib git

Then enable the pgvector extension in Postgres:

-- In psql on the new host (as postgres or a superuser):
CREATE DATABASE azurro;
CREATE USER azurro WITH PASSWORD 'azurro_pw';
GRANT ALL PRIVILEGES ON DATABASE azurro TO azurro;

\\c azurro
CREATE EXTENSION IF NOT EXISTS vector;

Adjust database name, user and password if you prefer a different naming scheme.

If psycopg2-binary ever complains about missing build deps, install:

sudo apt install -y build-essential libpq-dev

3. Moving the code and .env

On the old host (current EC2), from the parent directory of Azurro:

cd /home/ubuntu
tar czf azurro-code.tar.gz Azurro

Copy azurro-code.tar.gz to the new server (for example, using scp or rsync):

scp azurro-code.tar.gz new-host:/home/ubuntu/

On the new host:

cd /home/ubuntu
tar xzf azurro-code.tar.gz
cd Azurro
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Copy the .env file securely from old host to new host (never commit it to git), then on the new host:

  • Open .env and update any host‑specific values, for example:
    • AZURRO_PG_DSN to point at the new Postgres instance, e.g.
      AZURRO_PG_DSN=postgresql://azurro:azurro_pw@localhost:5432/azurro

4. Migrating the database

On the old host, create a dump of the azurro database:

pg_dump -Fc -d azurro -U azurro > azurro.dump

(You may need to prefix with sudo -u postgres if you normally connect as postgres rather than azurro.)

Copy azurro.dump to the new server:

scp azurro.dump new-host:/home/ubuntu/

On the new host, restore the dump into the azurro database you created earlier:

sudo -u postgres pg_restore -d azurro -U azurro /home/ubuntu/azurro.dump

After restore, verify a few basics in psql:

\\c azurro
\\d memory_items
SELECT COUNT(*) FROM memory_items;

Check that the embedding column is of type vector(768) (or whatever dim you configured).

5. Recreating systemd service

If you use systemd to keep the bot running 24/7, create a unit file on the new host, for example /etc/systemd/system/azurro.service:

[Unit]
Description=Azurro Azuro Betting Bot
After=network-online.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/Azurro
ExecStart=/home/ubuntu/Azurro/.venv/bin/python -u main.py
Restart=always
RestartSec=15
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Then reload and enable:

sudo systemctl daemon-reload
sudo systemctl enable --now azurro

Check status:

systemctl status azurro

You should see the service running and logs flowing into journalctl -u azurro.

6. Recreating reflection cron jobs

On the new host, install the same nightly and weekly reflection jobs under the target user (e.g. ubuntu):

crontab -e

Add lines like:

0 3 * * * cd /home/ubuntu/Azurro && /home/ubuntu/Azurro/.venv/bin/python reflection.py nightly >> /home/ubuntu/Azurro/logs/reflection-nightly.log 2>&1
0 4 * * MON cd /home/ubuntu/Azurro && /home/ubuntu/Azurro/.venv/bin/python reflection.py weekly >> /home/ubuntu/Azurro/logs/reflection-weekly.log 2>&1

Create the logs directory if it does not exist:

mkdir -p /home/ubuntu/Azurro/logs

Optional: you can instead create systemd timer units for reflection.py if you prefer systemd‑managed scheduling, but cron is usually sufficient.

7. Sanity checklist after migration

Once everything is copied and configured on the new host:

  • Service health
    • systemctl status azurro shows active (running).
  • Database health
    • psql -d azurro -c "SELECT COUNT(*) FROM memory_items;" returns a reasonable count (similar order of magnitude as old host).
    • A quick query like SELECT kind, source, created_at FROM memory_items ORDER BY created_at DESC LIMIT 5; shows recent memories.
  • Bot behaviour
    • Telegram /status works and shows correct environment.
    • /teach stores a new lesson, and /memory displays it.
    • Optionally, run ./.venv/bin/python reflection.py nightly once by hand and confirm that it completes and writes a new lesson entry.

If all of the above pass, Azurro + the Memory Vault have been successfully migrated to the new host.