FossID Documentation

Introduction
Prerequisites
Image Management
Deployment Options
Configuration Management
Troubleshooting
Production Deployment
Additional Resources

Introduction

This guide provides detailed instructions for deploying FossID Workbench in a containerized environment. The application is distributed as a container image and can be deployed using Docker, Podman, or Docker Compose depending on your requirements. The guide covers prerequisites, configuration, deployment options, troubleshooting, and best practices.

Application Overview

Registry Location: quay.io/fossid
Base Image: workbench
Exposed Ports: 80
Required Environment Variables: multiple
Storage Requirements:
- fossid.conf
- backup
- intake
- logs
- uploads
- scan-path
Network Configuration: bridge

Prerequisites

To deploy the FossID Workbench as a container you can use one of the required software. Please check that the software is correctly installed and updated to the latest version.

Required Software

Verify Docker installation

docker --version

If using Podman, verify the installation

podman --version

If using Docker Compose

docker-compose --version

Authentication

Please use the username and password provided in the Delivery portal to connect to FossID private repository at Quay.io.

docker login quay.io

Configuration Management

Environment Variables

Use .env files for local development
Consider using external secret management solutions (e.g. HashiCorp Vault, AWS Secrets Manager)

Example of an .env file:

PROJECT_NAME=deployment

# FOSSID Release configuration
# RELEASE=25.1.0
RELEASE=FOSSID_VERSION

# Database server environment configuration
MYSQL_ROOT_PASSWORD=root123
MYSQL_USER=fossiduser
MYSQL_PASSWORD=fossidpassword
MYSQL_HOST=db
FOSSID_MYSQL_DATABASE=fossid

# Web Server Configuration
# change only if default HTTP is modified or HTTPS is configured
# HTTPS_PORT=
HTTP_PORT=8081

# FossID Shinobi service configuration
FOSSID_SHINOBI_JAVA_ARGS="-Xms8g -Xmx8g -XX:NewSize=5g -XX:MaxNewSize=5g -XX:SurvivorRatio=8"
FOSSID_SHINOBI_ARGS="-threads 8 -timeout 275 -socket 127.0.0.1:9900"

# FossID Workbench
# The initial password for the `fossid` user.
FOSSID_INITIAL_PASSWORD=fossidlogin

FossID Workbench Configuration

The FossID Workbench configuration is done through the fossid.conf file. The image contains an example file fossid.conf.dist, located in the directory /fossid/etc/, and can be extracted by running the command: docker cp <container id>:/fossid/etc/fossid.conf.dist /path/on/host/fossid.conf.dist.

The minimal configuration required is:

[CLI]
cli_server_host = FOSSID_HOST
cli_token = FOSSID_TOKEN
cli_strip_tags = .html

[WebApp]
webapp_db_server = MYSQL_HOST
webapp_db_database = MYSQL_DATABASE
webapp_db_username = MYSQL_USER
webapp_db_password = FOSSID_MYSQL_PASSWORD
webapp_db_port = 3306
webapp_server_name = fossid-workbench
webapp_timezone = Europe/Berlin
webapp_intake_repository =/fossid/intake/
webapp_backups=/fossid/backup/

webapp_base_url=https://fossid-workbench/index.php

The file can be mounted in the container by adding the following option to the docker or podman command, for example:

  --volume ./fossid.conf:/fossid/etc/fossid.conf:Z

or add it as a volume in the compose.yaml file, for example:

...
  fossid-workbench-service:
  ...
    volumes:
      - ./fossid.conf:/fossid/etc/fossid.conf:Z
...

Port mapping

The application is exposed on port 80, meaning all incoming HTTP traffic is forwarded to the container. In Docker Compose, this is configured as:

ports:
  - "80:80"

Volume Management

The following directories can be configured as volumes or as bind-mounts for data persistence outside the container:

# Create volumes
docker volume create fossid-wb-backup
docker volume create fossid-wb-intake
docker volume create fossid-wb-logs
docker volume create fossid-wb-uploads

# Inspect volumes
docker volume inspect fossid-wb-backup
docker volume inspect fossid-wb-intake
docker volume inspect fossid-wb-logs
docker volume inspect fossid-wb-uploads

For using the target path option in FossID Workbench it is recommended to use a bind mounted volume. You can user either --volume flag or the --mount flag with Docker or Podman. Here are some examples:

# Create directory on the host
mkdir /path/to/target-path-directory

and use one of the options:

--volume /path/to/target-path-directory:/target-path:rw,Z

--mount type=bind,source=/path/to/target-path-directory,target=/target-path

Image Management

Pulling the Image

Pull the image from the FossID private repository quay.io.

docker pull quay.io/fossid/workbench:latest

Or a specific version

docker pull quay.io/fossid/workbench:25.1.0

Using specific platform (if needed)

docker pull --platform linux/amd64 quay.io/fossid/workbench:latest

Image Verification

# Verify image presence
docker images | grep workbench

# Inspect image details
docker inspect --format='{{.RepoDigests}}' quay.io/fossid/workbench:25.1.0

Deployment Options

Basic Docker Deployment

docker network create --driver=bridge wb-network

docker run -d \
  --name db \
  --platform linux/amd64 \
  --env-file .env \
  --health-cmd 'mysqladmin -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h127.0.0.1 ping' \
  --health-interval 5s \
  --health-timeout 5s \
  --health-retries 60 \
  --network wb-network \
  -v ./db/db-persist:/var/lib/mysql \
  docker.io/library/mysql:8.0

docker run -d \
  --name fossid-workbench \
  --platform linux/amd64 \
  --memory-reservation 8g \
  --tty \
  --env-file .env \
  --cap-add=CAP_AUDIT_WRITE \
  --health-cmd 'curl --silent --fail localhost:80/health-check' \
  --health-interval 5s \
  --health-timeout 5s \
  --health-retries 60 \
  --network wb-network \
  -p 8080:80 \
  -v ./fossid.conf:/fossid/etc/fossid.conf:Z \
  -v ./backup:/fossid/backup:Z \
  -v ./intake:/fossid/intake:Z \
  -v ./logs:/fossid/logs:Z \
  -v ./uploads:/fossid/uploads:Z \
  -v ./scan-path:/fossid/scan-path:Z \
  --restart unless-stopped \
  quay.io/fossid/workbench:latest

Docker Compose Deployment

Create a docker-compose.yml:

services:
  fossid-workbench:
    image: quay.io/fossid/workbench:${RELEASE}
    platform: linux/amd64
    mem_reservation: 8g
    container_name: fossid-workbench
    ports:
      - "8081:80"
    tty: true
    env_file:
      - .env
    depends_on:
      - fossid-mysql
    healthcheck:
      test: curl --silent --fail localhost:80/health-check
      interval: 5s
      timeout: 5s
      retries: 60
    volumes:
      - ./fossid.conf:/fossid/etc/fossid.conf:Z
      - ./backup:/fossid/backup:Z
      - ./intake:/fossid/intake:Z
      - ./logs:/fossid/logs:Z
      - ./uploads:/fossid/uploads:Z
      - ./scan-path:/fossid/scan-path:Z
    networks:
      - wb-network
    cap_add:
      - CAP_AUDIT_WRITE

  fossid-mysql:
    image: docker.io/library/mysql:8.0
    platform: linux/amd64
    container_name: db
    env_file:
      - .env
    healthcheck:
      test: mysqladmin -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h127.0.0.1 ping
      interval: 5s
      timeout: 5s
      retries: 60
    networks:
      - wb-network
    volumes:
      - ./db/db-persist:/var/lib/mysql

networks:
  wb-network:
    driver: bridge

Deploy with:

docker-compose up -d

Podman Pod Deployment

podman create network --driver=bridge wb-network

podman pod create --name fossid-workbench-pod --publish 8080:80 --network wb-network

podman run -d \
  --name db \
  --platform linux/amd64 \
  --pod fossid-workbench-pod \
  --env-file .env \
  --health-cmd 'mysqladmin -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h127.0.0.1 ping' \
  --health-interval 5s \
  --health-timeout 5s \
  --health-retries 60 \
  -v ./db/db-persist:/var/lib/mysql \
  docker.io/library/mysql:8.0

podman run -d \
  --name fossid-workbench \
  --platform linux/amd64 \
  --pod fossid-workbench-pod \
  --memory-reservation 8g \
  --tty \
  --env-file .env \
  --cap-add=CAP_AUDIT_WRITE \
  --health-cmd 'curl --silent --fail localhost:80/health-check' \
  --health-interval 5s \
  --health-timeout 5s \
  --health-retries 60 \
  -p 8080:80 \
  -v ./fossid.conf:/fossid/etc/fossid.conf:Z \
  -v ./backup:/fossid/backup:Z \
  -v ./intake:/fossid/intake:Z \
  -v ./logs:/fossid/logs:Z \
  -v ./uploads:/fossid/uploads:Z \
  -v ./scan-path:/fossid/scan-path:Z \
  --restart unless-stopped \
  quay.io/fossid/workbench:latest

Troubleshooting

Common Issues

Container fails to start:

# Check container status
docker ps -a

# View logs
docker logs [CONTAINER_ID]

# Check resource usage
docker stats

Network connectivity issues:

# Test network connectivity
docker network inspect [NETWORK_NAME]

# Enter container for debugging
docker exec -it [CONTAINER_ID] /bin/sh

Volume mounting issues:

# Verify mount points
docker inspect -f '{{ .Mounts }}' [CONTAINER_ID]

Debugging Commands

# Container shell access
docker exec -it [CONTAINER_ID] /bin/sh

# Process list in container
docker top [CONTAINER_ID]

# Resource usage
docker stats [CONTAINER_ID]

# Network information
docker network inspect [NETWORK_NAME]

Production Deployment

Security Best Practices

Image Security:

# Scan for vulnerabilities
docker scan workbench:latest

# Use specific tags instead of 'latest'
docker pull quay.io/fossid/workbench@sha256:[DIGEST]

Reverse proxy setup (Nginx).

Example Nginx Configuration:

server {
    listen 80;
    client_max_body_size 50M;
    location / {
        proxy_pass http://[APP_NAME]:[PORT];
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forward-Proto $scheme;
        proxy_read_timeout 10m;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_redirect http:// $scheme://;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

Additional Resources

Docker Documentation: https://docs.docker.com
Podman Documentation: https://docs.podman.io/
Docker Compose Documentation: https://docs.docker.com/compose

Workbench Containerized Application Deployment Guide

Table of Contents