nextav/docs/archive/deployment-legacy/DEPLOYMENT_GUIDE.md

# NextAV Deployment Guide

## Overview
NextAV is a Next.js application that provides media library management with SQLite database storage. This guide covers Docker deployment, troubleshooting, and best practices for the NextAV application.

## Prerequisites
- Docker and Docker Compose installed
- At least 4GB of available disk space
- Port 3000 available

## Quick Start

### 1. Clone and Setup
```bash
git clone <repository-url>
cd nextav
```

### 2. Environment Configuration
Create a `.env` file in the `docker` directory:
```bash
cd docker
cp .env.example .env
# Edit .env with your configuration
```

### 3. Create Required Directories
```bash
mkdir -p data media
chmod 755 data media
```

### 4. Build and Run
```bash
# Build the Docker image
docker build -t nextav:latest ..

# Start the application
docker compose up -d
```

### 5. Verify Deployment
```bash
# Check container status
docker compose ps

# Test health endpoint
curl http://localhost:3000/api/health

# Access the application
open http://localhost:3000
```

## Configuration

### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `DB_PATH` | `./data` | Path to database storage directory |
| `MEDIA_PATH` | `./media` | Path to media files directory |
| `DB_FILE` | `/app/data/media.db` | Database file path inside container |
| `NEXT_PUBLIC_MEDIA_ROOT` | `/app/media` | Media root path for the application |

### Volume Mounts
- `./data:/app/data` - Database and application data
- `./media:/app/media` - Media files storage

## Troubleshooting

### Database Access Issues
**Problem**: `SqliteError: unable to open database file`

**Solution**:
1. Ensure data directory exists and has correct permissions:
   ```bash
   mkdir -p data
   chmod 755 data
   ```

2. Fix container permissions:
   ```bash
   docker exec -u root nextav-app chown -R nextjs:nodejs /app/data /app/media
   ```

3. Restart the container:
   ```bash
   docker compose restart nextav
   ```

### Native Module Issues
**Problem**: `Could not locate the bindings file. Tried: ... better_sqlite3.node`

**Solution**:
1. Rebuild the Docker image:
   ```bash
   docker build --no-cache -t nextav:latest ..
   ```

2. Ensure build dependencies are available in Dockerfile

### Container Health Issues
**Problem**: Container shows as "unhealthy"

**Solution**:
1. Check logs:
   ```bash
   docker compose logs nextav
   ```

2. Test health endpoint manually:
   ```bash
   curl http://localhost:3000/api/health
   ```

3. Verify database connectivity and permissions

### Build Performance Issues
**Problem**: Docker build takes too long

**Solutions**:
1. Use multi-stage builds (already implemented)
2. Remove unnecessary packages from production stage
3. Use `.dockerignore` to exclude unnecessary files
4. Consider using build cache

## Best Practices

### Security
- Run container as non-root user (implemented)
- Use specific image tags instead of `latest`
- Regularly update base images
- Scan images for vulnerabilities

### Performance
- Use multi-stage builds to reduce image size
- Implement proper caching strategies
- Monitor resource usage
- Use health checks for reliability

### Data Persistence
- Use named volumes for production
- Regular database backups
- Monitor disk space usage
- Implement proper backup strategies

### Monitoring
- Health check endpoint: `/api/health`
- Application logs: `docker compose logs nextav`
- Resource monitoring: `docker stats`

## Production Deployment

### 1. Environment Setup
```bash
# Production environment variables
NODE_ENV=production
DB_PATH=/var/lib/nextav/data
MEDIA_PATH=/var/lib/nextav/media
```

### 2. Reverse Proxy (Optional)
Configure Nginx or Traefik for SSL termination and load balancing.

### 3. Backup Strategy
```bash
# Database backup
docker exec nextav-app sqlite3 /app/data/media.db ".backup /app/data/backup.db"

# Volume backup
docker run --rm -v nextav_data:/data -v $(pwd):/backup alpine tar czf /backup/nextav_data.tar.gz -C /data .
```

### 4. Monitoring
- Set up log aggregation
- Monitor container health
- Track resource usage
- Set up alerts for failures

## Maintenance

### Regular Tasks
1. **Update Dependencies**: Monthly security updates
2. **Database Maintenance**: Regular backups and optimization
3. **Log Rotation**: Prevent disk space issues
4. **Image Updates**: Keep base images current

### Troubleshooting Commands
```bash
# View logs
docker compose logs -f nextav

# Access container shell
docker exec -it nextav-app sh

# Check resource usage
docker stats nextav-app

# Restart services
docker compose restart nextav

# Update and rebuild
docker compose down
docker build -t nextav:latest ..
docker compose up -d
```

## Support

For issues not covered in this guide:
1. Check application logs
2. Review Docker documentation
3. Consult Next.js deployment guides
4. Open an issue in the project repository

---

**Last Updated**: August 30, 2025
**Version**: 1.0.0