# Configuration

## Environment Variables

SGO supports configuration through environment variables. Create a `.env` file in the same directory as your `docker-compose.yml` file.

### Available Options

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `AWS_CONFIG_PATH` | Absolute path to AWS credentials directory | Yes | None |
| `PUID` | User ID for file permissions | No | `1000` |
| `PGID` | Group ID for file permissions | No | `1000` |
| `DATA_PATH` | Path for database storage (local mode) | No | `./data` |
| `SGO_PORT` | Port to expose on host | No | `5000` |
| `DEBUG` | Enable Flask debug logging | No | `false` |
| `FLASK_ENV` | Flask environment | No | `production` |

## Data Storage Options

### Option 1: Docker Volume (Default - Recommended)

- Data stored in Docker-managed volume `sgo-data`
- Survives container restarts and rebuilds
- Better performance on macOS/Windows
- Use default `docker-compose.yml`

```bash
docker-compose up --build
```

### Option 2: Local Directory

- Data stored in `./data` directory
- Easy to backup and access
- Better for development
- Use `docker-compose.local.yml`:

```bash
docker-compose -f docker-compose.local.yml up --build
# or
podman-compose -f docker-compose.local.yml up --build
```

Or edit `docker-compose.yml` and swap the volume configuration as indicated in comments.

## User/Group Configuration

To avoid permission issues, set `PUID` and `PGID` to match your host user:

```bash
# Find your IDs
id -u  # Your PUID
id -g  # Your PGID

# Add to .env file
echo "PUID=$(id -u)" >> .env
echo "PGID=$(id -g)" >> .env
```

## Configuration Examples

### Example 1: Basic Setup (Default)

Minimal configuration with Docker volume:

```bash
# Create .env file
cat > .env << EOF
AWS_CONFIG_PATH=$HOME/.aws
PUID=$(id -u)
PGID=$(id -g)
EOF

# Run
docker-compose up --build
# or: podman-compose up --build
```

### Example 2: Local Data Directory

Store database in local directory for easy access:

```bash
# Create .env file
cat > .env << EOF
AWS_CONFIG_PATH=$HOME/.aws
PUID=$(id -u)
PGID=$(id -g)
DATA_PATH=./data
EOF

# Use the local compose file
docker-compose -f docker-compose.local.yml up --build
```

### Example 3: Custom AWS Credentials Location

If your AWS credentials are in a non-standard location:

```bash
# Create .env file
cat > .env << EOF
AWS_CONFIG_PATH=/path/to/custom/.aws
PUID=$(id -u)
PGID=$(id -g)
EOF

docker-compose up --build
```

### Example 4: Debug Mode

Enable detailed logging for troubleshooting:

```bash
# Create .env file
cat > .env << EOF
AWS_CONFIG_PATH=$HOME/.aws
PUID=$(id -u)
PGID=$(id -g)
DEBUG=true
EOF

docker-compose up --build
```

### Example 5: Custom Port

Run on a different port (e.g., 8080):

```bash
# Create .env file
cat > .env << EOF
AWS_CONFIG_PATH=$HOME/.aws
PUID=$(id -u)
PGID=$(id -g)
SGO_PORT=8080
EOF

# Access at http://localhost:8080
docker-compose up --build
```

## Quick Reference Commands

### Essential Commands

```bash
# Start
docker-compose up --build
# or: podman-compose up --build

# Stop
docker-compose down
# or: Ctrl+C

# View logs
docker-compose logs -f

# Rebuild after changes
docker-compose up --build

# Remove everything including data
docker-compose down -v
```

### Quick .env Setup

```bash
# Minimal configuration for most users
cat > .env << EOF
AWS_CONFIG_PATH=$HOME/.aws
PUID=$(id -u)
PGID=$(id -g)
EOF

# Then run
docker-compose up --build
```

### Data Location

**Docker volume (default)**: Managed by Docker, survives rebuilds

```bash
# Inspect volume
docker volume inspect sgo-data

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

**Local directory**: `./data/aws_export.db`

```bash
# Use local mode
docker-compose -f docker-compose.local.yml up --build
```

## Platform-Specific Notes

### Windows

- Use Git Bash, WSL2, or PowerShell for running scripts
- Docker Desktop must be running
- WSL2 backend recommended for better performance

### macOS

- Docker Desktop must be running
- Ensure Docker has access to your home directory in Docker Desktop settings

### Linux

- You may need to run Docker commands with `sudo` or add your user to the `docker` group
- Podman works without root by default