### Full Container Configuration with `docker run`

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/configuration-reference.md

An example of a complete `docker run` command to start a SATOSA container with essential environment variables configured. Includes base URL, encryption key, and SAML discovery service.

```bash
docker run \
  --name satosa \
  -p 8080:8080 \
  -e BASE_URL="https://satosa.example.com" \
  -e STATE_ENCRYPTION_KEY="ABC123DEF456GHI789JKL012MNO345P" \
  -e SAML2_BACKEND_DISCO_SRV="https://ds.example.com/discovery" \
  satosa:8.5
```

--------------------------------

### Debian Stage 1: Runtime Dependencies and Setup

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Sets up the SATOSA user, installs runtime dependencies like jq, xmlsec1, and yq on Debian.

```dockerfile
RUN set -eux; \
    groupadd -g 1000 satosa; \
    useradd -m -g 1000 -u 1000 satosa; \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        jq libxml2-utils xmlsec1; \
    rm -rf /var/lib/apt/lists/*; \
    pip install --no-cache-dir yq;
```

--------------------------------

### Alpine Stage 1: Runtime Dependencies and Setup

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Sets up the SATOSA user, installs runtime dependencies like bash, jq, and yq on Alpine.

```dockerfile
RUN set -eux; \
    addgroup --gid 1000 satosa; \
    adduser -D -G satosa --uid 1000 satosa; \
    apk add --no-cache bash jq libxml2-utils openssl xmlsec; \
    pip install --no-cache-dir yq;
```

--------------------------------

### Docker Build Command Example

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Example command to build a SATOSA Docker image for a specific version and variant. Ensure the path points to the generated Dockerfile.

```bash
docker build -t satosa:8.5 8.5/bookworm/
```

--------------------------------

### Test Application Startup Help

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/implementation-notes.md

Ensures the SATOSA application starts correctly and displays its help message.

```bash
docker run --rm satosa:8.5 --help
```

--------------------------------

### Container Initialization Process

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Illustrates the sequence of steps executed when a Satosa Docker container starts, from entrypoint script to gunicorn execution.

```bash
# Container start
#    ↓
# Entrypoint: docker-entrypoint.sh
#    ↓
# Check if command is gunicorn
#    ↓
# YES → docker_setup_env()
#    │   ├─→ Load BASE_URL (or use default)
#    │   ├─→ Load STATE_ENCRYPTION_KEY (or generate)
#    │   ├─→ Load SAML2 discovery service
#    │   ├─→ Load certificate env vars
#    │   └─→ Set HOSTNAME from BASE_URL
#    │
#    └→ docker_create_config()
#       ├─→ Generate proxy_conf.yaml
#       ├─→ Generate internal_attributes.yaml
#       ├─→ Generate SAML2 backend/frontend configs
#       ├─→ Generate/use backend certificates
#       └─→ Generate/use frontend certificates
#    │
#    └→ docker_pprint_metadata()
#       ├─→ Generate SAML2 metadata
#       └─→ Print metadata to stdout
#    │
# NO → Pass through to command
#
# Execute: gunicorn -b0.0.0.0:8080 satosa.wsgi:app
```

--------------------------------

### Local SATOSA Docker Development Setup

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Steps to clone the repository, build a development image, and run SATOSA with a local configuration directory.

```bash
# Clone repository
git clone https://github.com/IdentityPython/satosa-docker.git
cd satosa-docker

# Build current version
docker build -t satosa:dev 8.5/bookworm/

# Run with local configuration directory
docker run \
  -p 8080:8080 \
  -v $(pwd)/test-config:/etc/satosa \
  -e BASE_URL="https://localhost:8080" \
  satosa:dev
```

--------------------------------

### Dockerfile for Adding Custom SATOSA Plugins

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Example Dockerfile to build a custom SATOSA image by installing additional Python packages and copying custom configuration.

```dockerfile
# Build on top of official image
FROM satosa:8.5

# Install additional packages
RUN pip install --no-cache-dir satosa-custom-plugin

# Example config with custom plugin
COPY custom_plugin_config.yaml /etc/satosa/plugins/backends/

# Keep original entrypoint
ENTRYPOINT ["docker-entrypoint.sh"]
```

--------------------------------

### Download and Extract SATOSA Example Configuration

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

This Dockerfile stage downloads the SATOSA release archive, extracts only the example configuration directory, and stores it for later use. It also handles version parsing to fetch the correct release.

```dockerfile
RUN set -eux; \
    python -c 'import urllib.request; \
      urllib.request.urlretrieve(
        "https://github.com/IdentityPython/SATOSA/archive/refs/tags/v${SATOSA_VERSION%%[a-z]*}.tar.gz",
        "/tmp/satosa.tgz")'; \
    mkdir /usr/share/satosa; \
    tar --extract --directory /usr/share/satosa \
      --strip-components=1 --file /tmp/satosa.tgz \
      SATOSA-${SATOSA_VERSION%%[a-z]*}/example/; \
    rm /tmp/satosa.tgz
```

--------------------------------

### Tag Generation Examples

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Demonstrates how version and variant information translate into Docker image tags for different scenarios.

```text
Version 8.5.1, Variant bookworm:
  ├─→ Full version tags: 8.5.1, 8.5, 8, latest
  ├─→ Variant tags: 8.5.1-bookworm, 8-bookworm
  └─→ Shared: (promoted to main repo aliases)

Version 8.5.1, Variant alpine3.22:
  ├─→ Full version tags: 8.5.1-alpine, 8.5-alpine, 8-alpine, latest-alpine
  ├─→ Explicit tags: 8.5.1-alpine3.22
  └─→ Shared: (none, only if default)
```

--------------------------------

### User and Permissions Setup

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/build-scripts-reference.md

Creates a dedicated 'satosa' user and group, and sets ownership for the configuration directory.

```dockerfile
# Alpine
addgroup --gid 1000 satosa
adduser -D -G satosa --uid 1000 satosa

# Debian
groupadd -g 1000 satosa
useradd -m -g 1000 -u 1000 satosa

# Both
mkdir /etc/satosa
chown -R satosa:satosa /etc/satosa
```

--------------------------------

### Kubernetes Secret Setup for SATOSA Certificates and Configuration

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

This example shows how to create Kubernetes secrets for TLS certificates (backend and frontend) and sensitive configuration like the encryption key before deploying SATOSA.

```bash
# Create namespace
kubectl create namespace satosa

# Create secret for certificates
kubectl create secret tls satosa-backend \
  --cert=backend.crt --key=backend.key \
  -n satosa

kubectl create secret tls satosa-frontend \
  --cert=frontend.crt --key=frontend.key \
  -n satosa

# Create secret for encryption key
kubectl create secret generic satosa-config \
  --from-literal=STATE_ENCRYPTION_KEY="MySecureKey1234567890123456789012" \
  -n satosa
```

--------------------------------

### Install SATOSA with Extensions

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Installs the specified SATOSA version along with selected extensions like OIDC, LDAP, MongoDB, and Redis support.

```dockerfile
pip install --no-cache-dir \
    satosa[idpy_oidc_backend,ldap,pyop_mongo,pyop_redis]==${SATOSA_VERSION}
```

--------------------------------

### Data Flow Example

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/README.md

Illustrates the data flow within the SATOSA Docker container, from environment variables to configuration files and the SATOSA application.

```text
Environment Variables
  ↓
docker_setup_env()
  ↓
docker_create_config()
  ↓
Configuration Files (/etc/satosa/*)
  ↓
SATOSA Application
```

--------------------------------

### View SATOSA Startup Logs

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Start a SATOSA container and view its full startup output, or capture logs from an already running container. This helps in diagnosing initialization issues.

```bash
# Run container and see full output
docker run \
  -e BASE_URL="https://test.example.com" \
  satosa:8.5

# Or capture logs
docker logs <container-id>
```

--------------------------------

### jq Commands for Checking SATOSA Versions

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Examples using jq to inspect available SATOSA versions and their variants from the versions.json file.

```bash
# Show all available versions
jq keys versions.json

# Show specific version details
jq '.["8.5"]' versions.json

# List all variants
jq '.["8.5"].variants' versions.json
```

--------------------------------

### Kubernetes Deployment with PersistentVolume

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Example Kubernetes Deployment and PersistentVolumeClaim for deploying SATOSA with persistent configuration storage.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: satosa
  namespace: satosa
spec:
  replicas: 2
  selector:
    matchLabels:
      app: satosa
  template:
    metadata:
      labels:
        app: satosa
    spec:
      containers:
      - name: satosa
        image: satosa:8.5
        imagePullPolicy: Always
        ports:
        - name: http
          containerPort: 8080
        env:
        - name: BASE_URL
          value: "https://satosa.example.com"
        - name: STATE_ENCRYPTION_KEY
          valueFrom:
            secretKeyRef:
              name: satosa-config
              key: STATE_ENCRYPTION_KEY
        volumeMounts:
        - name: config
          mountPath: /etc/satosa
      volumes:
      - name: config
        persistentVolumeClaim:
          claimName: satosa-config

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: satosa-config
  namespace: satosa
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
```

--------------------------------

### Jq-Template Syntax Examples

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Illustrates the syntax for conditional blocks, variable access, jq expressions, environment access, and function definitions within jq-templates.

```jq
# Conditional blocks
{{ if condition then ( code ) else ( code ) end }}

# Variables (jq context)
{{ env.VARIABLE }}

# jq expressions
{{ .field | select(...) }}

# Environment access
$ENV.VARIABLE

# Function definitions
{{ def is_alpine: env.variant | contains("alpine") }}
```

--------------------------------

### Create Configuration File from Template

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/entrypoint-functions.md

Generates configuration files from example templates, applying optional filters for JSON, XML, or YAML. Use to create configuration files with dynamic values or transformations.

```bash
# Create proxy config with custom BASE URL
_make_conffile proxy_conf.yaml '.BASE = "https://myhost.com"'

# Create internal attributes config, removing specific fields
_make_conffile internal_attributes.yaml 'del(.hash, .user_id_from_attrs)'

# Create SAML2 backend config with discovery service
_make_conffile plugins/backends/saml2_backend.yaml \
  'del(.config.acr_mapping) | .config.disco_srv = "https://service.seamlessaccess.org/ds/"'
```

--------------------------------

### Runtime Dependency Detection (Alpine)

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Shows how to detect and install runtime dependencies in Alpine using scanelf to ensure only necessary libraries are included.

```bash
find /usr/local -type f -executable \
  -exec scanelf --needed --nobanner --format '%n#p' '{}' ';' \
  | ... | apk add --no-network --virtual .satosa-rundeps
```

--------------------------------

### Access and View SATOSA Configuration Files

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Connect to a running SATOSA container to inspect generated configuration files and certificates. This is crucial for debugging and verifying setup.

```bash
# Get into running container
docker exec -it <container-id> /bin/bash

# View configuration
cat /etc/satosa/proxy_conf.yaml
cat /etc/satosa/internal_attributes.yaml
cat /etc/satosa/plugins/backends/saml2_backend.yaml

# Check certificates
openssl x509 -in /etc/satosa/backend.crt -text -noout
openssl x509 -in /etc/satosa/frontend.crt -text -noout

# Check SAML metadata
cat /etc/satosa/backend.xml
cat /etc/satosa/frontend.xml
```

--------------------------------

### Launch SATOSA Container with Production Configuration

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Deploys SATOSA in a production-ready setup, including persistent storage for configuration, custom environment variables for security and backend discovery, and volume mounts for certificates.

```bash
docker run \
  --name satosa-prod \
  --restart unless-stopped \
  -p 8080:8080 \
  -e BASE_URL="https://satosa.example.com" \
  -e STATE_ENCRYPTION_KEY="MySecureEncryptionKey1234567890123456789012" \
  -e SAML2_BACKEND_DISCO_SRV="https://ds.example.com/discovery" \
  -e SAML2_BACKEND_CERT_FILE="/run/secrets/backend_cert" \
  -e SAML2_BACKEND_KEY_FILE="/run/secrets/backend_key" \
  -e SAML2_FRONTEND_CERT_FILE="/run/secrets/frontend_cert" \
  -e SAML2_FRONTEND_KEY_FILE="/run/secrets/frontend_key" \
  -v /path/to/certs:/run/secrets:ro \
  -v satosa_config:/etc/satosa \
  satosa:8.5
```

--------------------------------

### Example versions.json Structure

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Illustrates the JSON structure used to define SATOSA versions, their corresponding Python versions, and available image variants (e.g., bookworm, alpine).

```json
{
  "8.5": {
    "python_version": "3.13",
    "version": "8.5.1",
    "variants": ["bookworm", "alpine3.22"]
  }
}
```

--------------------------------

### Debian Package Manager Commands

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Standard commands for updating, installing, and cleaning up packages using apt-get on Debian-based images.

```bash
apt-get update
apt-get install -y --no-install-recommends [packages]
apt-get purge -y --auto-remove
```

--------------------------------

### Process Version Results

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Provides examples of processing version strings, including filtering out pre-releases and sorting versions numerically. Useful for determining the latest stable release.

```bash
# Filter out pre-releases (rc, alpha, beta)
grep -v -E -- '[a-zA-Z]+'
```

```bash
# Sort versions numerically (highest first)
sort -ruV
```

```bash
# Take latest
possibles=(...)
fullVersion="${possibles[0]}"
```

--------------------------------

### Run Gunicorn with Default Command

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/entrypoint-functions.md

This command starts the Gunicorn WSGI server, triggering the full initialization sequence before launching the SATOSA application. It binds to all network interfaces on port 8080.

```bash
CMD ["gunicorn", "-b0.0.0.0:8080", "satosa.wsgi:app"]
```

--------------------------------

### Test Configuration Generation with Docker

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Run a SATOSA Docker container temporarily to generate and view the proxy configuration file without starting the full service. This is useful for validating configuration generation logic.

```bash
docker run --rm \
  -e BASE_URL="https://test.example.com" \
  -e STATE_ENCRYPTION_KEY="test_key_123456789012345678901234" \
  satosa:8.5 \
  cat /etc/satosa/proxy_conf.yaml
```

--------------------------------

### Conditional Execution Based on Command

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Executes specific setup functions only when the script is invoked with a particular command (e.g., 'gunicorn'). After conditional execution, it executes the provided command.

```bash
# Run setup only for specific commands
if [ "$1" = "gunicorn" ]; then
    docker_setup_env
    docker_create_config
    docker_pprint_metadata
fi

exec "$@"
```

--------------------------------

### Integrate SATOSA with Docker Secrets using Docker Swarm

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

This example demonstrates how to create Docker secrets for sensitive information like base URL, encryption keys, and certificates, and then deploy SATOSA as a service using these secrets.

```bash
# Create secrets
echo "https://satosa.example.com" | docker secret create base_url -
echo "MyStateKey1234567890123456789012" | docker secret create state_key -
openssl req -batch -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout backend.key -out backend.crt -subj "/CN=satosa.example.com"
docker secret create backend_cert - < backend.crt
docker secret create backend_key - < backend.key

# Service definition
docker service create \
  --name satosa \
  --publish published=8080,target=8080 \
  --secret base_url \
  --secret state_key \
  --secret backend_cert \
  --secret backend_key \
  -e BASE_URL_FILE=/run/secrets/base_url \
  -e STATE_ENCRYPTION_KEY_FILE=/run/secrets/state_key \
  -e SAML2_BACKEND_CERT_FILE=/run/secrets/backend_cert \
  -e SAML2_BACKEND_KEY_FILE=/run/secrets/backend_key \
  satosa:8.5
```

--------------------------------

### Debian Stage 3: Track Build Dependencies

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Tracks and installs temporary build dependencies for SATOSA on Debian, saving the initial manual package list.

```dockerfile
savedAptMark="$(apt-mark showmanual)"
apt-get update
apt-get install -y --no-install-recommends \
    cargo dirmngr dpkg-dev gcc gnupg \
    [... more packages ...]
```

--------------------------------

### Environment Variable Conflict Example

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Demonstrates an error scenario where both BASE_URL and BASE_URL_FILE environment variables are set, causing the container to exit with an error. Use only one method for setting the base URL.

```bash
# ERROR: both BASE_URL and BASE_URL_FILE are set
export BASE_URL="value"
export BASE_URL_FILE="/path/to/file"
docker run ... # Exits with error code 1
```

--------------------------------

### Source Docker Entrypoint Functions

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/README.md

Source the Docker entrypoint script to make its functions available in the current shell session. This is useful for debugging or manual setup.

```bash
#!/bin/bash
. /path/to/docker-entrypoint.sh
docker_setup_env
docker_create_config
```

--------------------------------

### Load Docker Secrets for Configuration

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/implementation-notes.md

Example of exporting environment variables that point to secret files. The `file_env` function in SATOSA handles loading these secrets.

```bash
export BASE_URL_FILE=/run/secrets/base_url
export STATE_ENCRYPTION_KEY_FILE=/run/secrets/state_key
```

--------------------------------

### Pull SATOSA Alpine-based Image

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Example commands to pull the minimal Alpine-based SATOSA Docker image from Docker Hub, including specific version and variant tags.

```bash
# Alpine-based (minimal)
docker pull satosa:8.5-alpine
docker pull satosa:8.5-alpine3.22
docker pull satosa:latest-alpine
```

--------------------------------

### Generated versions.json format

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/build-scripts-reference.md

Example structure of the `versions.json` file, which stores SATOSA version, latest Python version, and supported image variants. This file is used by `apply-templates.sh`.

```json
{
  "8.5": {
    "python_version": "3.13",
    "version": "8.5.1",
    "variants": [
      "bookworm",
      "alpine3.22"
    ]
  }
}
```

--------------------------------

### Initialize Environment Variables with Defaults

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/entrypoint-functions.md

Sets up environment variables using the `file_env` function, providing default values. This is typically the first function called in the entrypoint script.

```bash
docker_setup_env
```

--------------------------------

### jq Filter: Array Manipulation

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Example of manipulating arrays within JSON using jq.

```bash
# Array manipulation
jq '.FRONTEND_MODULES = ["saml2", "ping"]'
```

--------------------------------

### Debian Linux Dependencies

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/build-scripts-reference.md

Installs runtime and build dependencies for Debian-based Docker images using apt-get.

```dockerfile
apt-get update
apt-get install -y --no-install-recommends \
    jq \
    libxml2-utils \
    xmlsec1 \

apt-get install -y --no-install-recommends \
    [build dependencies]

# After build:
apt-mark auto '.*' 
apt-get purge -y --auto-remove
```

--------------------------------

### Prepare Version Directory

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Create a new directory for the version being added.

```bash
mkdir 8.6
```

--------------------------------

### Alpine Linux Dependencies

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/build-scripts-reference.md

Installs runtime and build dependencies for Alpine-based Docker images using apk.

```dockerfile
apk add --no-cache \
    bash \
    jq \
    libxml2-utils \
    openssl \
    xmlsec \

apk add --no-cache --virtual .build-deps \
    [build dependencies]

# After build:
apks del --no-network .build-deps
```

--------------------------------

### jq Filter: Delete Fields

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Example of using jq to remove specific fields from a JSON structure.

```bash
# Delete specific fields
jq 'del(.hash, .user_id_from_attrs)'
```

--------------------------------

### Test full container startup

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/README.md

Tests the full container startup by running a SATOSA container and then sending a ping request to verify its availability. This is an end-to-end test to ensure the container is operational.

```bash
# Test full container startup
docker run -p 8080:8080 satosa:8.5
curl http://localhost:8080/satosa/ping
```

--------------------------------

### Test Multi-architecture Image Build

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/implementation-notes.md

Demonstrates building a Docker image for multiple architectures (e.g., amd64, arm64) using buildx.

```bash
# Using QEMU
docker run --rm --platform linux/arm64 satosa:8.5 uname -m
# Output: aarch64

# Using buildx
docker buildx build --platform linux/amd64,linux/arm64 -t satosa:8.5 .
```

--------------------------------

### Launch SATOSA Container with Minimal Configuration

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

A minimal configuration for launching SATOSA, primarily setting a custom base URL while relying on other defaults. Useful for development environments.

```bash
# All defaults, except custom URL
docker run \
  -p 8080:8080 \
  -e BASE_URL="https://dev.example.com" \
  satosa:8.5
```

--------------------------------

### Bootstrap New Version

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/build-scripts-reference.md

Initializes a new version directory and updates version information. This step queries SATOSA releases and generates Dockerfiles from templates.

```bash
mkdir 8.5
./update.sh 8.5
```

--------------------------------

### Set SATOSA Version Environment Variable

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Sets the SATOSA_VERSION environment variable, which is used in subsequent build steps for package installation.

```dockerfile
ENV SATOSA_VERSION=8.5.1
```

--------------------------------

### Alpine Dependency Cleanup with scanelf

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Uses scanelf to identify and ensure only actual library dependencies are installed, excluding build tools.

```bash
find /usr/local -type f -executable \
  -not \( -name '*tkinter*' \)
  -exec scanelf --needed --nobanner --format '%n#p' '{}' ';' 
```

--------------------------------

### Entrypoint and Command Configuration

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/build-scripts-reference.md

Sets the working directory, copies the entrypoint script, and defines the default command for the container.

```dockerfile
WORKDIR /etc/satosa
COPY docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]
EXPOSE 8080
USER satosa:satosa
CMD ["gunicorn", "-b0.0.0.0:8080", "satosa.wsgi:app"]
```

--------------------------------

### Launch SATOSA Container with Default Configuration

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

This command launches a SATOSA container using the default configuration. It automatically generates necessary keys, certificates, and configuration files.

```bash
# Default configuration
docker run satosa:8.5

# Output includes:
# - Auto-generated STATE_ENCRYPTION_KEY
# - Auto-generated self-signed certificates
# - Auto-generated configuration files
```

--------------------------------

### _is_sourced Usage: Conditional Execution

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Example of using _is_sourced to conditionally execute a main function, allowing the script to be sourced or run directly.

```bash
# Allow script to be sourced or executed
if ! _is_sourced; then
    _main "$@"
fi
```

--------------------------------

### Build SATOSA Image for Multiple Architectures

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Builds a SATOSA Docker image for multiple target architectures (e.g., amd64 and arm64) using Docker's buildx feature. Requires QEMU to be set up.

```bash
# Build for specific architecture (requires QEMU)
docker buildx build --platform linux/amd64,linux/arm64 \
  -t satosa:8.5 8.5/bookworm/
```

--------------------------------

### Dockerfile for Multi-stage Build

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Demonstrates a multi-stage Docker build to create smaller runtime images by separating build steps.

```dockerfile
# Stage 1: Build
FROM satosa:8.5 as builder
WORKDIR /app
# Build steps here

# Stage 2: Runtime
FROM satosa:8.5
COPY --from=builder /app /app
CMD ["gunicorn", "-b0.0.0.0:8080", "satosa.wsgi:app"]
```

--------------------------------

### Deploy a SATOSA Container

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/README.md

Run a SATOSA container, exposing port 8080 and setting the base URL.

```bash
docker run -p 8080:8080 \
  -e BASE_URL="https://satosa.example.com" \
  satosa:8.5
```

--------------------------------

### Extract Basename from Path

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Extracts the basename from a given file path using the 'basename' command. Useful for getting the last component of a path, such as a directory name.

```bash
# Extract basename from path
variant="$(basename "$dir")"  # "alpine3.22" from "8.5/alpine3.22"
```

--------------------------------

### Review and Test Generated Dockerfiles

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/build-scripts-reference.md

Displays the generated Dockerfiles for review and builds/runs Docker images for testing.

```bash
# Generated files
cat 8.5/bookworm/Dockerfile
cat 8.5/alpine3.22/Dockerfile

# Build and test images
docker build -t satosa:8.5 8.5/bookworm/
docker run -e BASE_URL=https://test.example.com satosa:8.5
```

--------------------------------

### Debian Build Dependencies

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Illustrates managing build dependencies in Debian using apt-mark and apt-get, including saving and restoring manual package states.

```bash
savedAptMark="$(apt-mark showmanual)"
apt-get install -y --no-install-recommends [packages]
# ... build ...
apt-mark auto '.*'
apt-mark manual $savedAptMark
apt-get purge -y --auto-remove
```

--------------------------------

### Pull SATOSA Debian-based Image

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Example commands to pull the default Debian-based SATOSA Docker image from Docker Hub, including specific version and variant tags.

```bash
# Debian-based (full size)
docker pull satosa:8.5
docker pull satosa:8.5-bookworm
docker pull satosa:latest
```

--------------------------------

### Configuration Generation from Environment Variables

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Maps environment variables to their corresponding SATOSA configuration files and specific YAML keys.

```yaml
# Environment Variables (docker_setup_env)
#     ↓
#     ├─→ BASE_URL
#     │   ├─→ proxy_conf.yaml: .BASE
#     │   ├─→ HOSTNAME (extracted)
#     │   └─→ Certificate CN (if auto-generating)
#     │
#     ├─→ STATE_ENCRYPTION_KEY
#     │   └─→ proxy_conf.yaml: .STATE_ENCRYPTION_KEY
#     │
#     ├─→ SAML2_BACKEND_DISCO_SRV
#     │   └─→ saml2_backend.yaml: .config.disco_srv
#     │
#     ├─→ SAML2_BACKEND_CERT + SAML2_BACKEND_KEY
#     │   ├─→ backend.crt
#     │   └─→ backend.key
#     │
#     └─→ SAML2_FRONTEND_CERT + SAML2_FRONTEND_KEY
#         ├─→ frontend.crt
#         └─→ frontend.key
#
# ↓
#
# SATOSA Configuration Files
#     ├─→ /etc/satosa/proxy_conf.yaml
#     ├─→ /etc/satosa/internal_attributes.yaml
#     ├─→ /etc/satosa/plugins/backends/saml2_backend.yaml
#     ├─→ /etc/satosa/plugins/frontends/saml2_frontend.yaml
#     └─→ /etc/satosa/plugins/frontends/ping_frontend.yaml
```

--------------------------------

### Full Container Configuration with `docker-compose`

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/configuration-reference.md

A `docker-compose.yml` file demonstrating how to configure and run a SATOSA service. It includes port mapping, environment variables, and Docker secrets for certificates.

```yaml
version: '3.8'

services:
  satosa:
    image: satosa:8.5
    ports:
      - "8080:8080"
    environment:
      BASE_URL: "https://satosa.example.com"
      STATE_ENCRYPTION_KEY: "ABC123DEF456GHI789JKL012MNO345P"
      SAML2_BACKEND_DISCO_SRV: "https://ds.example.com/discovery"
      SAML2_BACKEND_CERT_FILE: /run/secrets/backend_cert
      SAML2_BACKEND_KEY_FILE: /run/secrets/backend_key
      SAML2_FRONTEND_CERT_FILE: /run/secrets/frontend_cert
      SAML2_FRONTEND_KEY_FILE: /run/secrets/frontend_key
    secrets:
      - backend_cert
      - backend_key
      - frontend_cert
      - frontend_key
    volumes:
      - satosa_config:/etc/satosa

volumes:
  satosa_config:

secrets:
  backend_cert:
    file: ./certs/backend.crt
  backend_key:
    file: ./certs/backend.key
  frontend_cert:
    file: ./certs/frontend.crt
  frontend_key:
    file: ./certs/frontend.key
```

--------------------------------

### Alpine Build Dependencies

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Demonstrates how to add and remove build dependencies in Alpine Linux using apk.

```bash
apk add --no-cache --virtual .build-deps [packages]
# ... build ...
apk del --no-network .build-deps
```

--------------------------------

### Get Latest Commit Modifying Files

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Retrieves the latest commit hash that modified specified files using git log. This is useful for tracking changes in the repository.

```bash
# Get latest commit modifying files
fileCommit() {
    git log -1 --format='format:%H' HEAD -- "$@"
}
```

--------------------------------

### Main Entrypoint Orchestration

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/entrypoint-functions.md

The main entrypoint function `_main` orchestrates the initialization sequence for the SATOSA Docker container. It conditionally prepends 'gunicorn' to arguments and executes initialization functions before running the main command.

```bash
_main() {
    # Arguments that look like flags are prepended with "gunicorn"
    if [ "${1:0:1}" = '-' ]; then
        set -- gunicorn "$@"
    fi

    # If running gunicorn, perform initialization
    if [ "$1" = 'gunicorn' ]; then
        docker_setup_env
        docker_create_config
        docker_pprint_metadata
        exec "$@"
    fi

    # Otherwise, pass through to the command
    exec "$@"
}
```

--------------------------------

### Get Commit for Dockerfile and COPY'd Files

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Determines the commit hash for a directory by considering the Dockerfile and any files copied into it. It uses git log and awk to parse the Dockerfile.

```bash
# Get commit for Dockerfile and COPY'd files
dirCommit() {
    local dir="$1"
    (
        cd "$dir"
        files="$(
            git show HEAD:./Dockerfile \
                | awk 'toupper($1) == "COPY" { print $2 }'
        )"
        fileCommit Dockerfile $files
    )
}
```

--------------------------------

### Build SATOSA Image for Current Architecture

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Builds a SATOSA Docker image for the host's native architecture. This is the standard build command.

```bash
# Build for current architecture
docker build -t satosa:8.5 8.5/bookworm/
```

--------------------------------

### Initialize versions for a new SATOSA release

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/build-scripts-reference.md

Initializes version information for a new SATOSA release by querying upstream sources and updating `versions.json`. This is typically done before applying templates for a new version.

```bash
mkdir 8.5
./versions.sh 8.5
```

--------------------------------

### Generate SATOSA Configuration Files

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/entrypoint-functions.md

Generates essential SATOSA configuration files, including proxy settings, SAML2 backend and frontend configurations, and certificate files. This function should be called after `docker_setup_env`.

```bash
docker_setup_env
docker_create_config

# Configuration files are now created in /etc/satosa:
# - proxy_conf.yaml
# - internal_attributes.yaml
# - plugins/backends/saml2_backend.yaml
# - plugins/frontends/saml2_frontend.yaml
# - etc.
```

--------------------------------

### Display SAML2 Metadata

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/entrypoint-functions.md

Displays SAML2 metadata from backend and frontend certificates. It generates metadata using `satosa-saml-metadata` and prints it to stdout, also saving it to XML files. This function is typically called after environment setup and configuration generation.

```bash
docker_setup_env
docker_create_config
docker_pprint_metadata

# Output appears in container logs and is saved to XML files
```

--------------------------------

### Generate Proxy Configuration File

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Generate a proxy configuration file using _make_conffile, setting base URL, state encryption key, and frontend/backend modules. This is useful for container initialization.

```bash
_make_conffile proxy_conf.yaml \
    '.BASE = $ENV.BASE_URL |\
    .STATE_ENCRYPTION_KEY = $ENV.STATE_ENCRYPTION_KEY |\
    .FRONTEND_MODULES = [\
        "plugins/frontends/saml2_frontend.yaml",\
        "plugins/frontends/ping_frontend.yaml",\
        "plugins/frontends/oidc_frontend.yaml"
    ] |\
    .BACKEND_MODULES = [\
        "plugins/backends/saml2_backend.yaml",\
        "plugins/backends/oidc_backend.yaml"
    ]'
```

--------------------------------

### Test Docker Image Build

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Build Docker images for the new SATOSA version using the generated Dockerfiles to ensure they are created correctly.

```bash
docker build -t satosa:8.6-test 8.6/bookworm/
docker build -t satosa:8.6-alpine-test 8.6/alpine3.22/
```

--------------------------------

### Test config generation

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/README.md

Tests the configuration generation by running a SATOSA container and printing its proxy configuration file. This is useful for verifying that environment variables are correctly parsed into the configuration.

```bash
# Test config generation
docker run --rm -e BASE_URL="https://test.com" satosa:8.5 \
  cat /etc/satosa/proxy_conf.yaml
```

--------------------------------

### Create Directory if Needed

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Creates a directory, including any necessary parent directories, if it does not already exist. Useful for ensuring paths for files.

```bash
# Check directory and create if needed
mkdir -p "$(dirname "$1")"
```

--------------------------------

### Configuration Persistence Behavior

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Shows how SATOSA configuration files are generated on the first run and persist across subsequent runs. To regenerate, the container and its configurations must be deleted.

```bash
# First run: Generates config files in /etc/satosa
docker run --name satosa-container satosa:8.5

# Second run: Files already exist, not regenerated
docker exec satosa-container cat proxy_conf.yaml # Same config
```

--------------------------------

### Conditional Dockerfile Instructions

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Illustrates conditional logic within a Dockerfile template using jq. It applies different commands based on whether the image variant is Alpine or Debian.

```jq
{{ if is_alpine then (
    # Alpine-specific commands
) else (
    # Debian-specific commands
) end }}
```

--------------------------------

### _make_conffile Function Implementation Essentials

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Creates configuration files, supporting JSON, YAML, and other formats using jq or yq. It only creates files if they do not already exist.

```bash
function _make_conffile() {
    if [ -f "$1" ]; then return; fi
    mkdir -p "$(dirname "$1")"
    case "$1" in
        *.json) 
            jq    "${2:-.}" "/usr/share/satosa/example/$1.example" > "$1"
            ;;
        *.yaml | *.yml)
            yq -y "${2:-.}" "/usr/share/satosa/example/$1.example" > "$1"
            ;;
        *)
            jq -r "${2}" -n > "$1"
            ;;
    esac
}
```

--------------------------------

### Set Up Environment Variables for SATOSA

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/entrypoint-functions.md

Calls `file_env` to set default environment variables for SATOSA, such as BASE_URL and STATE_ENCRYPTION_KEY. It also extracts the hostname from BASE_URL.

```bash
docker_setup_env

# Now use the configured variables
echo $BASE_URL
echo $STATE_ENCRYPTION_KEY
echo $HOSTNAME
```

--------------------------------

### Launch SATOSA Container with Custom Base URL

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Sets a custom base URL for the SATOSA container. This affects the proxy configuration, certificate Common Name (CN), and HOSTNAME.

```bash
# Set custom base URL
docker run \
  -e BASE_URL="https://satosa.example.com" \
  satosa:8.5

# Effects:
# - proxy_conf.yaml .BASE = "https://satosa.example.com"
# - Certificate CN = "satosa.example.com"
# - HOSTNAME = "satosa.example.com"
```

--------------------------------

### Default Frontends Configuration

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/configuration-reference.md

This YAML snippet shows the default frontends configured in the `proxy_conf.yaml` file. It includes SAML2 and Ping frontends, which are automatically set up unless overridden.

```yaml
FRONTEND_MODULES:
  - plugins/frontends/saml2_frontend.yaml
  - plugins/frontends/ping_frontend.yaml
```

--------------------------------

### Use Custom Certificates with SATOSA

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/README.md

Deploy a SATOSA container with custom certificates for SAML2 backend and frontend. Mount certificates to /run/secrets.

```bash
docker run \
  -e SAML2_BACKEND_CERT_FILE=/run/secrets/backend_cert \
  -e SAML2_BACKEND_KEY_FILE=/run/secrets/backend_key \
  -e SAML2_FRONTEND_CERT_FILE=/run/secrets/frontend_cert \
  -e SAML2_FRONTEND_KEY_FILE=/run/secrets/frontend_key \
  -v /path/to/certs:/run/secrets:ro \
  satosa:8.5
```

--------------------------------

### Run Update Script for New Version

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Execute the update script to fetch release information, update configuration files, and generate Dockerfiles for the new SATOSA version.

```bash
./update.sh 8.6
```

--------------------------------

### Compare SATOSA Alpine vs Debian Image Performance

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Deploy SATOSA using both Alpine and Debian-based Docker images to compare their startup times. This helps in choosing the optimal image based on performance requirements.

```bash
# Alpine image (smaller, slightly slower startup)
docker run -d --name satosa-alpine satosa:8.5-alpine

# Debian image (larger, faster startup)
docker run -d --name satosa-debian satosa:8.5-bookworm

# Compare startup times
time docker run satosa:8.5-alpine echo "OK"
time docker run satosa:8.5-bookworm echo "OK"
```

--------------------------------

### Build Docker Image for ARM64

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Builds a Docker image for the arm64 architecture using BuildKit. Ensure you have BuildKit enabled.

```bash
DOCKER_BUILDKIT=1 docker build --platform linux/arm64 \
  -t satosa:8.5-arm64 8.5/bookworm/
```

--------------------------------

### Test Environment Variable Loading

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/implementation-notes.md

Runs a SATOSA container with a specific environment variable and checks if the configuration file reflects this setting.

```bash
docker run -e BASE_URL="https://test.com" satosa:8.5 \
  cat /etc/satosa/proxy_conf.yaml | grep "BASE:"
```

--------------------------------

### SATOSA Docker Testing Script Functions

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/usage-examples.md

Bash script to test utility functions within the SATOSA Docker entrypoint, including file_env, _is_sourced, and _make_selfsigned.

```bash
#!/bin/bash
set -e

# Source functions
. ./docker-entrypoint.sh

# Test file_env function
export TEST_VAR="test_value"
file_env TEST_VAR
[ "$TEST_VAR" = "test_value" ] && echo "✓ file_env direct works"

# Test with default
file_env UNDEFINED_VAR "default_value"
[ "$UNDEFINED_VAR" = "default_value" ] && echo "✓ file_env default works"

# Test _is_sourced
if _is_sourced; then
    echo "✓ _is_sourced works"
fi

# Test _make_selfsigned
_make_selfsigned test-cert "test.example.com"
[ -f test-cert.crt ] && echo "✓ _make_selfsigned works"
rm test-cert.{crt,key}

echo "All tests passed!"
```

--------------------------------

### Container Configuration for SATOSA

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Sets up the working directory, entrypoint script, exposed port, and default command for running the SATOSA container. It configures Gunicorn to serve the SATOSA WSGI application as a non-root user.

```dockerfile
WORKDIR /etc/satosa

COPY docker-entrypoint.sh /usr/local/bin/
ENTRYPOINT ["docker-entrypoint.sh"]

EXPOSE 8080
USER satosa:satosa
CMD ["gunicorn", "-b0.0.0.0:8080", "satosa.wsgi:app"]
```

--------------------------------

### Update to New SATOSA Version

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/README.md

Update to a new SATOSA version by creating a new directory, running the update script, and building a new Docker image.

```bash
mkdir 8.6
./update.sh 8.6
docker build -t satosa:8.6 8.5/bookworm/
```

--------------------------------

### Configure SAML2 Backend Discovery Service

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/configuration-reference.md

Set the SAML2_BACKEND_DISCO_SRV environment variable to specify the SAML2 Discovery Service URL for the backend. This service helps in discovering available identity providers.

```bash
# Use default Seamless Access service
docker run satosa:8.5

# Use custom discovery service
export SAML2_BACKEND_DISCO_SRV="https://ds.example.com/discovery"
docker run -e SAML2_BACKEND_DISCO_SRV="$SAML2_BACKEND_DISCO_SRV" satosa:8.5
```

--------------------------------

### Publication Pipeline Process

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/architecture-and-workflow.md

Outlines the steps involved in generating library metadata for Docker Official Images from version and variant information.

```bash
# versions.json
#     ↓
# For each version and variant:
#     ├─→ Get git commit hash for Dockerfile
#     ├─→ Get git commit hash for COPY'd files
#     ├─→ Query Docker Official Images for parent image architectures
#     ├─→ Generate version/variant tags
#     └─→ Output library metadata entry
#     
# ↓
# 
# Library metadata (Docker Official Images format)
#     ├─→ Tags: 8.5.1, 8.5, 8, latest, 8.5.1-bookworm, etc.
#     ├─→ SharedTags: (for default variant)
#     ├─→ Architectures: amd64, arm64v8
#     ├─→ GitCommit: abc123...
#     └─→ Directory: 8.5/bookworm/
#     
# ↓
# 
# Manually update https://github.com/docker-library/official-images
#     └─→ library/satosa file
```

--------------------------------

### _make_conffile Usage: Using Environment Variables

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Creates a JSON configuration file, setting values using environment variables via jq.

```bash
# Using environment variables
_make_conffile app_config.json '.app_name = env.APP_NAME'
```

--------------------------------

### file_env Usage: Direct Environment Variable

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Demonstrates setting and using a direct environment variable with the file_env function.

```bash
# Direct environment variable
export PASSWORD="secret123"
file_env PASSWORD
echo $PASSWORD  # secret123
```

--------------------------------

### Test Config File Generation

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/implementation-notes.md

Verifies that the SATOSA configuration file is generated within the container.

```bash
docker run --rm satosa:8.5 \
  test -f /etc/satosa/proxy_conf.yaml
```

--------------------------------

### Provide Custom SAML2 Backend Certificate and Key

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/configuration-reference.md

Configure custom X.509 certificate and private key for the SAML2 backend by setting SAML2_BACKEND_CERT and SAML2_BACKEND_KEY environment variables. This overrides auto-generated self-signed certificates.

```bash
export SAML2_BACKEND_CERT="$(cat /path/to/backend.crt)"
export SAML2_BACKEND_KEY="$(cat /path/to/backend.key)"
docker run \
  -e SAML2_BACKEND_CERT="$SAML2_BACKEND_CERT" \
  -e SAML2_BACKEND_KEY="$SAML2_BACKEND_KEY" \
  satosa:8.5
```

```bash
docker run \
  -e SAML2_BACKEND_CERT_FILE=/run/secrets/backend_cert \
  -e SAML2_BACKEND_KEY_FILE=/run/secrets/backend_key \
  -v /path/to/secrets:/run/secrets:ro \
  satosa:8.5
```

--------------------------------

### Build Custom SATOSA Docker Image

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/dockerfile-image-variants.md

Builds a custom SATOSA Docker image tagged 'custom', specifying the SATOSA version using a build argument. It targets the 'bookworm' variant.

```bash
docker build -t satosa:custom \
  --build-arg SATOSA_VERSION=8.5.1 \
  8.5/bookworm/
```

--------------------------------

### Exporting SAML2 Frontend Certificate and Key

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/configuration-reference.md

Use this snippet to export your custom X.509 certificate and private key as environment variables for SATOSA's SAML2 frontend. Ensure both certificate and key are provided for custom configuration; otherwise, auto-generation will be used.

```bash
export SAML2_FRONTEND_CERT="$(cat /path/to/frontend.crt)"
export SAML2_FRONTEND_KEY="$(cat /path/to/frontend.key)"
docker run \
  -e SAML2_FRONTEND_CERT="$SAML2_FRONTEND_CERT" \
  -e SAML2_FRONTEND_KEY="$SAML2_FRONTEND_KEY" \
  satosa:8.5
```

--------------------------------

### Check File Exists Before Reading

Source: https://github.com/identitypython/satosa-docker/blob/main/_autodocs/shell-utilities-reference.md

Ensures a configuration file exists before attempting to read it. If the file is not found, an error message is displayed, and the script exits.

```bash
# Check file exists before reading
if [ ! -f "$config_file" ]; then
    echo >&2 "error: config file not found: $config_file"
    exit 1
fi
```