0. What is Caddy#
Caddy server is an open-source web server written in Golang that supports HTTP/2. It uses the Golang standard library to provide HTTP functionality. A notable feature of Caddy is that it enables HTTPS by default. It is the first web server to provide HTTPS features without requiring additional configuration.
Here are the installation instructions based on Ubuntu 18.04:
1. Installation#
You can download directly from Download Caddy, choose your platform and plugins, and you can download and run it directly.
Of course, I prefer the second method, which is to use the script from https://getcaddy.com/. The official recommendation is not to use root privileges to install and run Caddy, so we can execute the following command with ordinary user permissions.
$ curl https://getcaddy.com | bash -s personal
Caddy has personal and commercial licenses; generally, personal use can just use the personal licensed version. The commercial license requires a fee. If you need to install plugins, the syntax is as follows:
$ bash -s [personal|commercial] [plugin1,plugin2,...] [accessCode1,accessCode2...]
For example, I need to use http.filemanager / http.authz / http.login / http.minify / tls.dns.dnspod, the command and execution result are as follows:
$ curl https://getcaddy.com | bash -s personal http.filemanager,http.authz,http.login,http.minify,tls.dns.dnspod
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 7380 100 7380 0 0 12058 0 --:--:-- --:--:-- --:--:-- 12058
Downloading Caddy for linux/amd64 (personal license)...
Download verification OK
Extracting...
Backing up /usr/local/bin/caddy to /usr/local/bin/caddy_old
(Password may be required.)
Putting caddy in /usr/local/bin (may require password)
Caddy 0.11.0 (non-commercial use only)
Successfully installed
For plugin descriptions, please refer to Caddy User Guide
2. Running#
Directly execute the caddy command in the terminal script, which will use the current directory as the web root directory by default and will automatically listen for requests on port 2015, as follows:
$ cd ~/home
$ caddy
By executing http://localhost:2015/ in the browser, you can access the files under the user directory.
3. Configuration#
3.1 Temporary Server#
Caddy's configuration file is called Caddyfile. Caddy does not force you to place the configuration file in any specific folder; by default, placing the Caddyfile in the current directory will work, as follows:
$ echo 'localhost:8888' >> Caddyfile
$ echo 'gzip' >> Caddyfile
$ echo 'browse' >> Caddyfile
$ caddy
3.2 Production Environment Configuration#
When using in a production environment, you cannot carelessly place the configuration file in the current directory; generally, it will be placed in /etc/caddy.
$ sudo mkdir /etc/caddy
$ sudo touch /etc/caddy/Caddyfile
$ sudo chown -R root:www-data /etc/caddy
In addition to the configuration file, Caddy will automatically generate SSL certificates, requiring a folder to place the SSL certificates.
$ sudo mkdir /etc/ssl/caddy
$ sudo chown -R www-data:root /etc/ssl/caddy
$ sudo chmod 0770 /etc/ssl/caddy
Since the SSL folder will contain private keys, the permissions are set to 770 to prevent other users from accessing it. Finally, create a directory to place website files; if it already exists, there is no need to create it.
$ sudo mkdir /var/www
$ sudo chown www-data:www-data /var/www
After creating these files and directories, we need to configure Caddy as a service so that it can run automatically on boot and be easier to manage. Since most distributions now use systemd, I will only explain how to configure systemd here, but Caddy also supports configuration as a traditional sysvinit service; for specific methods, see here.
$ sudo curl -s https://raw.githubusercontent.com/mholt/caddy/master/dist/init/linux-systemd/caddy.service -o /etc/systemd/system/caddy.service # Download systemd configuration file from github
$ sudo systemctl daemon-reload # Reload systemd configuration
$ sudo systemctl enable caddy.service # Set Caddy service to start automatically
$ sudo systemctl status caddy.service # Check Caddy status
4. Caddyfile#
After completing the basic installation configuration, the most important thing is how to write the Caddyfile. You can directly modify the Caddyfile using vim /etc/caddy/Caddyfile, or you can modify it on your own computer and then rsync it to the server. If you modify the Caddyfile and find it not effective, you need to execute sudo systemctl restart caddy.service to restart Caddy.
4.1 Caddyfile Format#
The format of Caddyfile is relatively simple; the first line must be the website address, for example:
localhost:8080
or
example.com
The address can include a port number, in which case Caddy will only start the HTTP service on that port and will not start HTTPS. If no port number is specified, Caddy will default to binding ports 80 and 443, starting both HTTP and HTTPS services. The address can be followed by a whole bunch of directives. The basic format of Caddyfile consists of a website address and directives.
4.2 Directives#
The purpose of directives is to enable certain features for the website. There are three formats for directives. First, the simplest format is a directive without parameters, such as:
example.com
gzip
The second line, gzip, is a directive that enables gzip compression, which reduces traffic when transmitting web pages.
The second format of directives is one with simple parameters:
example.com
gzip
log /var/log/caddy/example.com.access.log
tls admin@example.com
root /var/www/
The third line, the log directive, enables logging for the website, and the parameter following the log directive tells Caddy where to store the log file. The fourth line's tls directive tells Caddy to enable HTTPS for the website and automatically request a certificate; the email parameter informs the CA of the applicant's email. (Caddy will default to using Let's Encrypt to request and renew certificates.)
Additionally, simple parameters may not be limited to one, such as the redir directive:
example.com
gzip
log /var/log/caddy/example.com.access.log
tls admin@example.com
root /var/www/
redir / https://lengzzz.com/archive/{uri} 301
The above redir directive has three parameters, meaning that all requests will be redirected using 301 to https://example.com/archive/xxx, which is very useful when changing the domain name of the website. Additionally, the tls directive has changed; it no longer just passes the email as a parameter but instead passes the paths of the certificate and private key separately, so Caddy will not automatically request a certificate but will use the provided certificate.
In this example, placeholders like {uri} are also used; a detailed list can be found here: https://caddyserver.com/docs/placeholders.
The last type of directive is one with complex parameters, which may contain many parameters, so it needs to be wrapped in a pair of curly braces, such as the header directive:
example.com
gzip
log /var/log/caddy/example.com.access.log
tls admin@example.com
root /var/www/
header /api {
Access-Control-Allow-Origin *
Access-Control-Allow-Methods "GET, POST, OPTIONS"
-Server
}
fastcgi / 127.0.0.1:9000 php {
index index.php
}
rewrite {
to {path} {path}/ /index.php?{query}
}
Lines 6-10 of the header directive add the Access-Control-Allow-Origin and Access-Control-Allow-Methods headers to all requests for /api/xxx, thus supporting JavaScript cross-origin access, and line 9 removes the Server header to prevent others from seeing the server type.
Lines 11-13 use the fastcgi directive, which means passing requests to backend programs like PHP or Ruby via fastcgi.
Lines 14-15 use the rewrite directive, which serves the purpose of internal server redirection with the parameters following to. This functionality is somewhat similar to nginx's try_files. It tells Caddy to first check if there is a file corresponding to {path} in the root directory /var/www; if not, it checks if there is a directory corresponding to {path}; if neither exists, it forwards to the index.php entry file. This functionality is generally used in PHP's MVC frameworks.
As this Caddyfile is gradually improved, the current version of the Caddyfile is now ready for direct use on the website.
4.3 Multiple HOST Websites#
So far, I have only discussed single domain websites. What if multiple domain websites are deployed on the same server? It's simple; just wrap the domain name in curly braces, as follows:
example.com {
gzip
log /var/log/caddy/railgun_moe.log
tls admin@example.com
root /var/www/
header /api {
Access-Control-Allow-Origin *
Access-Control-Allow-Methods "GET, POST, OPTIONS"
-Server
}
fastcgi / 127.0.0.1:9000 php {
index index.php
}
rewrite {
to {path} {path}/ /index.php?{query}
}
}
assets.example.com {
tls lengz@example.com
log /var/log/caddy/assets.example.com.log
redir / https://example.com/{uri} 301
}
At this point, the Caddy service can run, and these are the basic Caddy configurations; for more content, you need to learn from the official documentation.
Version Update#
Upgrading Caddy is also very simple, just like installing Caddy.
$ curl https://getcaddy.com | bash -s personal
This will automatically update to the latest version of Caddy. After updating, remember to execute sudo systemctl restart caddy.service to restart Caddy.
—EOF—
References and other materials