You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Docker Stack** is a developer-oriented project that provides:
9
10
10
-
This project is composed of a 2 things :
11
+
-**A powerful CLI tool (`dctl`)**: A drop-in replacement for Docker Compose, with extra features and improved usability.
12
+
-**A curated collection of Docker Compose files**: Ready-to-use configurations for a complete local development stack.
11
13
12
-
- A Docker Compose compatible CLI, but with more features; try it!
13
-
- A collection of Docker Compose files that aims to provide a functional common web stack for developers. It's easy to intergrate your own projects around the stack.
14
+
You can use the CLI and the compose files independently or together, depending on your needs.
14
15
15
-
[**Cli tool**](doc/dctl.md) and [**compose files collection**](doc/collection.md) are independants, you can use cli without the compose files and vice versa.
16
+
---
16
17
17
-
## Documentation
18
+
## Overview
18
19
19
-
- Manage your local docker compose projects easilly with [the cli tool : dctl](doc/dctl.md)
20
-
- Your local stack for web development. [A collection of docker-compose files](doc/collection.md)
20
+
-**[CLI Tool Documentation](doc/dctl.md):** Manage your local Docker Compose projects more easily with `dctl`.
21
+
-**[Compose Files Collection](doc/collection.md):** Quickly set up a local web development stack with pre-configured services.
22
+
-**[Changelog](CHANGELOG.md):** See what's new.
21
23
22
-
- The project [change log](CHANGELOG.md)
24
+
---
23
25
24
-
## "dctl" cli vs "docker compose" ?
26
+
## Why use `dctl` instead of `docker compose`?
25
27
26
-
With **dctl**,
27
-
28
-
- no need to be in the project folder,
29
-
- no need to know new commands and arguments, "dclt" use the same ones as docker compose, you won't be lost,
30
-
31
-
With **dctl**, you can manage your project from everywhere in your terminal.
28
+
- No need to be in your project folder.
29
+
- Uses the same commands and arguments as Docker Compose—no new learning curve.
30
+
- Manage multiple projects from anywhere in your terminal.
31
+
- Easily override default compose files and set default arguments for all commands.
The cli can "manage" multiple docker-compose files (start, stop, down, restart, build and more) from **everywhere in your terminal**. With this tool, you can **avoid declaring multiple aliases** in your shell, and you can use the same command to start/stop/restart/ and so on for all your projects. The cli offers an **easy way to override default docker-compose** file for a project, you can also define **default arguments for all docker-compose commands** to avoid repeating them in the command line.
35
+
With `dctl`, you can start, stop, restart, build, and manage multiple Docker Compose projects from anywhere, without the need for custom shell aliases. The CLI also allows you to define default arguments and override compose files per project.
36
36
37
-
[See more](doc/dctl.md)
37
+
---
38
38
39
-
## Roadmap / next steps
39
+
## Roadmap
40
40
41
-
-[ ] Documentation - add examples of docker-compose files for local development.
41
+
-[ ] Add more documentation and examples for local development.
42
+
-[ ] Add commands to register/unregister projects using docker-compose files.
43
+
-[ ] Make default arguments optional and project-specific.
44
+
-[ ] Improve merging of default and command-line arguments.
42
45
43
46
### v1
44
47
45
-
-[x]~~Build - Plublish the cli tool for multiples platforms (Windows, Mac, Linux), different architectures (x86, arm, arm64).~~
A pre-configured docker-compose files [collection](collection) helping web developers.
7
+
This repository provides a curated collection of ready-to-use Docker Compose files for local web development. The collection is organized into five categories: **web**, **data**, **logging**, **tools**, and **monitoring**. Each service is pre-configured for easy integration and can be customized to fit your needs.
8
8
9
-
The collection is composed of five categories (web, data, logging, tools, monitoring). To use a service, each ```.dist``` files need to be copy as as ```.yml``` file.
9
+
To use a service, copy the corresponding `.dist` file to `.yml` (e.g., `docker-compose.yml.dist` → `docker-compose.yml`).
| Traefik | expose localy your application through a local domain | web | stack.web.reverse |[⤴](https://hub.docker.com/_/traefik)|[⤴](https://docs.traefik.io/en/latest/)|
14
-
|Mail Catcher | catch all emails sent | web | stack.web.mailcatcher |[⤴](https://hub.docker.com/r/schickling/mailcatcher)|[⤴](https://mailcatcher.me/)|
15
-
| PostgreSQL | A relational database | data | stack.data.postgres |[⤴](https://hub.docker.com/_/postgres/)|[⤴](https://www.postgresql.org/docs/)|
16
-
| MySQL | A relational database | data | stack.data.mysql |[⤴](https://hub.docker.com/_/mysql)|[⤴](https://dev.mysql.com/doc/)|
17
-
| Redis | The cache | data | stack.data.redis |[⤴](https://hub.docker.com/_/redis)|[⤴](https://redis.io/docs/)|
18
-
| RabbitMQ| The message broker | data | stack.data.rabbitmq |[⤴](https://hub.docker.com/_/rabbitmq)|[⤴](https://www.rabbitmq.com/documentation.html)|
| Traefik | Expose your apps locally via domain names | web | stack.web.reverse |[⤴](https://hub.docker.com/_/traefik)|[⤴](https://doc.traefik.io/traefik/)|
14
+
|MailCatcher | Catch all outgoing emails | web | stack.web.mailcatcher|[⤴](https://hub.docker.com/r/schickling/mailcatcher)|[⤴](https://mailcatcher.me/)|
15
+
| PostgreSQL | Relational database | data | stack.data.postgres|[⤴](https://hub.docker.com/_/postgres/)|[⤴](https://www.postgresql.org/docs/)|
16
+
| MySQL | Relational database | data | stack.data.mysql|[⤴](https://hub.docker.com/_/mysql)|[⤴](https://dev.mysql.com/doc/)|
17
+
| Redis | In-memory cache | data | stack.data.redis|[⤴](https://hub.docker.com/_/redis)|[⤴](https://redis.io/docs/)|
18
+
| RabbitMQ| Message broker | data | stack.data.rabbitmq|[⤴](https://hub.docker.com/_/rabbitmq)|[⤴](https://www.rabbitmq.com/documentation.html)|
| Portainer CE | Container manager | tools | stack.tools.portainer|[⤴](https://hub.docker.com/r/portainer/portainer.ce)|[⤴](https://docs.portainer.io/)|
24
24
25
-
You can add our own services to the collection and customize the existing ones.
26
-
**Softwares version** and **few properties** are also **configurable**, this is defined in the environment file on the root of the collection.
25
+
You can add your own services or customize the existing ones. **Software versions** and some properties are configurable via the `.env` file at the root of the collection.
27
26
28
-
If you want to contribute and improve this project, fix a typo, make it better (sorry for my english, please correct me), you're welcome, make me a PR.
27
+
---
28
+
29
+
## Getting Started
29
30
30
31
### Requirements
31
32
32
-
[Docker](https://docs.docker.com/engine/install/) is required to run the stack. The stack share the same [docker network](https://docs.docker.com/network/) to facilated communication between containers. The network is named "stack_dev" by default.
33
+
-[Docker](https://docs.docker.com/engine/install/) must be installed.
34
+
- All containers share a common Docker network (default: `stack_dev`) for easy inter-service communication.
35
+
36
+
Create the network (if not already present):
33
37
34
38
```bash
35
39
docker network create stack_dev
36
40
```
37
41
38
-
Be free to change the name of the network, you can change it by editing the ```.env``` file in the root of the collection.
39
-
40
-
Copy the ```.env.dist``` file to ```.env```, and change the value of the ```DOCKER_NETWORK``` variable.
41
-
42
-
### 1. Web
43
-
44
-
This is the **base** of all web projects, composed of the following services:
42
+
You can change the network name by editing the `DOCKER_NETWORK` variable in the `.env` file. Start by copying `.env.dist` to `.env` and adjusting values as needed.
45
43
46
-
- A reversed proxy service (Traefik) that forwards requests to your different applications. You don't have to worry about multiple applications port number, the request can be routed to the right application by following a local domain name rule (a host rule in Traefik). So, each application can have is own local domain. For example, the application "myapp" can be accessible at the address ```myapp.stack.local```.
47
-
- A mail catcher service (MailCatcher) that captures all emails sent from your applications. This is avoid to send accidentally emails to real users, you can also check the content of the emails sent by your application whitout beeing connected to Internet.
44
+
---
48
45
49
-
#### 1.1. Reverse proxy
46
+
##Category Details
50
47
51
-
The reverse proxy web interface is available via a local domain. The domain is defined in the environnement file, ```DOMAIN```.
52
-
To work, ```the local domain should target the Docker Host IP```.
48
+
### 1. Web
53
49
54
-
https://dashboard.stack.local (default)
50
+
-**Traefik**: Reverse proxy for routing requests to your apps using local domain names (e.g., `myapp.stack.local`).
51
+
-**MailCatcher**: Captures all outgoing emails for safe testing.
If you want to use a local domain with your application, you must explicitly set the use traefik with docker labels:
55
+
To expose your app at a local domain, add these labels to your service:
59
56
60
57
```yaml
61
58
services:
62
-
# Your application web server
63
59
nginx:
64
60
container_name: myapp-nginx
65
61
image: nginx:1.20
@@ -73,70 +69,42 @@ services:
73
69
- "8080"
74
70
```
75
71
76
-
Your application can be accessed at ```http://myapp.stack.local```. The entrypoint is ```web``` (port 80), Traefik forwards requests to the port 8080 of your application. Note that the application port 8080 is not exposed.
77
-
78
-
#### 1.2. MailCatcher
72
+
Your app will be accessible at `http://myapp.stack.local` (Traefik forwards to port 8080 inside the container).
79
73
80
-
The mail catcher web interface is available via a local domain.
74
+
#### MailCatcher
81
75
82
-
http://mailcatcher.stack.local (default)
76
+
- Web interface: [http://mailcatcher.stack.local](http://mailcatcher.stack.local)
The SMTP server is exposed on the port 1025, no authentication is required.
79
+
---
87
80
88
81
### 2. Data
89
82
90
-
- A Redis service that provides a cache.
91
-
- A RabbitMQ service that provides a message broker.
92
-
- A PostgreSQL service that provides a PostrgreSQL database instance.
93
-
- A MySQL service that provides a MySQL database instance.
94
-
95
-
#### 2.1. Redis
96
-
97
-
Redis service is exposed on port 6379, no authentication is required.
98
-
99
-
#### 2.2. RabbitMQ
100
-
101
-
RabbitMQ service is exposed on port 5672, and the managment interface is available via http://rabbitmq.stack.local
102
-
Credentials are defined in the ```.env``` file.
103
-
104
-
105
-
106
-
#### 2.3. PostgreSQL
107
-
108
-
PostgreSQL service is exposed on port 5432, the default port for PostgreSQL.
109
-
Credentials are defined in the ```.env``` file.
83
+
- **Redis**: Exposed on port 6379 (no auth by default)
84
+
- **RabbitMQ**: Exposed on port 5672; management UI at [http://rabbitmq.stack.local](http://rabbitmq.stack.local) (credentials in `.env`)
85
+
- **PostgreSQL**: Exposed on port 5432 (credentials in `.env`)
86
+
- **MySQL**: Exposed on port 3306 (credentials in `.env`)
110
87
111
-
#### 2.4. MySQL
112
-
113
-
MySQL service is exposed on port 3306, the default port for MySQL.
114
-
Credentials are defined in the ```.env``` file.
88
+
---
115
89
116
90
### 3. Logging
117
91
118
-
- A Loki service (Loki) that provides a log aggregator.
119
-
- A log service (Rsyslog) that provides a log aggregator.
120
-
121
-
#### 3.1. Loki
122
-
123
-
Loki API service is exposed on port 3100, the default port for Loki. Loki is use to collect Docker logs of containers (where you have selected Loki as driver).
124
-
125
-
To use Loki, you need to [install the docker driver](https://grafana.com/docs/loki/latest/clients/docker-driver/) before, create the loki configuration using the sample file in ```logging/docker/loki/loki-local-config.yaml```. Then, connect loki API to your Grafana
92
+
- **Loki**: Log aggregation (API on port 3100, metrics at [http://loki.stack.local/metrics](http://loki.stack.local/metrics)). Loki collects logs from your containers and makes them available for querying in Grafana. To use Loki effectively, you need to:
93
+
- Install the [Loki Docker logging driver](https://grafana.com/docs/loki/latest/clients/docker-driver/).
94
+
- Configure your containers to use the Loki driver (see example below).
95
+
- Optionally, use Promtail to collect host logs and forward them to Loki.
96
+
- **Promtail**: Collects logs from the host and sends them to Loki. Configure Promtail in `logging/docker/promtail/config.yml` (rename `config.yml.dist` and adjust paths as needed).
97
+
- **Rsyslog**: (WIP)
126
98
127
-
Loki metrics are accessible at http://loki.stack.local/metrics.
99
+
#### Loki Setup & Usage
128
100
129
-
We use Grafana (in the tools stack) to explore loki collected logs.
101
+
1. **Install the Loki Docker logging driver** on your Docker host:
130
102
131
-
[Signin in Grafana](http://grafana.stack.local) with the default credentials (admin/admin) and add a Loki datasource.
132
-
133
-
[Add a new datasource](http://grafana.stack.local/datasources), and select Loki as type.
134
-
135
-
Use the Loki container name as URL : http://stack.logging.loki:3100
Promtail is a service that provides a log collector. It is used to collect logs from the host machine.
123
+
- `loki-url` should point to your Loki instance (default: `http://loki.stack.local/loki/api/v1/push`).
124
+
- You can add custom labels to help filter logs in Grafana.
155
125
156
-
Promtail use the Loki API to send logs to Loki. The provided configuration file is ```logging/docker/promtail/config.yml.dist``` is given as example.
157
-
You can see, in the ```config.yml.dist``` file, that the logs are collected from the ```/var/log``` directory, mounted in the container from docker-compose.
126
+
3. **Explore logs in Grafana**:
127
+
- Access Grafana at [http://grafana.stack.local](http://grafana.stack.local)
128
+
- Add Loki as a data source (URL: `http://stack.logging.loki:3100`)
129
+
- Use the Explore tab to query your logs (e.g., `{job="myapp"}`)
158
130
159
-
Rename the file ```config.yml.dist``` to ```config.yml``` and edit it to match your needs.
131
+
4. **Promtail (optional):**
132
+
- Promtail can collect logs from the Docker host (e.g., `/var/log`) and forward them to Loki.
133
+
- Edit `logging/docker/promtail/config.yml` to match your log paths and labels.
160
134
161
-
#### 3.3. Rsyslog
135
+
**Note:**
136
+
- Only logs sent to stdout/stderr are collected by default. For application logs, ensure your app writes to stdout or configure file-based collection with Promtail.
137
+
- For advanced Loki usage, see the [official documentation](https://grafana.com/docs/loki/latest/).
162
138
163
-
WIP, not yet provided.
139
+
---
164
140
165
141
### 4. Monitoring
166
142
167
-
WIP, not yet provided.
168
-
169
-
### 5. Tools
170
-
171
-
- A container manager, which is a tool to manage containers (Portainer).
172
-
- A Grafana service (Grafana) that provides a dashboard to visualize data.
173
-
174
-
#### 5.1. Portainer
143
+
- (WIP)
175
144
176
-
Portainer is a service that provides a web interface to manage containers.
0 commit comments