howto/DOCKER.md

Rama main · réplica de lectura del repositorio original.

# Docker Configuration Guide

This guide covers all available configuration options for running CronMaster in Docker using Docker Compose.

## Basic Configuration

### Service Definition

```yaml
services:
  cronmaster:
    image: ghcr.io/fccview/cronmaster:latest
    container_name: cronmaster
    user: "root"
```

- **image**: The Docker image to use (latest version recommended)
- **container_name**: Name of the container instance
- **user**: User to run the container as (must be root for crontab access)

### Port Configuration

```yaml
ports:
  - "40123:3000" # Host port : Container port
```

- Default port 3000 inside container
- Map to any available host port (40123 shown as example)

## Environment Variables

### Required Environment Variables

```yaml
environment:
  - NODE_ENV=production
  - NEXT_PUBLIC_CLOCK_UPDATE_INTERVAL=30000
  - AUTH_PASSWORD=very_strong_password
  - HOST_CRONTAB_USER=root
```

- **NODE_ENV**: Set to `production` for production deployments
- **NEXT_PUBLIC_CLOCK_UPDATE_INTERVAL**: Clock update interval in milliseconds (default: 30000)
- **AUTH_PASSWORD**: Strong password for authentication
- **HOST_CRONTAB_USER**: User whose crontab to read (default: root, can be comma-separated for multiple users)

### Optional Environment Variables

#### Localization

```yaml
- LOCALE=en # or any locale code (supports custom translations in ./data/translations/)
```

#### Logging Configuration

```yaml
- MAX_LOG_AGE_DAYS=30 # Days to keep logs (default: 30)
- MAX_LOGS_PER_JOB=50 # Maximum logs per job (default: 50)
```

#### Host Paths

Crontab entries run on the host, so the app needs the host paths of its `/app/data` and `/app/scripts` mounts. By default it asks Docker through the mounted socket. Set these when that is not possible (no socket, rootless or remote Docker, unusual mounts):

```yaml
- HOST_DATA_DIR=/home/user/cronmaster/data
- HOST_SCRIPTS_DIR=/home/user/cronmaster/scripts
```

Both must be absolute host paths matching the `volumes` entries. The legacy `HOST_PROJECT_DIR=/home/user/cronmaster` is still honoured as a last resort and maps to `HOST_PROJECT_DIR/data` and `HOST_PROJECT_DIR/scripts`.

#### SSO Authentication (OIDC)

```yaml
- SSO_MODE=oidc
- OIDC_ISSUER=https://your-sso-provider.com
- OIDC_CLIENT_ID=your_client_id
- APP_URL=https://your-cronmaster-domain.com
# Optional SSO settings:
- OIDC_CLIENT_SECRET=your_secret
- OIDC_LOGOUT_URL=https://provider/logout
- OIDC_GROUPS_SCOPE=groups # Scope to request for groups (set to empty string or "no" to disable for providers like Entra ID)
- OIDC_USER_GROUPS=cronmaster_users,ops # Restrict access to users in these groups
- OIDC_USER_ROLES=user,member # Restrict access to users with these roles
- NODE_TLS_REJECT_UNAUTHORIZED=0 # For self-signed certificates
```

See [SSO.md](SSO.md) for detailed SSO setup instructions.

#### API Key Protection

```yaml
- API_KEY=your-secret-api-key-here
```

See [API.md](API.md) for API key usage instructions.

#### Live Updates

```yaml
- LIVE_UPDATES=false # Set to false to disable Server-Sent Events
```

#### Disk Space and Inodes

```yaml
- DISK_MOUNTS=/,/mnt/data
```

Set `DISABLE_DISK_STATS=true` to turn the disk cards off entirely.

By default only the host root filesystem is shown. With `pid: "host"` and `privileged: true` Cr\*nMaster reads host mounts through `/proc/1/root/<mount>`, so no extra volumes are needed. Each listed mount gets a single `statfs` call at most once per minute, and only when system stats are actually requested (the sidebar polls them while the page is visible). `statfs` reads filesystem counters, never file contents, but on some setups (mergerfs, network shares, sleepy USB disks) it can still wake the underlying drives, so only add mounts you are happy to have checked.

#### Execution Shell

```yaml
- EXECUTION_SHELL=/bin/bash # Optional, shell used by "Run now" via su -s
- STRICT_EXECUTION_USER=true # Optional, "Run now" fails instead of running as root when the job user is missing on the host
```

"Run now" enters the host with `nsenter` and switches to the job's user with `su`. By default the user's login shell is used, and service users with no login shell (`/usr/sbin/nologin`, `/bin/false`) automatically fall back to `/bin/sh`, so jobs owned by users like `www-data` run fine. Set `EXECUTION_SHELL` to force one shell for every manual run. Scheduled runs go through the host's cron and ignore this setting.

## Volume Mounts

### Required Volumes

```yaml
volumes:
  # Docker socket for command execution
  - /var/run/docker.sock:/var/run/docker.sock

  # Data persistence
  - ./scripts:/app/scripts
  - ./data:/app/data
  - ./snippets:/app/snippets
```

- **Docker socket**: Required for executing commands on the host
- **./scripts**: Directory for custom scripts created via the app
- **./data**: Application data directory
- **./snippets**: Code snippets directory

### Optional Host Data Mounts

If you want to keep data on the host machine instead of Docker volumes:

```yaml
- ./scripts:/app/scripts
- ./data:/app/data
- ./snippets:/app/snippets
```

**Note**: Do not change the container paths - the application expects these specific locations.

## Container Configuration

### Runtime Configuration

```yaml
pid: "host" # Use host PID namespace for command execution
privileged: true # Required for nsenter access
restart: always # Always restart container
init: true # Use init process
```

### Platform Configuration

```yaml
platform: linux/arm64 # For ARM64 systems (default: linux/amd64)
```

## Complete Example

Here's a complete example with all optional configurations:

```yaml
services:
  cronmaster:
    image: ghcr.io/fccview/cronmaster:latest
    container_name: cronmaster
    user: "root"
    ports:
      - "40123:3000"
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_CLOCK_UPDATE_INTERVAL=30000

      # Localization
      - LOCALE=en

      # Logging
      - MAX_LOG_AGE_DAYS=30
      - MAX_LOGS_PER_JOB=50

      # Authentication
      - AUTH_PASSWORD=very_strong_password

      # SSO (optional)
      - SSO_MODE=oidc
      - OIDC_ISSUER=https://your-sso-provider.com
      - OIDC_CLIENT_ID=your_client_id
      - APP_URL=https://your-cronmaster-domain.com
      - OIDC_CLIENT_SECRET=your_secret
      - OIDC_LOGOUT_URL=https://provider/logout
      - OIDC_GROUPS_SCOPE=groups
      - OIDC_USER_GROUPS=cronmaster_users

      # API Key (optional)
      - API_KEY=your-secret-api-key-here

      # Live Updates
      - LIVE_UPDATES=true

      # Crontab Users
      - HOST_CRONTAB_USER=root
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./scripts:/app/scripts
      - ./data:/app/data
      - ./snippets:/app/snippets
    pid: "host"
    privileged: true
    restart: always
    init: true
    platform: linux/amd64
```

## Security Considerations

- The container runs as root and requires privileged access for crontab management
- The Docker socket is mounted for command execution capabilities
- Choose strong passwords for authentication
- Consider using SSO for enhanced security in production environments

## Troubleshooting

- Ensure Docker socket is accessible: `ls -la /var/run/docker.sock`
- Check crontab user exists: `ls -asl /var/spool/cron/crontabs/`
- Verify port 40123 (or your chosen port) is available
- Check container logs: `docker logs cronmaster`