Caddyserver examples Syntax Examples Wildcard matchers Path matchers Named matchers Standard matchers client_ip expression file header header_regexp host method not path path_regexp protocol query remote_ip vars vars_regexp Syntax In the Caddyfile, a matcher token immediately following the directive can limit that OBSOLETE. com, with the CA customized via the pki global option, and issuing its own certificate using the internal issuer: { pki { ca home { name "My Home CA" } } } acme. Syntax handle_path <path_matcher> { <directives> } <directives> is a list of HTTP handler directives OBSOLETE. Simply choose a folder that describes what you're trying to use Caddy for or with. Dec 8, 2020 · An example of a Caddy 2 JSON configuration file for a reverse proxy that uses the Cloudflare DNS module - Caddy 2 Cloudflare DNS Example. - Lotharok/caddy-config-guide import Includes a snippet or file, replacing this directive with the contents of the snippet or file. com { reverse_proxy localhost:8080 { transport http { dial_timeout 2s response_header_timeout 30s } } } Reverse proxy to an HTTPS upstream: example. Contribute to caddyserver/dist development by creating an account on GitHub. The repository contains over 20 different application deployment examples, ranging from content management systems to development frameworks and infrastructure services. Note that the URI does not include scheme or authority (host & port), and clients typically do not send fragments. redir Issues an HTTP redirect to the client. Pay attention to when the file you're looking at was last updated. This directive allows you to match responses, and the first matching handle_response route or replace_status will be invoked. This can typically be done with sudo -u caddy <command>. For example, this config is all it takes to obtain and renew certificates for a set of domain names. Tagged with caddy, server, vps, webserver. It expects that any index. By default, the written status code will typically be 200, or 206 for partial content. In other words, when multiple handle directives appear in sequence, only the first matching handle block will be evaluated. Contribute to jnaskali/caddy-examples development by creating an account on GitHub. Many parts of this config are extensible through the use of Caddy modules. email@address. Caddy Server is the first and only web server to use HTTPS automatically with no extra configuration or separate tooling required. - caddyserver/examples OBSOLETE. 0 to expose Caddy service in Docker Local dev server with self-signed TLS certificate Prevent automatic http-to-https redirect Return a plain text response Reverse proxy plus static files Routing multiple paths to a reverse proxy Serve static files When serving static files, you may want Caddy to only serve static files, or sometimes you may want Caddy to serve static files and run as a reverse proxy. Docker and Docker Compose provide a consistent environment for containerizing and deploying applications View the Unikraft application catalog and the KraftCloud platform examples (powered by Unikraft). For v2 and newer, see our forum's wiki category. com { log handle /static* { log_append area "static" respond "Static response!" } handle { log_append area "dynamic" reverse_proxy localhost:9000 } } Feb 25, 2025 · This HTTPS functionality built into Caddy can be a great utility, especially if you are running software where you have multiple domain names or intend to allow other users to point a domain name to your Caddy server. It's a <find> is the substring or regular expression to search for. com } Enable the DNS challenge for a domain managed on Cloudflare with account credentials in an environment variable. However, if you need a OBSOLETE. handlers. The hashed password for user1 can be generated using Caddy: OBSOLETE. Caddy config is expressed natively as a JSON document. 0 respond "Hello, world!" } handle Evaluates a group of directives mutually exclusively from other handle blocks at the same level of nesting. While Nginx is very fast and a big name in the industry, Caddy has some awesome features like - Automatic HTTPS: Caddy, by default obtains/renews SSL/TLS certificates from Let's Encrypt / ZeroSSL. Keep Caddy Running While Caddy can be run directly with its command line interface, there are numerous advantages to using a service manager to keep it running, such as ensuring it starts automatically when the system reboots and to capture stdout/stderr logs. com reverse_proxy localhost:2021 } That's it! The one line containing the tls directive tells Caddy to serve the domain via SSL and use the given email address for the ACME account that manages the site's certificates. - caddyserver/examples Caddy is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go OBSOLETE. When invoked, the original response body is http. OBSOLETE. com { reverse_proxy https://example. pkg install os-caddy View the FreeBSD caddy-custom makefile and the os-caddy plugin source Jun 22, 2024 · The alternative is to use a docker run command but this . e. The other two servers are going to act as the web servers. This server is more than just code; it’s practically your automated assistant. json above and note how the curl response changes. php at the site root acts OBSOLETE. Its contents will replace this line as if that Caddy Reverse Proxy With Docker In this guide, I'll walk through the process of setting up a Caddy reverse proxy using Docker and Docker Compose. Can be: A Caddy is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go Syntax log_append [<matcher>] <key> <value> Examples Display in the logs the area of the site that the request is being served from, either static or dynamic: example. The rewrite directive implies the intent to accept the request, but with modifications. To configure Caddy's runtime logs, see the log global option instead. For example, let's suppose we want to have both a file server and a reverse proxy, but we obviously can't do both on every request! Either the file server will write a response with a static file, or the reverse proxy will pass the request to a backend and write back its response. replace_response manipulates response bodies by performing substring or regex replacements. com/caddyserver/caddy | Installer Source | Releases (json) (tab) Mar 9, 2022 · This setup will configure the WebDAV module for the webdav. This may be used with any handler that produces responses, including those from plugins like FrankenPHP 's php_server. The directive may be repeated with different status codes to handle different errors differently. 🔗 servers/routes/match ModuleMap is a map that can contain multiple modules, where the map key is the module's name. - caddyserver/examples A comprehensive guide to configuring and troubleshooting Caddy server. example. Set up Caddy as a reverse proxy and quickly streamline access to your services. Can be a 3-digit status code, For example: 404. The handle directives are sorted according to the directive sorting algorithm by their matchers. We will be using three servers. html, and /index. However, if you set your domain as 0. Menu Using the API Using a Caddyfile Static file server Reverse proxy HTTPS Simple guided examples of how to use Caddy. 🔗 servers/listen There are no docs for this property. com { tls { issuer internal { ca foo } } } Specify an email address for your ACME account (but if only one email is used for all sites, we recommend the email global option instead): example. This directive is a special case in that its subdirectives are also regular directives. Dec 30, 2021 · In the example above, we told Caddy to forward all requests hitting Caddy to the configured server behind the reverse proxy. They are intended to illustrate some of the most common configuration patterns. It is mutually The plugin scans Docker metadata, looking for labels indicating that the service or container should be served by Caddy. OPNsense Note: This is a community-maintained installation method. So I would be interested into converted htaccess files to get applications (cms, ) working with caddy (+php-fpm). Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS - caddyserver/caddy For example, when running Caddy as a systemd service, it will run as the caddy user, so you should run the export or import commands as that user. It is highly recommended that you follow-up by reading other tutorials and reference documentation to fully understand how your web server works. Build Caddy with plugins. rewrite Rewrites the request URI internally. Using an environment If you’re deploying an app built with a framework like Django, you’ll likely want to serve the application through a reverse proxy, then have Caddy serve your static files directly. As Francis Lavoie explains on the Caddy Forum: The issue is that the reverse Reverse proxy quick-start This guide will show you how to get a production-ready reverse proxy with or without HTTPS up and running quickly. - caddyserver/examples Jul 28, 2024 · Caddy Server Just like Nginx, Caddy is a cross-platform, open-source web server. Linux Service Unit Files Manual Installation Using the Service Local HTTPS Overrides Environment variables run and reload override middleware cache varnish caddy tyk traefik gin-middleware skipper labstack-echo caddy-server caddyserver gin-gonic caddy-plugin echo-framework http-cache tyk-gateway traefik-v2 caddy-module traefik-plugin souin-instance Updated 2 weeks ago Go Resources for packaging and distributing Caddy. html/ represent the same resource. Only serve static files To configure Caddy to only serve static files, use the file_server directive, then set the root directory. For example, if you've enabled passive health checks for your proxies, then you need to also take into consideration the fails and num_requests values to determine if an upstream is considered available: check that the fails amount is less than your configured maximum amount of failures for your proxy (i. Your first Caddyfile That was kind of a lot of work just for Hello World. To conditionally skip some requests from logging, use Mar 28, 2024 · Master traffic redirection with our Caddy tutorial. - examples/radicale/Caddyfile at master · caddyserver/examples Feb 10, 2025 · Logging in Caddy is designed to be efficient, flexible, and developer-friendly. The In the examples below, a named volume caddy_data is mounted to /data, so that data will be persisted. It also secures access to files using basic authentication. Syntax method [<matcher>] <method> <method> is the HTTP method to change the request to. A rewrite changes some or all of the request URI. This site will be a living document containing patterns I use for building Caddy-powered sites. These are not drop-in solutions; you will have to customize your domain name, ports/sockets, directory paths, etc. This directive is a special case: it is evaluated before the structure is parsed, and it can appear anywhere in the Caddyfile. Learn how you can use Caddy 2 and Docker simplify this process. php at the site root acts Jul 1, 2025 · The examples repository contains only a reference pointer to ensure users always access the most up-to-date systemd integration files. Sources: systemd/README. handle_path Works the same as the handle directive, but implicitly uses uri strip_prefix to strip the matched path prefix. There are very few responsible reasons to serve an http version of your production site. For a complete example of a site using templates to serve markdown, take a look at the source for this very website! Specifically, take a look at the Caddyfile and src/docs/index. The first server, called lb01, is going to act as the load balancer. - examples/seafile/Caddyfile at master · caddyserver/examples OBSOLETE. Maybe (working and tes php_fastcgi An opinionated directive that proxies requests to a PHP FastCGI server such as php-fpm. When hosting two or more applications on your server you want to reverse proxy each domain to a different server. They are named web01 Jul 1, 2025 · This document provides a comprehensive guide for configuring Caddy v1 to serve Nextcloud, a self-hosted cloud storage and collaboration platform. Objectives: 🔲 Run the daemon 🔲 Try the API 🔲 Give Caddy a config 🔲 Test config 🔲 Make a Caddyfile 🔲 Use the config adapter 🔲 Start with an initial config 🔲 Compare JSON and Caddyfile 🔲 Compare API and config files 🔲 Run in the Configure some transport options: example. Quick-starts These tutorials are designed to get you up and running quickly without much explanation to get in the way. Caddy’s named matchers allow you to define a set of path directives then route them all to a single reverse proxy. This requires you to configure the DNS records of your domain correctly, which should point to the address of your Caddy server. May 31, 2022 · Deploying web apps can be tough, even with leading server technologies. In this situation, Caddy can be useful as a reverse-proxy in front of your local dev server. Routing multiple paths to a reverse proxy Sometimes your app will need to route a handful of paths to one service and all other paths to another. Note that named volumes are persisted across container restarts and terminations, so if you move to a new image version, the same data and config directories can be re-used. These can be helpful starting points for your own Caddyfile documents. It handles everything you can possibly automate, from HTTPS to easy configurations. Caddy is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go Syntax log_append [<matcher>] <key> <value> Examples Display in the logs the area of the site that the request is being served from, either static or dynamic: example. Why would you need a local reverse proxy? With a hosts file, you can only map hostnames to IP OBSOLETE. Examples Remove the Referer header from the request: request_header -Referer Delete all headers containing an underscore from the request: request_header -*_* Dec 31, 2015 · Hello, I found caddy a short time ago and really like it. This tutorial assumes you want to get a publicly-trusted site (i. Handling a request matching a certain path (while stripping that path from the request URI) is a common enough use case that it has its own directive for convenience. 0:80, you will see the following error: Because of this, you must use the bind directive. disable_canonical_uris disables the default behaviour of redirecting (to add a trailing slash if the request path is a directory, or remove the trailing slash if the request path is a Docker services that you want exposed to outside of the container can’t be resolved to localhost, they must instead be resolved down to 0. Contribute to Hylve/caddy-examples development by creating an account on GitHub. Every time a Docker object changes, the For expanded content like specific examples, check out our community wiki - then contribute to it! We recommend sticking to these official resources to install, configure, and run Caddy, rather than running commands or copying config snippets from random blogs and Q&A boards. Look at the Caddyfile in that folder, and follow the instructions there for more information. https://github. Nov 8, 2024 · How to Set Up the Caddy Web Server to Do All the Work for You (Well, Almost) Ever wanted to set up a web server but got lost in the labyrinth of configuration files? Enter Caddy. Caddy is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go For example, this config is all it takes to obtain and renew certificates for a set of domain names. It also redirects HTTP to HTTPS for you! Caddy uses safe and modern defaults -- no downtime, extra configuration, or separate tooling is required. - caddyserver/examples Jan 6, 2022 · Awesome! Here's a sample Caddyfile with SSL setup for the superchargejs. com { header_up Host {upstream_hostport} } } Reverse proxy to an HTTPS upstream, but ⚠️ disable TLS verification. With its plugin system, zero-config SSL support, and modern architecture, it's a good bit more powerful. The configuration demonstrates PHP-FPM integration, se example. Contribute to mholt/caddy-l4 development by creating an account on GitHub. If you prefer not to work with JSON directly, there are many config adapters available that can convert various inputs into Caddy JSON. - caddyserver/examples For example, this config is all it takes to obtain and renew certificates for a set of domain names. Fields which have a json. The Mar 18, 2023 · This only works if you use the aforementioned custom Docker network, so you need to make sure that both the service (Jenkins, for example) and the internal Caddy server is on the same network! In this case, I would create the internal Caddy server on the proxynetwork, and forward port 80 to 680 on the host machine. This repository offers a simple approach to having Caddy Server as a local reverse proxy for your Docker containers. log Enables and configures HTTP request logging (also known as access logs). Getting Started Welcome to Caddy! This tutorial will explore the basics of using Caddy and help you get familiar with it at a high level. Example Here’s a simple example of how you can use Caddy as a reverse proxy for other containers in a Docker Compose stack: First, create a docker-compose. On top of this HTTPS functionality, Caddy is also a great solution for easily setting up a reverse proxy on Ubuntu. Syntax redir [<matcher>] <to> [<code>] <to> is the target location. Linux Service Unit Files Manual Installation Using the Service Local HTTPS Overrides Environment variables run and reload override middleware cache varnish caddy tyk traefik gin-middleware skipper labstack-echo caddy-server caddyserver gin-gonic caddy-plugin echo-framework http-cache tyk-gateway traefik-v2 caddy-module traefik-plugin souin-instance Updated 2 weeks ago Go Simple guided examples of how to use Caddy. Examples Change the method for all requests under /api to POST: method /api* POST Syntax log_name [<matcher>] <names> Examples You may want to log requests to different files, for example you might want to log health checks to a separate file from the main access logs. Caddy uses HTTP redirects to enforce path canonicalization (removing trailing slashes from files, and adding them for directories). I’ve been using Caddy server off-and-on for over two years, but I find the docs less-than-helpful because they lack examples. - caddyserver/examples This repository contains community-contributed, simple, guided examples of using Caddy with a variety of web applications and purposes. Prerequisites: Basic terminal Caddy is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go Apr 18, 2025 · Learn how to use Caddy as a powerful reverse proxy with automatic HTTPS, easy configs, and blazing-fast performance. 🔗 servers/routes Route represents a collection of handlers that are gated by matching and other kinds of logic. Placeholders are supported. RawMessage type and which appear Introduction to Caddy Load Balancing In this tutorial, you will learn how to use Caddy as a web load balancer. Comprehensive guide to setting up Caddy web server with Docker, including automatic HTTPS, configuration examples, and access restrictions. <code> is the HTTP status code to use for the redirect. When running in production, automatically provision TLS certificates for the appropriate hostnames. If you choose a domain that Caddy recognizes as localhost, it will automatically sign the certificate with its internal CA. Syntax Expanded Form Explanation Examples Caddy's reverse_proxy is capable of serving any FastCGI application, but this directive is tailored specifically for PHP apps. Alternatively, you can disable http-to-https redirects for all sites in your Caddyfile by adding the following block to the top of your Caddyfile (as seen in this GitHub issue): Examples To serve an ACME server with ID home on the domain acme. The log directive applies to the hostnames of the site block it appears in, unless overridden with the hostnames subdirective. com { tls your@email. Perfect for beginners & pros alike! Simple guided examples of how to use Caddy. Do not use this configuration in production. Menu Syntax Examples Wildcard matchers Path matchers Named matchers Standard matchers expression file header header_regexp host method not path path_regexp protocol query remote_ip Syntax In the Caddyfile, a matcher token immediately following the directive can limit that directive's scope. When configured, by default all requests to the site will be logged. max_fails), and that num_requests is For example, you can serve static error pages, templated error pages, or reverse proxy to another backend to handle errors. Automatic HTTPS provisions TLS certificates for all your sites and keeps them renewed. com domain and use /data/webdav as the root directory. Thus, this directive is mostly used for path and query string manipulation. Syntax Matchers status header Syntax If a directive accepts response matchers, the usage is represented as either [<response_matcher>] or Dec 11, 2024 · In this guide, you’ll learn how to install and configure Caddy Reverse Proxy. The * immediately after root tells Caddy that it should match all requests–without it, Caddy wouldn’t Some applications require HTTPS to function correctly, or you may prefer to develop with HTTPS to more closely match your production environment. Directives contained in a route block will not be reordered internally. md Caddy is a fast, multi-platform web server with automatic HTTPS. - caddyserver/examples Layer 4 (TCP/UDP) app for Caddy. Oct 29, 2024 · As part of setting up my new home server, I decided to learn Caddy. Contribute to caddyserver/xcaddy development by creating an account on GitHub. forward_auth An opinionated directive which proxies a clone of the request to an authentication gateway, which can decide whether handling should continue, or needs to be sent to a login page. HTTPS quick-start This guide will show you how to get up and running with fully-managed HTTPS in no time. caddy storage export caddy storage export -c, --config <path> [-o, --output <path>] --config is the config file load. Another way to configure Caddy is with the Caddyfile Caddyfile Concepts This document will help you learn about the HTTP Caddyfile in detail. yml file with the following contents: Request Matchers Request matchers can be used to filter (or classify) requests by specific criteria. These typically only appear as config inside of certain other directives, to make decisions on the response as it's being written out to the client. Caddy is a powerful web server that comes with built-in support for automatic HTTPS, making it an excellent choice for hosting reverse proxies. Example Run Edit If you see Hello, world!, then congrats — it's working! It's always a good idea to make sure your config works as you expect, especially before deploying into production. Response Matchers Response matchers can be used to filter (or classify) responses by specific criteria. md 3 Repository Structure Integration Sources: systemd/README. Syntax import <pattern> [<args>] [{block}] <pattern> is the filename, glob pattern, or name of snippet to include. Improve security and optimize routing for your applications. - examples/flask/Caddyfile at master · caddyserver/examples Simple guided examples of how to use Caddy. Caddy v2, Nextcloud, Bitwarden, Bookstack, Prometheus+Grafana, Borg, Watchtower, Homer, Portainer, DDclient Config is the top (or beginning) of the Caddy configuration structure. md 1-4 Integration Patterns Service Lifecycle Management The systemd integration follows standard Linux service management patterns: Automatic Startup: Service starts Mar 29, 2021 · Caddy 2 Caddyfile usage examples. So, let’s get Caddy set up, sit back, and maybe For example, this config is all it takes to obtain and renew certificates for a set of domain names. Request Matchers Request matchers can be used to filter (or classify) requests by specific criteria. Complete detailed self-hosting docker guide-by-example. This directive is a convenient shortcut, replacing a longer configuration. 0 so services outside of the container can access them. com { log handle /static* { log_append area "static" respond "Static response!" } handle { log_append area "dynamic" reverse_proxy localhost:9000 } } OBSOLETE. A handle with no matcher acts like a fallback route. Structure Blocks Directives Tokens and quotes Global options Addresses Matchers Placeholders Snippets Named Routes Comments Environment variables Structure The Caddyfile's structure can be described visually: Key points: An optional global options block can be the very first thing in the file. Can be: A Caddy is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go Static files quick-start This guide will show you how to get a production-ready static file server up and running quickly. com domain: superchargejs. Learn how to deploy secure web services with Docker Compose and Caddy. - examples/shopware/Caddyfile at master · caddyserver/examples For example: /, /index. 0. com { tls { issuer internal { ca home } } acme_server { ca home } } Oct 22, 2024 · In this blog post, we’ll look at how to use Caddy Reverse Proxy with my Docker containers running across multiple hosts. - examples/grav/Caddyfile at master · caddyserver/examples Field List 🔗 servers Server represents a Caddy layer4 server. Snippets or Caddy is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go Request Matchers Request matchers can be used to filter (or classify) requests by various criteria. - caddyserver/examples Oct 30, 2024 · Caddy is a fantastic web server, let's take a look at how to do path-based reverse proxying so we can expose multiple services running on different ports on the same domain. I'm really impressed with what they've built. Examples for using Caddy Web Server This repository contains community-contributed, simple, guided examples of using Caddy with a variety of web applications and purposes. Caddy will automatically try to acquire SSL certificates for the specified domain, in this example example. :80 { bind 0. Additional config can be written to wire up certificate maintenance events, which can then be used to integrate with external scripts and tooling. not "localhost") up over HTTPS, so we'll be using a public domain name and external ports. Syntax route [<matcher>] { <directives method Changes the HTTP method on the request. Feb 25, 2025 · This HTTPS functionality built into Caddy can be a great utility, especially if you are running software where you have multiple domain names or intend to allow other users to point a domain name to your Caddy server. Contribute to sergeyt/caddyserver-examples development by creating an account on GitHub. Caddy innovated automatic HTTPS technology; we've been doing intercept A generalized abstraction of the response interception feature from the reverse_proxy directive. However, if you just try to put a root and file_server directive into a site block that contains a reverse proxy, it won’t work. Some may need to Caddy is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go redir Issues an HTTP redirect to the client. Redirect www to non-www or vice versa. Caddy uses HTTPS for all sites by default, as long as a host name is provided in the config. (The namespace is usually read from an Automatic HTTPS Caddy is the first and only web server to use HTTPS automatically and by default. <replace> is the replacement value; required if performing a search-and-replace. Syntax Expanded Form Examples Authelia Tailscale Caddy's reverse_proxy is capable of performing "pre-check requests" to an external service, but this directive is tailored specifically for the route Evaluates a group of directives literally and as a single unit. Try changing the body in the caddy. yml file will save the configuration and help you remember how the container is configured. Prerequisites: Basic terminal / command line skills caddy in your PATH A folder containing your website OBSOLETE. Becomes the response's Location header . For that reason, its directive order is very early. Only HTTP handler directives (directives which add handlers or middleware to the chain) can be used in a route block. Only use this configuration for development. Then, it generates an in-memory Caddyfile with site entries and proxies pointing to each Docker service by their DNS name or container IP. This directive implies that a matched request is to be rejected as-is, and the client should try again at a different URL. Prerequisites: Basic terminal / command line skills caddy in your PATH A running backend process to proxy to Caddy Server Examples Return a plain text response Returning a plain text response with Caddy can be useful for debugging, ensuring that the server is indeed working before configuring a something like a reverse proxy. html. As usual, the first line is the site address. - caddyserver/examples Ideally, a single Caddyfile could handle the following use cases without relying on different files for development and production: When running locally, develop using the localhost hostname without having to provision certificates. Caddy Server Examples Examples Binding to 0. - caddyserver/examples. com { tls your. Under the hood, it uses the high-performance Zap logging library to provide structured logging out of the box, ensuring zero allocation overhead even under high load. Caddy is a replacement for nginx/apache. It's been a while since I've used something that just felt right: well-designed, great abstractions, good defaults, etc. This repo was for Caddy v1. org. mdba ldkar xggmc pqt nhc ccim dlnbc myzs ymabv wfp tayifuu gybcfr llbnpf chjjikp bdrk