lanrenbang/caddy-services repository overview

⁠caddy-services

English⁠ | 简体中文⁠

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.

⁠Features

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

⁠Project Structure

.
├── 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.md

⁠Usage

1. Install Docker or Podman (recommended), or choose to run natively.
2. Clone this repository:

git clone https://github.com/Lanrenbang/caddy-services.git

1. Copy or rename .env.warp.example⁠ to .env.warp and modify the necessary content as needed.
2. Refer to the internal comments to modify compose.yaml⁠/compose.override.yaml⁠ as required.
3. 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> - 

1. Enter the root directory and start the container service:

docker compose up -d
podman compose up -d

⁠About Modules

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

⁠Others

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

⁠Related Projects

• xray-services⁠
• xray-api-bridge⁠

⁠Credits

• caddy⁠

⁠Support Me

⁠License

This project is distributed under the terms of the LICENSE file.