btc-trading/SYNOLOGY_INSTALL.md

Installing BTC Bot on Synology NAS

Tested on Synology DS218+ (DSM 7.x, 2 GB RAM). The system runs three Docker containers: TimescaleDB, a data collector (WebSocket to Hyperliquid), and a FastAPI server with a web dashboard.

Prerequisites

1. Docker -- install from Synology Package Center.
2. SSH access -- enable in DSM: Control Panel > Terminal & SNMP > Enable SSH.
3. Git (optional) -- install the Git Server package, or copy files manually.

Step 1 -- Set NAS DNS

Docker on Synology often can't resolve hostnames during image builds. Fix this before anything else:

DSM > Control Panel > Network > General tab > set DNS Server:

Field	Value
Preferred DNS	8.8.8.8
Alternate DNS	8.8.4.4

Click Apply.

Step 2 -- Get the code onto the NAS

SSH into the NAS and clone/copy the project:

ssh your_user@nas_ip
cd /volume1/homes/your_user    # or wherever you prefer
git clone <repo_url> btc_bot
cd btc_bot

Or copy files via SMB/SCP to /volume1/homes/your_user/btc_bot.

Step 3 -- Create directories

sudo mkdir -p /volume1/btc_bot/{data,backups,logs,exports}

These are mounted as volumes by the containers.

Step 4 -- Configure environment

cp .env.example .env
nano .env    # or vi

At minimum, set a strong password for these two values:

DB_PASSWORD=your_secure_password_here
API_SECRET_KEY=your_secret_key_here

The remaining values can stay at their defaults for data collection.

Step 5 -- Build images

The standard docker-compose build may fail with DNS errors inside the build container. Use docker build with --network host to bypass this:

cd ~/btc_bot

# Build both images (uses host network for DNS resolution)
docker build --network host -f docker/Dockerfile.collector -t btc_collector .
docker build --network host -f docker/Dockerfile.api -t btc_api .

If you make code changes later, re-run these two commands to rebuild.

Step 6 -- Start services

cd ~/btc_bot/docker
docker-compose up -d --no-build

The --no-build flag tells compose to use the images you built in Step 5 instead of trying to build through its own (potentially broken) network.

TimescaleDB will initialize the schema automatically from docker/init-scripts/01-schema.sql on first start.

Step 7 -- Verify

# Check all three containers are running
docker-compose ps

# Watch collector logs (Ctrl+C to stop)
docker-compose logs -f data_collector

# Check database health
docker exec btc_timescale pg_isready -U btc_bot -d btc_data

# Run the health check script
bash ~/btc_bot/scripts/health_check.sh

The API dashboard is available at: http://nas_ip:8000/dashboard API docs (Swagger): http://nas_ip:8000/docs

Setting up automated backups

The backup script dumps the database every run and keeps 30 days of history.

Option A -- DSM Task Scheduler (recommended)

1. Open DSM > Control Panel > Task Scheduler
2. Create > Scheduled Task > User-defined script
3. Set schedule: every 6 hours
4. User-defined script:

   /bin/bash /volume1/homes/your_user/btc_bot/scripts/backup.sh
   

5. Run as: root (needed for docker exec)

Option B -- Cron (via SSH)

sudo crontab -e

Add this line (runs every 6 hours):

0 */6 * * * /bin/bash /volume1/homes/your_user/btc_bot/scripts/backup.sh >> /volume1/btc_bot/logs/backup.log 2>&1

Backups are stored in /volume1/btc_bot/backups/.

Setting up health monitoring

Add another scheduled task (every 5 minutes) to check if everything is running:

/bin/bash /volume1/homes/your_user/btc_bot/scripts/health_check.sh

Common operations

View logs

cd ~/btc_bot/docker
docker-compose logs -f data_collector    # collector
docker-compose logs -f api_server        # API
docker-compose logs -f timescaledb       # database

Restart a single service

cd ~/btc_bot/docker
docker-compose restart data_collector

Stop everything

cd ~/btc_bot/docker
docker-compose down

Rebuild after code changes

cd ~/btc_bot
docker build --network host -f docker/Dockerfile.collector -t btc_collector .
docker build --network host -f docker/Dockerfile.api -t btc_api .
cd docker
docker-compose up -d --no-build

Reset database (destroys all data)

Only do this if you need a fresh schema:

cd ~/btc_bot/docker
docker-compose down -v
docker-compose up -d --no-build

Restore from backup

gunzip /volume1/btc_bot/backups/btc_data_YYYYMMDD_HHMM.dump.gz
docker exec -i btc_timescale pg_restore -U btc_bot -d btc_data --clean < /volume1/btc_bot/backups/btc_data_YYYYMMDD_HHMM.dump

Resource usage

The system is tuned for the DS218+ (2 GB RAM, dual-core):

Container	Memory limit	Typical usage
TimescaleDB	1.5 GB	~400-800 MB
Data Collector	256 MB	~50-100 MB
API Server	512 MB	~50-100 MB

PostgreSQL settings in docker/timescaledb.conf are optimized for this hardware. If running on a more powerful NAS, increase shared_buffers and effective_cache_size proportionally.

Troubleshooting

DNS errors during build

Use --network host when building (Step 5). If it still fails, check that your NAS can resolve DNS from the host:

nslookup pypi.org

If that fails, fix DNS in DSM (Step 1).

Container keeps restarting

docker logs btc_collector    # check error output
docker logs btc_api

Common causes: wrong DB_PASSWORD in .env, database not ready yet (wait 30 seconds after first start), or port 5432/8000 already in use.

No data appearing

1. Check collector logs: docker-compose logs data_collector
2. Verify WebSocket connectivity: the NAS needs outbound access to wss://api.hyperliquid.xyz/ws (port 443)
3. Check database: docker exec btc_timescale psql -U btc_bot -d btc_data -c "SELECT COUNT(*) FROM candles;"

Ports used

Port	Service	Direction
5432	PostgreSQL	Internal (+ exposed to host)
8000	API/Dashboard	Inbound from LAN
443	PyPI, Hyperliquid WS	Outbound
53	DNS	Outbound