How to use the command 'caddy' (with examples)

Caddy is an enterprise-ready open source web server written in Go. It is known for its automatic HTTPS functionality, making it easy to secure websites and applications. In this article, we will explore various use cases of the ‘caddy’ command.

Use case 1: Start Caddy in the foreground

Code:

caddy run

Motivation: Starting Caddy in the foreground is useful when you want to monitor its output in real-time. This is especially handy during development or troubleshooting scenarios.

Explanation: The caddy run command starts Caddy in the foreground, which means it will log all output directly to the console. This allows you to see any errors or warnings immediately and make necessary adjustments.

Example output:

2021/01/01 12:00:00.000 INFO    using adjacent Caddyfile
2021/01/01 12:00:00.001 INFO    admin        admin endpoint started        {"address": "tcp/localhost:2019", "enforce_origin": false, "origins": ["https://localhost:2019"]}
2021/01/01 12:00:00.002 INFO    http         server is listening only on the HTTP port, so no automatic HTTPS will be applied to this server {"server_name": "srv0", "http_port": 80}

Use case 2: Start Caddy with the specified Caddyfile

Code:

caddy run --config path/to/Caddyfile

Motivation: When you have multiple Caddyfiles for different environments (e.g., development, staging, production), you can specify the Caddyfile path to ensure the correct configuration is used.

Explanation: The --config flag followed by the path to the Caddyfile allows you to start Caddy using a specific configuration file. This is useful when you have multiple Caddyfiles and want to use a particular one.

Example output:

2021/01/01 12:00:00.000 INFO    using Caddyfile: /path/to/Caddyfile
2021/01/01 12:00:00.001 INFO    admin        admin endpoint started        {"address": "tcp/localhost:2019", "enforce_origin": false, "origins": ["https://localhost:2019"]}
2021/01/01 12:00:00.002 INFO    http         enabling automatic HTTPS        {"domains": ["example.com"]}

Use case 3: Start Caddy in the background

Code:

caddy start

Motivation: Running Caddy in the background is suitable for production environments or when you want to detach the server process from the current terminal session.

Explanation: The caddy start command launches Caddy as a background process, allowing it to run independently of the terminal session. This means you can close the terminal, and Caddy will continue to serve requests.

Example output:

Caddy started successfully. Process ID: 1234

Use case 4: Stop a background Caddy process

Code:

caddy stop

Motivation: When running Caddy in the background, you may need to stop the server gracefully, ensuring all active connections are properly closed.

Explanation: The caddy stop command sends a signal to the running Caddy process, instructing it to shut down gracefully. This ensures any active connections are closed, preventing potential data loss or issues.

Example output:

Caddy stopped successfully. Process ID: 1234

Use case 5: Run a simple file server on the specified port with a browsable interface

Code:

caddy file-server --listen :8000 --browse

Motivation: Quickly serving static files with an interface that allows browsing and navigation can be very useful, especially during testing or sharing files with others.

Explanation: The caddy file-server command starts Caddy as a file server, serving the specified directory on the provided port. The --listen flag sets the listening address and port, and the --browse flag enables a user-friendly browsing interface.

Example output:

2021/01/01 12:00:00.000 INFO    server       listening on ["tcp/:8000"]
2021/01/01 12:00:00.001 INFO    tls          cleaned up storage units

Use case 6: Run a reverse proxy server

Code:

caddy reverse-proxy --from :80 --to localhost:8000

Motivation: Reverse proxy servers are commonly used to route traffic from a public-facing domain or port to multiple internal destinations. This allows you to have a single entry point for incoming connections.

Explanation: The caddy reverse-proxy command configures Caddy to act as a reverse proxy. The --from flag specifies the public-facing address and port, while the --to flag defines the internal destination address and port.

Example output:

2021/01/01 12:00:00.000 INFO    http.reverse_proxy        forwarding to localhost:8000
2021/01/01 12:00:00.001 INFO    http.reverse_proxy        started HTTP/1.1 server        {"addr": ":80"}

Conclusion:

The ‘caddy’ command is a versatile tool for managing and configuring the Caddy web server. Whether you need to start Caddy in the foreground or background, specify a custom Caddyfile, serve files with a browsable interface, or run a reverse proxy server, Caddy has you covered. Understanding these use cases will help you leverage Caddy to its fullest potential for your web serving needs.