Skip to content

Commit 0e36ed9

Browse files
hhftechnologyhhftechnology
committed
documentation-fix
1 parent f872b0d commit 0e36ed9

2 files changed

Lines changed: 143 additions & 38 deletions

File tree

‎docs/content/docs/configuration/environment.mdx‎

Lines changed: 143 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -7,49 +7,161 @@ description: Comprehensive guide to environment configuration
77

88
CrowdSec Manager is configured primarily through environment variables passed to the Docker container.
99

10-
## Server Configuration
10+
## Summary
1111

12-
| Variable | Default | Description |
13-
|----------|---------|-------------|
14-
| `PORT` | `8080` | The internal port the application listens on. |
15-
| `ENVIRONMENT` | `production` | Set to `development` for verbose logging and dev features. |
16-
| `LOG_LEVEL` | `info` | Logging verbosity: `debug`, `info`, `warn`, `error`. |
17-
| `LOG_FILE` | `/app/logs/crowdsec-manager.log` | Path to the internal application log file. |
12+
**Are any variables absolutely necessary?**
13+
Technically, **no**. The application is designed with sensible defaults for all configuration options. You can run the application without setting any environment variables, provided the default paths (like `./data` and `./logs`) are writable and Docker is available locally.
1814

19-
## Docker Integration
15+
## Detailed Variable Breakdown
2016

21-
| Variable | Default | Description |
22-
|----------|---------|-------------|
23-
| `DOCKER_HOST` | `unix:///var/run/docker.sock` | Path to the Docker socket. Required for container management. |
24-
| `COMPOSE_FILE` | `/app/docker-compose.yml` | Path to the compose file inside the container. |
17+
### Core Application Configuration
18+
19+
| Variable | Default | Impact / Description |
20+
| :--- | :--- | :--- |
21+
| `PORT` | `8080` | The HTTP port the manager listens on. Change this if port 8080 is already in use. |
22+
| `ENVIRONMENT` | `production` | Sets the application mode. Use `development` for verbose logging and dev features. |
23+
| `LOG_LEVEL` | `info` | Controls logging verbosity. Options: `debug`, `info`, `warn`, `error`. |
24+
| `LOG_FILE` | `/app/logs/crowdsec-manager.log` | Path where the application log file is written. |
25+
26+
### Docker & Service Discovery
27+
28+
| Variable | Default | Impact / Description |
29+
| :--- | :--- | :--- |
30+
| `DOCKER_HOST` | `unix:///var/run/docker.sock` | Address of the Docker daemon. If empty, it uses the default local socket. Set this if connecting to a remote Docker instance. |
31+
| `COMPOSE_FILE` | `/app/docker-compose.yml` | Path to the Docker Compose file. The manager reads this to discover services and manage updates. |
32+
| `*_CONTAINER_NAME` | `crowdsec`, `traefik`, etc. | Overrides for container names if your stack uses different names (e.g., `CROWDSEC_CONTAINER_NAME`, `TRAEFIK_CONTAINER_NAME`). |
2533
| `PANGOLIN_DIR` | `/app` | Base working directory for the application. |
2634
| `CONFIG_DIR` | `/app/config` | Directory where configuration files are stored. |
2735

28-
## Database
36+
### File Paths & Persistence
2937

30-
| Variable | Default | Description |
31-
|----------|---------|-------------|
32-
| `DATABASE_PATH` | `/app/data/settings.db` | Path to the SQLite database file. Ensure this path is persistent. |
38+
| Variable | Default | Impact / Description |
39+
| :--- | :--- | :--- |
40+
| `DATABASE_PATH` | `/app/data/settings.db` | Location of the SQLite database storing app settings. Ensure this path is persistent. |
41+
| `BACKUP_DIR` | `/app/backups` | Directory where backups are stored. |
42+
| `RETENTION_DAYS` | `60` | Number of days to keep backups before auto-deletion. |
3343

34-
## Traefik Integration
44+
### Integrations (Traefik & CrowdSec)
3545

36-
| Variable | Default | Description |
37-
|----------|---------|-------------|
38-
| `TRAEFIK_DYNAMIC_CONFIG` | `/dynamic_config.yml` | Path to Traefik's dynamic configuration file. |
39-
| `TRAEFIK_STATIC_CONFIG` | `/etc/traefik/traefik_config.yml` | Path to Traefik's static configuration file. |
46+
| Variable | Default | Impact / Description |
47+
| :--- | :--- | :--- |
48+
| `TRAEFIK_DYNAMIC_CONFIG` | `/etc/traefik/dynamic_config.yml` | Path to Traefik's dynamic config file. Used to manage middlewares/routers. |
49+
| `TRAEFIK_STATIC_CONFIG` | `/etc/traefik/traefik_config.yml` | Path to Traefik's static config file. |
4050
| `TRAEFIK_ACCESS_LOG` | `/var/log/traefik/access.log` | Path to read Traefik access logs from. |
4151
| `TRAEFIK_ERROR_LOG` | `/var/log/traefik/traefik.log` | Path to read Traefik error logs from. |
52+
| `CROWDSEC_ACQUIS_FILE` | `/etc/crowdsec/acquis.yaml` | Path to CrowdSec's acquisition configuration. |
53+
| `INCLUDE_CROWDSEC` | `true` | Whether to manage CrowdSec container updates/restarts. |
4254

43-
## CrowdSec Integration
55+
## Recommendation
4456

45-
| Variable | Default | Description |
46-
|----------|---------|-------------|
47-
| `CROWDSEC_ACQUIS_FILE` | `/etc/crowdsec/acquis.yaml` | Path to CrowdSec acquisition configuration. |
48-
| `INCLUDE_CROWDSEC` | `false` | Whether to manage CrowdSec container updates/restarts. |
57+
For a standard deployment, you likely only need to configure:
58+
1. **`PORT`**: If you have a port conflict.
59+
2. **`COMPOSE_FILE`**: If your compose file is not in the default location.
60+
3. **`DOCKER_HOST`**: If running in a complex Docker environment.
4961

50-
## Backup Configuration
62+
Everything else can safely be left to defaults unless you have specific customization needs (like changing log locations or backup retention).
5163

52-
| Variable | Default | Description |
53-
|----------|---------|-------------|
54-
| `BACKUP_DIR` | `/app/backups` | Directory where backups are stored. |
55-
| `RETENTION_DAYS` | `60` | Number of days to keep backups before auto-deletion. |
64+
## Handling Custom Paths
65+
66+
A common source of confusion is the difference between **internal container paths** (where the app looks for files) and **external host paths** (where files actually exist on your server).
67+
68+
### The Golden Rule
69+
70+
- **Environment Variables** tell the application **where to look inside the container**.
71+
- **Docker Volumes** map your **real host files** to those **internal container locations**.
72+
73+
### Example: Custom CrowdSec Installation
74+
75+
Suppose your CrowdSec installation is at `/opt/my-custom-crowdsec` instead of the standard `/etc/crowdsec`.
76+
77+
**DO NOT** change the environment variable `CROWDSEC_ACQUIS_FILE` to `/opt/my-custom-crowdsec/acquis.yaml`. The container cannot see your `/opt` directory directly!
78+
79+
**Instead, update your `docker-compose.yml` volumes:**
80+
81+
```yaml
82+
services:
83+
crowdsec-manager:
84+
environment:
85+
# LEAVE THIS AS DEFAULT
86+
- CROWDSEC_ACQUIS_FILE=/etc/crowdsec/acquis.yaml
87+
volumes:
88+
# Map YOUR custom path (left) to the CONTAINER'S expected path (right)
89+
- /opt/my-custom-crowdsec/acquis.yaml:/etc/crowdsec/acquis.yaml:ro
90+
```
91+
92+
By changing the volume mapping, you "trick" the container into seeing your custom file at the standard location it expects. This is almost always the correct way to handle custom paths.
93+
94+
### Common Customization Examples
95+
96+
Here are examples for the most common customization requests. In all cases, **keep the environment variable at its default value** and change the volume mapping in `docker-compose.yml`.
97+
98+
#### 1. Custom CrowdSec Configuration Folder
99+
100+
If your CrowdSec configuration is stored in `/mnt/security/crowdsec`:
101+
102+
```yaml
103+
services:
104+
crowdsec-manager:
105+
environment:
106+
- CROWDSEC_ACQUIS_FILE=/etc/crowdsec/acquis.yaml # Default
107+
volumes:
108+
# Map your custom folder to the standard location
109+
- /mnt/security/crowdsec/acquis.yaml:/etc/crowdsec/acquis.yaml:ro
110+
```
111+
112+
#### 2. Custom Traefik Logs Location
113+
114+
If your Traefik logs are stored in `/var/log/custom-traefik`:
115+
116+
```yaml
117+
services:
118+
crowdsec-manager:
119+
environment:
120+
- TRAEFIK_ACCESS_LOG=/var/log/traefik/access.log # Default
121+
- TRAEFIK_ERROR_LOG=/var/log/traefik/traefik.log # Default
122+
volumes:
123+
# Map your custom log directory to the standard location
124+
- /var/log/custom-traefik:/var/log/traefik:ro
125+
```
126+
127+
#### 3. Custom Traefik Configuration File
128+
129+
If your Traefik static configuration is at `/opt/traefik/traefik.toml`:
130+
131+
```yaml
132+
services:
133+
crowdsec-manager:
134+
environment:
135+
- TRAEFIK_STATIC_CONFIG=/etc/traefik/traefik_config.yml # Default
136+
volumes:
137+
# Map your custom config file to the standard location
138+
- /opt/traefik/traefik.toml:/etc/traefik/traefik_config.yml:ro
139+
```
140+
141+
#### 4. Custom Traefik Dynamic Configuration
142+
143+
If your dynamic configuration is at `/opt/traefik/dynamic/rules.yml`:
144+
145+
```yaml
146+
services:
147+
crowdsec-manager:
148+
environment:
149+
- TRAEFIK_DYNAMIC_CONFIG=/etc/traefik/dynamic_config.yml # Default
150+
volumes:
151+
# Map your custom dynamic config to the standard location
152+
- /opt/traefik/dynamic/rules.yml:/etc/traefik/dynamic_config.yml:ro
153+
```
154+
155+
#### 5. Custom CrowdSec Manager Logs
156+
157+
If you want the manager's own logs to be stored in `/var/log/crowdsec-manager`:
158+
159+
```yaml
160+
services:
161+
crowdsec-manager:
162+
environment:
163+
- LOG_FILE=/app/logs/crowdsec-manager.log # Default
164+
volumes:
165+
# Map your custom log directory to the standard location
166+
- /var/log/crowdsec-manager:/app/logs
167+
```

‎internal/config/config.go‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,6 @@ type Config struct {
4444
GerbilContainerName string
4545
TraefikContainerName string
4646

47-
// CrowdSec LAPI Configuration
48-
CrowdSecLAPIUrl string
49-
CrowdSecLAPIMachineID string
50-
CrowdSecLAPIPassword string
5147

5248
// Services
5349
Services []string
@@ -87,9 +83,6 @@ func Load() (*Config, error) {
8783
PangolinContainerName: getEnv("PANGOLIN_CONTAINER_NAME", "pangolin"),
8884
GerbilContainerName: getEnv("GERBIL_CONTAINER_NAME", "gerbil"),
8985
TraefikContainerName: getEnv("TRAEFIK_CONTAINER_NAME", "traefik"),
90-
CrowdSecLAPIUrl: getEnv("CROWDSEC_LAPI_URL", "http://crowdsec:8080"),
91-
CrowdSecLAPIMachineID: getEnv("CROWDSEC_LAPI_MACHINE_ID", ""),
92-
CrowdSecLAPIPassword: getEnv("CROWDSEC_LAPI_PASSWORD", ""),
9386
IncludeCrowdsec: getEnvAsBool("INCLUDE_CROWDSEC", true),
9487
IncludePangolin: getEnvAsBool("INCLUDE_PANGOLIN", true),
9588
IncludeGerbil: getEnvAsBool("INCLUDE_GERBIL", true),

0 commit comments

Comments
 (0)