basil/scripts/README.md

# Basil Deployment Scripts

This directory contains scripts for automated deployment of Basil.

## Scripts Overview

### `deploy.sh`

Main deployment script that handles the complete deployment process.

**Features:**
- Pre-deployment backup creation
- Docker image pulling from registry
- Container restart with health checks
- Automatic cleanup of old images
- Comprehensive logging

**Usage:**
```bash
# With environment variables
DOCKER_USERNAME=myuser DOCKER_REGISTRY=docker.io IMAGE_TAG=latest ./deploy.sh

# Or source from .env.deploy
source ../.env.deploy && ./deploy.sh
```

**Environment Variables:**
- `DOCKER_USERNAME` (required): Docker registry username
- `DOCKER_REGISTRY` (optional, default: docker.io): Registry URL
- `IMAGE_TAG` (optional, default: latest): Image tag to pull

### `manual-deploy.sh`

Interactive wrapper around `deploy.sh` with user prompts.

**Features:**
- Interactive prompts for configuration
- Saves configuration to `.env.deploy` for future use
- Confirmation before deployment

**Usage:**
```bash
./manual-deploy.sh
```

The script will prompt for:
1. Docker Hub username
2. Docker registry (default: docker.io)
3. Image tag (default: latest)
4. Confirmation to proceed

### `webhook-receiver.sh`

Webhook server that listens for deployment triggers from CI/CD.

**Features:**
- HTTP webhook endpoint
- Secret-based authentication
- Automatic deployment on webhook call
- Systemd service support

**Usage:**
```bash
# Manual run (foreground)
WEBHOOK_PORT=9000 WEBHOOK_SECRET=mysecret ./webhook-receiver.sh

# Or install as systemd service (recommended)
sudo cp basil-webhook.service /etc/systemd/system/
sudo systemctl enable basil-webhook
sudo systemctl start basil-webhook
```

**Environment Variables:**
- `WEBHOOK_PORT` (optional, default: 9000): Port to listen on
- `WEBHOOK_SECRET` (optional, default: changeme): Authentication secret

**Webhook Endpoint:**
```
POST http://localhost:9000/hooks/basil-deploy
Header: X-Webhook-Secret: your-secret
```

### `basil-webhook.service`

Systemd service file for running webhook receiver as a system service.

**Installation:**
```bash
# 1. Copy service file
sudo cp basil-webhook.service /etc/systemd/system/

# 2. Edit environment variables in the file
sudo nano /etc/systemd/system/basil-webhook.service

# 3. Reload systemd
sudo systemctl daemon-reload

# 4. Enable and start service
sudo systemctl enable basil-webhook
sudo systemctl start basil-webhook

# 5. Check status
sudo systemctl status basil-webhook
```

**Service Management:**
```bash
# Start service
sudo systemctl start basil-webhook

# Stop service
sudo systemctl stop basil-webhook

# Restart service
sudo systemctl restart basil-webhook

# View logs
sudo journalctl -u basil-webhook -f

# Check status
sudo systemctl status basil-webhook
```

## Deployment Workflow

### Automatic Deployment (CI/CD)

1. Developer pushes to `main` branch
2. Gitea Actions runs tests and builds images
3. Images pushed to Docker registry
4. Gitea Actions calls webhook endpoint
5. Webhook server receives call and executes `deploy.sh`
6. Production server pulls new images and restarts

### Manual Deployment

1. Run `./manual-deploy.sh`
2. Enter configuration when prompted
3. Confirm deployment
4. Script executes deployment process

## Logs

All scripts log to the parent directory:

- `deploy.log` - Deployment script logs
- `webhook.log` - Webhook server logs
- `webhook-error.log` - Webhook server errors

**View logs:**
```bash
# Deployment logs
tail -f ../deploy.log

# Webhook logs
tail -f ../webhook.log

# Webhook errors
tail -f ../webhook-error.log

# Systemd service logs
sudo journalctl -u basil-webhook -f
```

## Configuration Files

### `.env.deploy` (in parent directory)

Stores deployment configuration. Created from `.env.deploy.example`.

```bash
DOCKER_USERNAME=your-dockerhub-username
DOCKER_REGISTRY=docker.io
IMAGE_TAG=latest
WEBHOOK_PORT=9000
WEBHOOK_SECRET=your-random-secret
```

**Important:** This file is gitignored and should never be committed.

### `webhook-config.json` (auto-generated)

Generated by `webhook-receiver.sh`. Configures the webhook endpoint.

**Location:** Created in scripts directory when webhook-receiver.sh runs.

## Troubleshooting

### Script Permission Denied

```bash
chmod +x *.sh
```

### Docker Pull Fails

```bash
# Check credentials
docker login -u $DOCKER_USERNAME

# Check image exists
docker pull $DOCKER_REGISTRY/$DOCKER_USERNAME/basil-api:$IMAGE_TAG
```

### Webhook Not Responding

```bash
# Check service status
sudo systemctl status basil-webhook

# Check if port is listening
sudo netstat -tlnp | grep 9000

# Check firewall
sudo ufw status
```

### Health Check Fails

```bash
# Check API logs
docker-compose logs api

# Check API manually
curl http://localhost:3001/health

# Check database connection
docker-compose exec api npx prisma studio
```

## Security Notes

1. **Never commit secrets**: `.env.deploy` is gitignored
2. **Use strong webhook secret**: 32+ character random string
3. **Firewall webhook port**: Allow only from known IPs if possible
4. **Use HTTPS**: Configure reverse proxy for webhook in production
5. **Backup before deploy**: Script creates automatic backups

## Directory Structure

```
scripts/
├── README.md                    # This file
├── deploy.sh                    # Main deployment script
├── manual-deploy.sh             # Interactive deployment
├── webhook-receiver.sh          # Webhook server
├── basil-webhook.service        # Systemd service file
└── webhook-config.json          # Generated webhook config (auto-created)

Parent directory:
├── .env.deploy                  # Deployment config (gitignored)
├── .env.deploy.example          # Example config
├── deploy.log                   # Deployment logs (gitignored)
├── webhook.log                  # Webhook logs (gitignored)
└── backups/                     # Automatic backups (gitignored)
```

## References

- [Full CI/CD Setup Guide](../docs/CI-CD-SETUP.md)
- [Quick Start Guide](../docs/DEPLOYMENT-QUICK-START.md)
- [Project Documentation](../CLAUDE.md)