littleshop/DEPLOYMENT.md

# LittleShop Deployment Guide

## Portainer Deployment to portainer-01 (10.0.0.51)

This guide covers deploying LittleShop to your Portainer infrastructure with Traefik routing.

### Prerequisites

1. **Portainer** running on `portainer-01 (10.0.0.51)`
   - Username: `sysadmin`
   - Password: `Phenom12#.`

2. **Traefik** running on `portainer-03` with:
   - External network named `traefik`
   - Let's Encrypt SSL certificate resolver named `letsencrypt`
   - Entry point named `websecure` (port 443)

3. **DNS Configuration**
   - `littleshop.silverlabs.uk` should point to your Traefik instance

### Deployment Steps

#### Step 1: Access Portainer
1. Navigate to `http://10.0.0.51:9000` (or your Portainer URL)
2. Login with `sysadmin` / `Phenom12#.`

#### Step 2: Create Environment Variables
1. Go to **Stacks** → **Add stack**
2. Name: `littleshop`
3. In the environment variables section, add:
   ```
   JWT_SECRET_KEY=YourSuperSecretKeyThatIsAtLeast32CharactersLong!
   BTCPAY_SERVER_URL=https://your-btcpay-server.com
   BTCPAY_STORE_ID=your-store-id
   BTCPAY_API_KEY=your-api-key
   BTCPAY_WEBHOOK_SECRET=your-webhook-secret
   ```

#### Step 3: Deploy the Stack
1. Copy the contents of `docker-compose.yml` into the web editor
2. Click **Deploy the stack**

#### Step 4: Verify Deployment
1. Check that the container is running in **Containers** view
2. Visit `https://littleshop.silverlabs.uk` to confirm the application is accessible

### Configuration Details

#### Traefik Labels Configuration
The docker-compose includes these Traefik labels:
- **Host Rule**: `littleshop.silverlabs.uk`
- **HTTPS**: Enabled with Let's Encrypt
- **Port**: Internal port 8080
- **Headers**: Proper forwarding headers for ASP.NET Core

#### Persistent Storage
Three volumes are created:
- `littleshop_data`: SQLite database and application data
- `littleshop_uploads`: Product images and file uploads  
- `littleshop_logs`: Application log files

#### Security Configuration
- Application runs on internal port 8080
- HTTPS enforced through Traefik
- JWT secrets configurable via environment variables
- Forwarded headers properly configured for reverse proxy

### Environment Variables

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `JWT_SECRET_KEY` | Secret key for JWT token signing | Yes | Default provided |
| `BTCPAY_SERVER_URL` | BTCPay Server URL | No | Empty |
| `BTCPAY_STORE_ID` | BTCPay Store ID | No | Empty |
| `BTCPAY_API_KEY` | BTCPay API Key | No | Empty |
| `BTCPAY_WEBHOOK_SECRET` | BTCPay Webhook Secret | No | Empty |

### Initial Setup

#### Default Admin Account
On first run, the application creates a default admin account:
- **Username**: `admin`
- **Password**: `admin`
- **⚠️ IMPORTANT**: Change this password immediately after deployment!

#### Post-Deployment Steps
1. Visit `https://littleshop.silverlabs.uk/Admin`
2. Login with `admin` / `admin`
3. Change the admin password
4. Configure categories and products
5. Set up BTCPay Server integration if needed

### Troubleshooting

#### Container Won't Start
- Check environment variables are set correctly
- Verify Traefik network exists: `docker network ls`
- Check container logs in Portainer

#### SSL Certificate Issues
- Ensure DNS points to Traefik instance
- Check Traefik logs for Let's Encrypt errors
- Verify `letsencrypt` resolver is configured

#### Application Errors
- Check application logs in `/app/logs/` volume
- Verify database permissions in `/app/data/` volume
- Ensure file upload directory is writable

#### Database Issues
- Database is automatically created on first run
- Data persists in `littleshop_data` volume
- Location: `/app/data/littleshop.db`

### Updating the Application

1. In Portainer, go to **Stacks** → **littleshop**
2. Click **Editor**
3. Update the image tag or configuration as needed
4. Click **Update the stack**

### Backup and Restore

#### Backup
```bash
# Backup volumes
docker run --rm -v littleshop_littleshop_data:/data -v $(pwd):/backup alpine tar czf /backup/littleshop-data-backup.tar.gz -C /data .
docker run --rm -v littleshop_littleshop_uploads:/data -v $(pwd):/backup alpine tar czf /backup/littleshop-uploads-backup.tar.gz -C /data .
```

#### Restore
```bash
# Restore volumes
docker run --rm -v littleshop_littleshop_data:/data -v $(pwd):/backup alpine tar xzf /backup/littleshop-data-backup.tar.gz -C /data
docker run --rm -v littleshop_littleshop_uploads:/data -v $(pwd):/backup alpine tar xzf /backup/littleshop-uploads-backup.tar.gz -C /data
```

### Support

For issues or questions:
1. Check application logs in Portainer
2. Verify Traefik configuration
3. Ensure all environment variables are set correctly
4. Check network connectivity between containers

---

**Deployment Status**: ✅ Ready for Production  
**Hostname**: `https://littleshop.silverlabs.uk`  
**Admin Panel**: `https://littleshop.silverlabs.uk/Admin`