121 lines
3.2 KiB
Markdown
121 lines
3.2 KiB
Markdown
<div align="center">
|
|
<img src="https://git.max-richter.dev/attachments/bd842b47-da55-407b-b832-469cb2d4f841" width="30%"/>
|
|
<h2 align="center">LocalCerts</h2>
|
|
<p align="center">
|
|
Automatic HTTPS and local domain routing for Docker Compose services using Traefik and Step-CA.
|
|
</p>
|
|
</div>
|
|
|
|
Created by [@Sajito](https://github.com/Sajito)
|
|
|
|
## Setup
|
|
|
|
1. Clone this repository and navigate into the directory.
|
|
|
|
2. Start the services:
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
3. Trust the Step-CA root certificate:
|
|
```bash
|
|
curl -k https://localhost:9000/roots.pem -o roots.pem
|
|
sudo trust anchor --store roots.pem
|
|
rm roots.pem
|
|
```
|
|
|
|
## How to Use
|
|
|
|
1. Add a label to your docker compose service:
|
|
```yaml
|
|
labels:
|
|
serviceName: my-app
|
|
```
|
|
|
|
2. Your service will be accessible at `https://my-app.dev.local`.
|
|
|
|
## Troubleshooting
|
|
|
|
- If routes do not work you can open the traefik dashboard under [https://traefik.vm](https://traefik.vm) and check if the service and route exist.
|
|
|
|
- If your service is not reachable it could mean that traefik did not detect the correct port. You can set the port manually in your docker compose file:
|
|
```yaml
|
|
labels:
|
|
traefik.http.services.my-app.loadbalancer.server.port: 8080
|
|
```
|
|
> [!IMPORTANT]
|
|
> For each overwritten port you need to specify a custom `service-label` `traefik.http.services.[service-label]`. Otherwise the custom port will not be detected.
|
|
|
|
- If certificates are not renewed or have expired
|
|
```bash
|
|
docker compose up -d --force-recreate traefik
|
|
```
|
|
|
|
## Tipps
|
|
|
|
### Custom Domain Suffix
|
|
|
|
For example `dev.cool` 😎
|
|
|
|
Replace `.dev.local` with your custom domain suffix in the `config/traefik/traefik.yml` file:
|
|
```yaml
|
|
...
|
|
docker:
|
|
defaultRule: |
|
|
Host(`{{ trim (index .Labels "serviceName") }}.dev.cool`) {{range $i, $domain := splitList "," (index .Labels "serviceDomains")}}{{if ne $domain ""}}|| Host(`{{$domain}}`){{end}}{{end}}
|
|
...
|
|
```
|
|
|
|
Replace `.dev.local` with your custom domain suffix in the `config/dns/config.sample.json` file:
|
|
```json
|
|
...
|
|
{
|
|
"id": 2,
|
|
"hostname": ".dev.cool",
|
|
"ip": "",
|
|
"target": "host.docker",
|
|
"ttl": 3600,
|
|
"type": "CNAME"
|
|
}
|
|
...
|
|
```
|
|
|
|
Remove the dns_config volume
|
|
```bash
|
|
docker compose down
|
|
docker compose volukme rm dns_config
|
|
docker compose up -d
|
|
```
|
|
|
|
|
|
### Certificate Lifetime
|
|
|
|
To ensure Traefik has enough time to renew certificates, increase their duration:
|
|
```bash
|
|
docker compose exec step step ca provisioner update acme \
|
|
--x509-min-dur=20m \
|
|
--x509-max-dur=8760h \
|
|
--x509-default-dur=2160h
|
|
```
|
|
|
|
### Use the preconfigured services
|
|
|
|
If you use the preconfigured services, you can add the following snippet to you `.bashrc/.zshrc` to easily start, stop, and manage the services.
|
|
|
|
```bash
|
|
dev () {
|
|
PROJECT_DIR="$HOME/Projects/dev/services"
|
|
case "$1" in
|
|
(start) shift
|
|
docker compose -f "$PROJECT_DIR/docker-compose.yml" --profile "$@" up -d ;;
|
|
(restart) shift
|
|
docker compose -f "$PROJECT_DIR/docker-compose.yml" --profile "$@" restart ;;
|
|
(stop) shift
|
|
docker compose -f "$PROJECT_DIR/docker-compose.yml" --profile "$@" down --remove-orphans ;;
|
|
(logs) shift
|
|
docker compose -f "$PROJECT_DIR/docker-compose.yml" --profile "$@" logs -f ;;
|
|
(*) echo "Usage: dev {start|restart|stop|logs} [services...]" ;;
|
|
esac
|
|
}
|
|
```
|