SGO/wiki/Configuration.md

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

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:

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:

# 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:

# 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:

# 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:

# 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:

# 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):

# 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

# 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

# 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

# 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

# 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