docker-documentation/docs/images/docker-ci.md

---
title: ci
---
<!-- DO NOT EDIT THIS FILE MANUALLY -->
<!-- Please read https://github.com/linuxserver/docker-ci/blob/master/.github/CONTRIBUTING.md -->
[linuxserverurl]: https://linuxserver.io
[forumurl]: https://discourse.linuxserver.io
[huburl]: https://hub.docker.com/r/linuxserver/ci/
[pipelineurl]: https://github.com/linuxserver/pipeline-triggers

[![linuxserver.io](https://raw.githubusercontent.com/linuxserver/docker-templates/master/linuxserver.io/img/linuxserver_medium.png?v=4&s=4000)][linuxserverurl]


## Contact information:-

| Type | Address/Details |
| :---: | --- |
| Discord | [Discord](https://discord.gg/linuxserver) |
| Forum | [Linuserver.io forum][forumurl] |

# [linuxserver/ci][huburl]

## 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][pipelineurl].

```
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." }