# 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:

```bash
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

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

These are mounted as volumes by the containers.

## Step 4 -- Configure environment

```bash
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:

```bash
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

```bash
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

```bash
# 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)

```bash
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

```bash
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

```bash
cd ~/btc_bot/docker
docker-compose restart data_collector
```

### Stop everything

```bash
cd ~/btc_bot/docker
docker-compose down
```

### Rebuild after code changes

```bash
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:

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

### Restore from backup

```bash
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:

```bash
nslookup pypi.org
```

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

### Container keeps restarting

```bash
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 |