217 lines
4.2 KiB
Markdown
217 lines
4.2 KiB
Markdown
# 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
|