Install with Docker or Podman

info

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

warning

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.

SH

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:

YAML

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

YAML

volumes:
  - logs:/var/log/nginx

Persist data directories

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

YAML

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

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.

YAML

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>

tip

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

---

Choose a Remediation Component

warning

The Security Engine by itself is a detection engine -- it will not block anything. You need to add a Remediation Component to enforce decisions.

Protecting a web application?

Use a WAF-capable bouncer to get real-time WAF protection and virtual patching. For Docker and Kubernetes environments, the Traefik bouncer plugin is a natural fit. If you use Nginx as a reverse proxy, see the Nginx bouncer.

See the full bouncer selection guide for all available options.

For non-web services (SSH, databases, SMTP), use the firewall bouncer for IP-level protection.

---

Next steps

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