Table of Contents

• 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

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

or

--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

1. Container fails to start: ```bash

   Check container status

   docker ps -a

View logs

docker logs [CONTAINER_ID]

Check resource usage

docker stats

2. Network connectivity issues:
```bash
# Test network connectivity
docker network inspect [NETWORK_NAME]

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

1. 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

1. Image Security: ```bash

   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; 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