Docker / Podman Deployment

info

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

Before getting started it is advised to read the prerequisites page to understand the requirements 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/

info

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

We recommend persisting the following directories:

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

info

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>

tip

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

---

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.