linuxserver/ci

linuxserver/ci repository overview

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

Spins up the container: It runs the target Docker image with a specified tag.
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.
Generates an SBOM: It uses syft to create a Software Bill of Materials, providing a complete list of all packages inside the image.
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.
Generates a report: It gathers all the results—container logs, build info, SBOM, screenshots, and test statuses—into a comprehensive HTML report.
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." }

Tag summary

Recent tags

Content type

Image

Digest

sha256:684e39449…

Size

479 MB

Last updated

about 9 hours ago

docker pull linuxserver/ci

This week's pulls

Pulls:

344

Last week

Learn more⁠