Contact information:-

Type	Address/Details
Discord	Discord
Forum	Linuserver.io forum

linuxserver/ci

What is this?

This container is an automated testing tool for Docker images. It's designed to perform a series of checks to ensure a container is healthy and functional before it's released. Here's what it does:

1. Spins up the container: It runs the target Docker image with a specified tag.
2. Checks for successful startup: It tails the container's logs, waiting for the [services.d] done. message, which confirms the init system has finished and the services are running.
3. Generates an SBOM: It uses syft to create a Software Bill of Materials, providing a complete list of all packages inside the image.
4. Tests the Web UI (optional): If the container runs a web service, it attempts to connect to the UI and take a screenshot to verify it's accessible and renders correctly.
5. Generates a report: It gathers all the results—container logs, build info, SBOM, screenshots, and test statuses—into a comprehensive HTML report.
6. Uploads the report (CI only): In a CI environment, it uploads the final report to an S3 bucket for review.

Developer Mode (Local Testing)

For local development and debugging, you can use CI_LOCAL_MODE. This mode runs all the tests but skips the S3 upload, saving the report directly to a local folder. It's the easiest way to test a container without needing cloud credentials.

Example Run Command

Run this command from your terminal. It will test the linuxserver/plex:latest image and place the report in an output directory in your current folder.

docker run --rm -i \
 --shm-size=1gb \
 -v /var/run/docker.sock:/var/run/docker.sock \
 -v "$(pwd)/output:/ci/output" \
 -e CI_LOCAL_MODE=true \
 -e IMAGE="linuxserver/plex" \
 -e TAGS="latest" \
 -e BASE="ubuntu" \
 -e WEB_SCREENSHOT=true \
 -e PORT=32400 \
 -e SSL=false \
 -e WEB_PATH="/web/index.html" \
 -e WEB_AUTH="" \
 -e WEB_SCREENSHOT_TIMEOUT=60 \
 -e WEB_SCREENSHOT_DELAY=20 \
 -t lsiodev/ci:latest \
 python3 test_build.py

Viewing the Report

Once the script finishes, you can view the detailed HTML report with this command:

chromium output/linuxserver/plex/latest/index.html

Note: You can use any modern web browser (Firefox, Chrome, etc.).

Key Local Variables

Variable	Description	Example
CI_LOCAL_MODE	Required. Enables local mode, disables S3 uploads.	true
IMAGE	Required. The full name of the image to test.	linuxserver/plex
TAGS	Required. The tag(s) to test. Use | to separate multiple tags.	latest
BASE	Required. The base distribution of the image.	ubuntu or alpine
WEB_SCREENSHOT	Set to true to enable screenshot testing for web UIs.	true
PORT	The internal port the web UI listens on.	32400
SSL	Set to true if the web UI uses https://.	false
WEB_PATH	The specific path to the web UI landing page.	/web/index.html
WEB_AUTH	Credentials for basic auth, format user:password. Leave empty for none.	""
WEB_SCREENSHOT_DELAY	Seconds to wait after the page loads before taking the screenshot.	20

Advanced Usage (CI Environment)

This container is not meant for public consumption as it is hard coded to LinuxServer endpoints for storage of resulting reports.

The following shows the full list of environment variables used when the container is run by our CI system, linuxserver/pipeline-triggers.

sudo docker run --rm -i \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /host/path:/ci/output:rw `#Optional, will contain all the files the container creates.` \
-e IMAGE="linuxserver/<dockerimage>" \
-e TAGS="<single tag or array separated by |>" \
-e META_TAG=<manifest main dockerhub tag> \
-e BASE=<alpine or debian based distro> \
-e SECRET_KEY=<S3 secret> \
-e ACCESS_KEY=<S3 key> \
-e DOCKER_ENV="<optional, Array of env vars separated by | IE test=test|test2=test2 or single var. Defaults to ''>" \
-e WEB_AUTH="<optional, format user:passord. Defaults to 'user:password'>" \
-e WEB_PATH="<optional, format /yourpath>. Defaults to ''." \
-e S3_REGION=<optional, custom S3 Region. Defaults to 'us-east-1'> \
-e S3_BUCKET=<optional, custom S3 Bucket. Defaults to 'ci-tests.linuxserver.io'> \
-e WEB_SCREENSHOT_TIMEOUT=<optional, time in seconds before timing out trying to take a screenshot. Defaults to '120'>
-e WEB_SCREENSHOT_DELAY=<optional, time in seconds to delay before taking a screenshot after loading the web page. Defaults to '10'> \
-e SBOM_TIMEOUT=<optional, time in seconds before timing out trying to generate a SBOM. Defaults to '900'>
-e WEB_SCREENSHOT=<optional, set to false if not a web app. Defaults to 'false'> \
-e PORT=<optional, port web application listens on internal docker port. Defaults to '80'> \
-e SSL=<optional , use ssl for the screenshot true/false. Defaults to 'false'> \
-e CI_S6_VERBOSITY=<optional, Updates the S6_VERBOSITY env. Defaults to '2'> \
-e CI_LOG_LEVEL=<optional, Sets the ci logging level. Defaults to 'INFO'> \
-e DOCKER_LOGS_TIMEOUT=<optional, How long to wait in seconds while tailing the container logs before timing out. Defaults to '120'> \
-e DRY_RUN=<optional, Set to 'true' when you don't want to upload files to S3 when testing> \
-e NODE_NAME=<optional, Name of the builder that runs the CI test.> \
-e RELEASE_TAG=<optional, The release tag of the docker image. Used for upload location. Defaults to 'latest'> \
-e SYFT_IMAGE_TAG=<optional, The image tag of the syft docker image. Used for generating SBOM. Defaults to '1.26.1'> \
-t lsiodev/ci:latest \
python3 test_build.py

The following line is only in this repo for loop testing:

• { date: "01.01.50:", desc: "I am the release message for this internal repo." }