This repository provides a ready-to-deploy Docker Compose stack that seamlessly integrates Caddy, a powerful, easy-to-use web server, with PocketBase, a lightweight, open-source backend. By packaging PocketBase as a Caddy module, this setup offers a simplified and efficient way to manage your backend and frontend services.
Key Features:
- Integrated Caddy and PocketBase: Leverage Caddy's automatic HTTPS and reverse proxy capabilities alongside PocketBase's real-time database and authentication features, all within a single, cohesive environment.
- Simplified Docker Compose Deployment: Get your application up and running quickly with a pre-configured Docker Compose stack, minimizing setup complexity.
- Easy Superuser Creation: Streamlined superuser creation process via a generated link in the logs, simplifying initial setup.
- Secure HTTPS by Default: Caddy's automatic HTTPS ensures your application is served securely.
- Local Development with Self-Signed Certificates: Provides clear instructions for handling self-signed certificates when using localhost for development.
- Comprehensive Usage Instructions: Step-by-step guidance for setting up, configuring, and interacting with the stack.
- PocketBase API Access: Direct access to PocketBase's robust API for data management and user authentication.
Ideal for:
- Rapid prototyping of web applications.
- Developing backend-as-a-service (BaaS) applications.
- Creating simple, data-driven websites and mobile apps.
- Users looking for a straightforward and efficient development workflow.
This repository streamlines the deployment of Caddy and PocketBase, empowering you to focus on building your application rather than managing complex server configurations.
Caddy with builtin PocketBase (as Caddy module), all nicely wrapped up in an easy to use Docker Compose stack.
- copy the
.env.exampleto.envand fill in the required values (e.g.,FQDN=localhostor your domain) - run
docker-compose up --build -d && docker-compose logs -fto start the stack and follow the logs - to create a superuser, copy the link from the logs and paste it into your
browser. You will need to replace the
http://127.0.0.1:12345part withhttps://${FQDN}. - visit
https://${FQDN}/api/healthto do a health check. - visit
https://${FQDN}/_/to see the PocketBase dashboard and login with the superuser credentials you've previously created. - create an new user using the dashboard in the
userscollection. Use this user to authenticate and interact with the API.
When using localhost as FQDN, make sure you install the CA certificate in your browser to avoid SSL errors. The CA certificate is located in the
caddy/ca-certificatesdirectory, once you've started the stack.
Access the PocketBase dashboard under https://${FQDN}/_/
Access the PocketBase API under https://${FQDN}/api/
Refer to the PocketBase API documentation for more information on how to interact with the API.
When using localhost as FQDN, Caddy generates a self-signed certificate. You have two options:
- Install the CA certificate (recommended): The CA certificate is auto-generated in
caddy/ca-certificates/after first run. Install it in your browser/system trust store. - Accept the risk: Bypass the SSL warning in your browser (not recommended for production).
If the superuser creation link doesn't work:
- Make sure you replaced
http://127.0.0.1:12345withhttps://${FQDN}in the link from the logs - Check that your FQDN resolves correctly (add to
/etc/hostsif testing locally) - Verify the container is healthy:
docker-compose ps
If the health check keeps failing:
- Check logs:
docker-compose logs caddy - Verify PocketBase is responding:
curl -k https://localhost/api/health - Ensure port 80/443 are not already in use
- Admin API Endpoints: This setup exposes PocketBase admin endpoints at
/pocketbase/*(for superuser management). In production, consider restricting access via firewall rules or Caddy matchers. - Change Default Ports: The internal PocketBase port (8090) is configurable in the Caddyfile if you need to avoid conflicts.
- HTTPS Only: Always use valid certificates in production (Let's Encrypt via Caddy is automatic for public domains).
- Admin UI Access: The PocketBase dashboard at
/_/should be restricted to authorized IPs in production environments.
To upgrade Caddy or PocketBase:
- Caddy: Update the version in
Dockerfile(e.g.,FROM caddy:2.10-builder) - PocketBase Module: The module version is pulled at build time via
xcaddy build --with github.com/mohammed90/caddy-pocketbase@latest - Rebuild:
docker-compose up --build -d
Thanks to mohammed90 for the caddy-pocketbase module.