# SamCloud Music App - Server Setup Guide for Girlfriend

This guide explains how to set up the SamCloud Music App on a new server for your girlfriend's testing.

## Prerequisites

Before starting, ensure the server has:

1. Docker and Docker Compose installed
2. At least 4GB RAM (8GB recommended)
3. At least 20GB free disk space
4. Internet access
5. Open ports 5140 (backend) and 5143 (frontend)

## Required Configuration Changes

Before deploying, you'll need to update several configuration values:

### 1. Environment Variables (setup/.env.girlfriend)

Update these values in the `.env.girlfriend` file:

```bash
# Jellyfin Configuration - REPLACE WITH YOUR ACTUAL VALUES
JELLYFIN_URL=https://your-jellyfin-server.com
JELLYFIN_API_KEY=your_actual_api_key_here

# Output Configuration for separate directory
OUTPUT_DIR=/app/downloads/girlfriend

# Playlist Configuration for separate playlist
GIRLFRIEND_PLAYLIST_NAME=girlfriend_test_playlist
M3U_PLAYLIST_PATH=/app/downloads/girlfriend/playlists
```

### 2. Docker Compose Configuration (setup/docker-compose.girlfriend.yml)

Update the volume mappings to match your server's directory structure:

```yaml
volumes:
  - /path/to/your/jellyfin/music:/music  # Final music files
  - /path/to/your/jellyfin/temp:/temp  # Temporary files
```

Also update any port mappings if needed:

```yaml
ports:
  - "5145:5145"  # Backend port
  - "5146:5146"  # Frontend port
```

## Installation Steps

1. Copy the entire application directory to your server

2. Navigate to the application directory:
   ```bash
   cd /path/to/samcloud-music-app
   ```

3. Update the configuration files as described above

4. Start the application:
   ```bash
   docker-compose -f setup/docker-compose.girlfriend.yml up -d
   ```

5. Wait 2-3 minutes for services to initialize

6. Access the application at `http://your-server-ip:5146`

## Directory Structure for Clean Installation

For a clean installation, use this directory structure:

```
samcloud-music-app/
├── server/                 # Backend code
├── src/                    # Frontend source
├── public/                 # Static assets
├── setup/                  # Girlfriend's setup files
│   ├── docker-compose.girlfriend.yml
│   └── .env.girlfriend
├── docs/                   # Documentation
│   └── girlfriend-setup/   # Girlfriend-specific docs
├── package.json            # Frontend dependencies
├── docker-compose.yml      # Main Docker config
├── Dockerfile              # Backend Docker config
├── Dockerfile.ui           # Frontend Docker config
├── .env                    # Main environment
├── .env.production         # Production environment
└── vite.config.ts          # Frontend build config
```

## Important Notes

1. **Data Isolation**: The girlfriend's setup uses separate directories and playlist names to avoid interfering with your main library.

2. **Resource Usage**: The setup includes resource limits to prevent impacting server performance.

3. **Port Conflicts**: If you're running this on the same server as your main instance, ensure ports don't conflict.

4. **Jellyfin Integration**: Make sure the Jellyfin URL and API key are correct for proper integration.

## Troubleshooting

### Common Issues

1. **Docker Permission Errors**:
   ```bash
   sudo usermod -aG docker $USER
   # Then log out and back in
   ```

2. **Port Already in Use**:
   Change the ports in `docker-compose.girlfriend.yml`

3. **Volume Mount Issues**:
   Ensure directories exist and have proper permissions:
   ```bash
   sudo mkdir -p /path/to/jellyfin/music
   sudo mkdir -p /path/to/jellyfin/temp
   sudo chown -R $USER:$USER /path/to/jellyfin
   ```

4. **Download Issues**:
   Check the backend logs:
   ```bash
   docker-compose -f setup/docker-compose.girlfriend.yml logs backend-girlfriend
   ```

### Checking Service Status

```bash
# Check if services are running
docker-compose -f setup/docker-compose.girlfriend.yml ps

# View logs
docker-compose -f setup/docker-compose.girlfriend.yml logs

# View specific service logs
docker-compose -f setup/docker-compose.girlfriend.yml logs backend-girlfriend
```

## Stopping the Services

To stop the services:

```bash
docker-compose -f setup/docker-compose.girlfriend.yml down
```

To stop and remove all data (including downloaded files):

```bash
docker-compose -f setup/docker-compose.girlfriend.yml down -v
```