Install with Docker or Podman

Prerequisites are written for bare metal installs. In containers, some of these items may not apply.

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 write your own compose file, make sure you create a volume for it.

New to CrowdSec? Start with the introduction to understand the components and prerequisites. This page installs the Security Engine (detection). To block attacks, add a Remediation Component after installation.

Docker

Make sure Docker is installed. If not, follow the official Docker instructions.

Run

The docker run command is useful for quick tests and development.

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

For most users, we recommend Docker Compose for production. It lets you define services, volumes, and networks in a single file.

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.

Example 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 do not find an example that fits your needs, create your own docker-compose.yml. Here are the key aspects to keep in mind:

Provide access to logs

Because CrowdSec runs inside a container, you must mount log sources. In the example above, the logs volume is shared with the application container.

volumes:
  - logs:/var/log/nginx

Persist 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

Use depends_on

The depends_on directive helps bring up the compose stack in order. In the snippet, the reverse-proxy container creates log files on startup, so we want it running first.

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 a 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.

---

Next steps

Great, you now have CrowdSec installed. Continue with the post-installation steps to finish setup and optimize your deployment.