flox-services

# Flox Services Guide

## Running Services in Flox Environments

- Start with `flox activate --start-services` or `flox activate -s`
- Define `is-daemon`, `shutdown.command` for background processes
- Keep services running using `tail -f /dev/null`
- Use `flox services status/logs/restart` to manage (must be in activated env)
- Service commands don't inherit hook activations; explicitly source/activate what you need

## Core Commands

```bash
flox activate -s                # Start services
flox services status            # Check service status
flox services logs <service>    # View service logs
flox services restart <service> # Restart a service
flox services stop <service>    # Stop a service
```

## Network Services Pattern

Always make host/port configurable via vars:

```toml
[services.webapp]
command = '''exec app --host "$APP_HOST" --port "$APP_PORT"'''

[vars]
APP_HOST = "0.0.0.0"  # Network-accessible
APP_PORT = "8080"
```

## Service Logging Pattern

Always pipe to `$FLOX_ENV_CACHE/logs/` for debugging:

```toml
[services.myapp]
command = '''
  mkdir -p "$FLOX_ENV_CACHE/logs"
  exec app 2>&1 | tee -a "$FLOX_ENV_CACHE/logs/app.log"
'''
```

## Python venv Pattern for Services

Services must activate venv independently:

```toml
[services.myapp]
command = '''
  [ -f "$FLOX_ENV_CACHE/venv/bin/activate" ] && \
    source "$FLOX_ENV_CACHE/venv/bin/activate"
  exec python-app "$@"
'''
```

Or use venv Python directly:

```toml
[services.myapp]
command = '''exec "$FLOX_ENV_CACHE/venv/bin/python" app.py'''
```

## Using Packaged Services

Override package's service by redefining with same name.

## Database Service Examples

### PostgreSQL

```toml
[services.postgres]
command = '''
  mkdir -p "$FLOX_ENV_CACHE/postgres"
  if [ ! -d "$FLOX_ENV_CACHE/postgres/data" ]; then
    initdb -D "$FLOX_ENV_CACHE/postgres/data"
  fi
  exec postgres -D "$FLOX_ENV_CACHE/postgres/data" \
    -k "$FLOX_ENV_CACHE/postgres" \
    -h "$POSTGRES_HOST" \
    -p "$POSTGRES_PORT"
'''
is-