Docker / Podman Deployment

Prerequisites are written for bare metal installations. Please keep in mind the containerization layer may make some of these items unnecessary.

Since CrowdSec 1.7.0, it is mandatory to persist the /var/lib/crowdsec/data directory in a volume.

If you use the examples provided in this page, they will be.

If you choose to write your own compose file, make sure create a volume for it.

Before getting started, it is advised to read the introduction page to understand the prerequisites and concepts for running CrowdSec.

Docker

We will presume you have Docker installed on your system. If not, you can install it by following the instructions on the official Docker website.

Run

Docker run command will run a container, this is useful for testing and development purposes.

docker run -d \
  --name crowdsec \
  --volume /etc/crowdsec:/etc/crowdsec \
  --volume /var/lib/crowdsec/data/:/var/lib/crowdsec/data/ \
  --volume /var/log:/var/log:ro \
  --env COLLECTIONS="crowdsecurity/linux" \
  -p 127.0.0.1:8080:8080 \
  crowdsecurity/crowdsec:latest

However, for most users it is recommended to use compose module for production deployments. Since it allows you to define your container deployments in a more structured format.

Compose

Docker Compose is a tool for defining and running multi-container setups in a structured format. It uses a YAML file to configure the application's services, networks, and volumes.

Here is a snippet:

crowdsec:
  image: crowdsecurity/crowdsec
  restart: always
  ports:
    - 127.0.0.1:8080:8080
  environment:
    COLLECTIONS: "crowdsecurity/nginx"
    GID: "${GID-1000}"
  depends_on:
    - "reverse-proxy"
  volumes:
    - ./crowdsec/acquis.yaml:/etc/crowdsec/acquis.yaml
    - logs:/var/log/nginx
    - crowdsec-db:/var/lib/crowdsec/data/
    - crowdsec-config:/etc/crowdsec/

Compose snippet was taken from our example-docker-compose repository which contains many examples of how CrowdSec container can be used in different setups.

Compose key aspects

If you don't find an example that fits your needs, you can create your own docker-compose.yml file. Here are the key aspects:

Provide Access To Logs

Since CrowdSec is running within a container layer you need to provide access to log sources within the example above we provide a named volume called logs which other containers will output their log files too.

volumes:
  - logs:/var/log/nginx

Persistent Data Directories

The following directories must be persisted, otherwise the container will refuse to start:

volumes:
  - crowdsec-db:/var/lib/crowdsec/data/ ## Data Directory
  - crowdsec-config:/etc/crowdsec/ ## Configuration Directory

If you haven't used named volumes within Docker before you can read their documentation here

Depends On

Depends on directive allows Docker to bring up the compose stack in "order", the reason we use it within the snippet the container reverse-proxy creates the log files on startup and we want to make sure CrowdSec finds these files to monitor.

depends_on:
  - "reverse-proxy"

Environment Variables

You can find a full list of available environment variables on our Docker Hub image page.

Here are the most common environment variables for customizing CrowdSec in Docker:

Variable	Default	Description
`COLLECTIONS`	(none)	Space-separated list of CrowdSec collections to install (e.g., `crowdsecurity/nginx`).
`TZ`	UTC	Timezone for logs (e.g., `Europe/London`).
`CONFIG_FILE`	`/etc/crowdsec/config.yaml`	Path to the main config file. Useful if mounting a single file instead of a full directory.
`LOCAL_API_URL`	`http://0.0.0.0:8080`	Where the Local API listens. Normally doesn't need to be changed unless you're running in agent mode.
`DISABLE_LOCAL_API`	`false`	Set to `true` to disable LAPI and use this instance as an log processor only.
`DISABLE_AGENT`	`false`	Set to `true` to disable the log processor and use this instance as an LAPI only.
`AGENT_USERNAME`	(none)	Required only if `DISABLE_LOCAL_API` is true. Username for connecting to central LAPI.
`AGENT_PASSWORD`	(none)	Password for authenticating the agent.
`BOUNCER_KEY_<name>`	(none)	Seed value as API key for remediation under `<name>`

Use a .env file or Docker secrets to avoid hardcoding sensitive variables like passwords or API keys.

Automatic Hub Updates

To keep your CrowdSec installation up to date with the latest parsers, scenarios, and collections from the hub, you can set up an automated cron job that will check for updates and restart the container when needed.

Docker Run Setup

For containers started with docker run, create this script:

#!/bin/bash
# /usr/local/bin/crowdsec-update.sh

CONTAINER_NAME="crowdsec"  # Adjust to your container name
DOCKER_BIN="/usr/bin/docker"  # Adjust path if needed
GREP_BIN="/usr/bin/grep"  # Adjust path if needed

# Check if container is running
if ! $DOCKER_BIN ps --format "table {{.Names}}" | $GREP_BIN -q "^${CONTAINER_NAME}$"; then
    echo "Container ${CONTAINER_NAME} is not running"
    exit 1
fi

# Update and check for upgrades
$DOCKER_BIN exec ${CONTAINER_NAME} cscli --error hub update >/dev/null
upgraded="$($DOCKER_BIN exec ${CONTAINER_NAME} cscli --error hub upgrade)"

if [ -n "$upgraded" ]; then
    echo "Hub updates detected, restarting container..."
    $DOCKER_BIN restart ${CONTAINER_NAME}
    echo "Container restarted successfully"
else
    echo "No hub updates available"
fi

Docker Compose Setup

For Docker Compose deployments, use this script instead:

#!/bin/bash
# /usr/local/bin/crowdsec-update.sh

cd /path/to/your/docker-compose/directory  # Adjust path
DOCKER_BIN="/usr/bin/docker"  # Adjust path if needed
GREP_BIN="/usr/bin/grep"  # Adjust path if needed

# Check if service is running
if ! $DOCKER_BIN compose ps crowdsec | $GREP_BIN -q "Up"; then
    echo "CrowdSec service is not running"
    exit 1
fi

# Update and check for upgrades
$DOCKER_BIN compose exec crowdsec cscli --error hub update >/dev/null
upgraded="$($DOCKER_BIN compose exec crowdsec cscli --error hub upgrade)"

if [ -n "$upgraded" ]; then
    echo "Hub updates detected, restarting service..."
    $DOCKER_BIN compose restart crowdsec
    echo "Service restarted successfully"
else
    echo "No hub updates available"
fi

Setup Instructions

Choose the appropriate script based on your deployment method

Make it executable:

sudo chmod +x /usr/local/bin/crowdsec-update.sh

Add to crontab (daily at 2 AM):

sudo crontab -e
# Add: 0 2 * * * /usr/local/bin/crowdsec-update.sh

Docker Compose is recommended as it doesn't require knowing the exact container name and works with the service name from your docker-compose.yml.

Finding binary paths:

# Find docker binary (includes compose subcommand)
which docker
# Common paths: /usr/bin/docker, /usr/local/bin/docker

# Find grep binary
which grep
# Common paths: /usr/bin/grep, /bin/grep

Cron schedule examples:

0 */6 * * * - Every 6 hours
0 2 * * 0 - Every Sunday at 2 AM
0 2 1 * * - First day of every month at 2 AM

Test your script manually before setting up the cron job to ensure it works with your specific setup.

Next Steps?

Great, you now have CrowdSec installed on your system. Within the post installation steps you will find the next steps to configure and optimize your installation.

Docker​

Run​

Compose​

Compose key aspects​

Provide Access To Logs​

Persistent Data Directories​

Depends On​

Environment Variables​

Automatic Hub Updates​

Docker Run Setup​

Docker Compose Setup​

Setup Instructions​

Next Steps?​