Use Caddy in a secure and simple way. Your configuration files can be shared freely without redaction. With secrets support, even your environment variable configurations can be shared safely.
- Automatic variable substitution in configuration files.
- Support for secrets in environment variables (e.g., Docker/Podman secrets).
- Automatically tracks upstream updates and rebuilds images.
- Provides out-of-the-box configuration templates, with default support for upstream services like Xray-core and xray-api-bridge.
- Configuration templates integrate L4 reverse proxy and JWT authentication modules by default, fully capable of acting as an API Gateway.
- Includes Docker/Podman build/compose configurations; easily build custom Caddy modules locally with simple configuration changes.
.
├── services # Recommended storage for sub-services
├── site # Caddy static site
│ └── web
│ └── index.html
├── templates
│ └── Caddyfile.json.template # Caddy configuration template
├── .env.warp.example # Template substitution definitions
├── .modules # Caddy module definitions
├── compose.yaml # Container orchestration config
├── compose.override.yaml # Container override config - for sub-services
├── Dockerfile # Image generation config
├── HEALTHCHECK.md # Health check instructions
├── README.md
└── README-cn.mdNote: We use JSON configuration directly instead of Caddy's default, more concise Caddyfile. This is because the Caddyfile automatically generates redundant configurations when paired with L4 modules. More importantly, the Caddyfile only supports automatic certificate configuration for explicitly declared domain site blocks, whereas our configuration does not require such site blocks at all.
- Install Docker or Podman (recommended), or choose to run natively.
- Clone this repository:
git clone https://github.com/Lanrenbang/caddy-services.gitYou can also download the Releases archive.
- Copy or rename .env.warp.example to
.env.warpand modify the necessary content as needed. - Refer to the internal comments to modify compose.yaml/compose.override.yaml as required.
- Add the information configured as secrets in the previous step to the keystore:
echo -n "some secret" | docker secret create <secret_name> -
echo -n "some secret" | podman secret create <secret_name> - Or run
docker/podman secret create <secret_name>directly and enter the secret when prompted.
Note:
<secret_name>must match the entries in.env.warpandcompose.yaml.
- Enter the root directory and start the container service:
docker compose up -d
podman compose up -d- Check the .modules configuration file. If the modules provided by this project do not meet your expectations, you will need to modify them, which means you cannot use the remote image provided by this project.
- After redefining the required modules, you can easily build a local custom image using the included Dockerfile.
- You can also push the image to your own registry; refer to the project's GitHub Workflow configuration for details.
- Caddy supports placeholders (variables), but not all fields support them, and support varies across modules. Therefore, this project uses the envwarp tool to perform variable substitution before runtime.
- A reference description for the cache module is provided in the module configuration file, but it is not currently used in this project. If needed, please research and implement it yourself.
- If you do not wish to use containers and prefer to run this project natively, please refer to the Native Execution Guide.
- For container health checks, please refer to the HEALTHCHECK Guide.
This project is distributed under the terms of the LICENSE file.
