streamline package naming

2026-07-29 13:07:34 +02:00
parent 1ba1c2a32a
commit 7e703c93b1
100 changed files with 141 additions and 139 deletions
@@ -0,0 +1,120 @@
+# caddy
+
+**Install Caddy webserver**
+
+## Purpose
+
+This cube installs Caddy, a modern, powerful web server with automatic HTTPS that's designed to be easy to use and configure.
+
+## What is Caddy?
+
+Caddy is a next-generation web server that stands out for its simplicity and built-in security:
+
+- **Automatic HTTPS**: Automatically obtains and renews SSL/TLS certificates from Let's Encrypt
+- **Modern HTTP features**: HTTP/2, HTTP/3 (QUIC) support out of the box
+- **Simple configuration**: Human-readable Caddyfile format
+- **Reverse proxy**: Easy proxying to backend applications
+- **Static file serving**: Fast and efficient static site hosting
+- **Zero-downtime reloads**: Update config without dropping connections
+
+## What This Cube Does
+
+1. **Adds Caddy's official repository**
+   - Installs required dependencies (debian-keyring, apt-transport-https, curl)
+   - Downloads and installs Caddy's GPG signing key
+   - Configures APT to use Caddy's official stable repository
+
+2. **Installs Caddy**
+   - Installs the latest stable version of Caddy
+   - Sets up the Caddy service
+
+3. **Configures TLS**
+   - Creates a Caddyfile with a reusable TLS snippet
+   - Configures TLS based on the `TLS` parameter
+
+## Configuration
+
+### Parameters
+
+- **TLS** (string, default: `''`)
+  - TLS certificate configuration
+  - **Options**:
+    - `''` (empty string) - Automatic HTTPS with Let's Encrypt (recommended)
+    - `'internal'` - Use Caddy's internal CA for self-signed certs (testing only)
+    - `'/path/to/cert /path/to/key'` - Provide custom certificate paths
+
+## Dependencies
+
+None - this cube can run standalone.
+
+## TLS Configuration Examples
+
+**Automatic HTTPS (Production)**:
+```javascript
+exec('caddy', { TLS: '' })
+```
+Caddy will automatically obtain SSL certificates from Let's Encrypt for your domain.
+
+**Self-Signed for Testing**:
+```javascript
+exec('caddy', { TLS: 'internal' })
+```
+Uses Caddy's internal CA. Browsers will show security warnings.
+
+**Custom Certificates**:
+```javascript
+exec('caddy', { TLS: '/etc/ssl/certs/mycert.pem /etc/ssl/private/mykey.pem' })
+```
+Use your own certificate and private key files.
+
+## Post-Installation
+
+The Caddyfile is created at `/etc/caddy/Caddyfile` with a reusable TLS snippet:
+
+```
+(tls_cert) {
+    tls {TLS}
+}
+```
+
+Other cubes (like `caddy-spa`) can import this snippet with `import tls_cert`.
+
+## Managing Caddy
+
+Start/stop/restart Caddy:
+```bash
+sudo systemctl start caddy
+sudo systemctl stop caddy
+sudo systemctl restart caddy
+sudo systemctl status caddy
+```
+
+Reload configuration without downtime:
+```bash
+sudo systemctl reload caddy
+```
+
+Test configuration:
+```bash
+caddy validate --config /etc/caddy/Caddyfile
+```
+
+## Common Use Cases
+
+- Reverse proxy for Node.js/Python/Go apps
+- Static website hosting
+- API gateway
+- Load balancer
+- SSL/TLS termination
+
+## Notes
+
+- Caddy runs on ports 80 (HTTP) and 443 (HTTPS) by default
+- Ensure these ports are open in your firewall (UFW)
+- For automatic HTTPS, your domain must point to your server's IP
+- Caddy automatically redirects HTTP to HTTPS when using automatic HTTPS
+
+## Additional Resources
+
+- [Caddy Documentation](https://caddyserver.com/docs/)
+- [Caddyfile Tutorial](https://caddyserver.com/docs/caddyfile-tutorial)
@@ -0,0 +1,34 @@
+from pyinfra.operations import  apt, server, files
+from pyinfra import host
+from io import StringIO
+
+# 🔹 Variables
+TLS = host.data.TLS
+
+server.shell(
+    commands=[
+        f"sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl",
+        f"curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg",
+        f"curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list"
+    ] 
+)
+
+apt.packages(
+    name='Install caddy',
+    packages=['caddy'],
+    update=True,
+    _sudo=True
+)
+
+
+TLS_BLOCK = f"""
+(tls_cert) {{
+    tls {TLS}
+}}
+"""
+
+files.put(
+    src = StringIO(TLS_BLOCK), # local filename to upload,
+    dest = '/etc/caddy/Caddyfile', # the remote filename to upload to
+    _sudo=True
+)
@@ -0,0 +1,19 @@
+import { Manifest } from '@bitsquare/nopy-cubes';
+import { z } from 'zod';
+
+export default Manifest({
+  id: 'caddy',
+  name: 'Install Caddy webserver',
+  dependencies: () => [],
+  schema: z.object({
+    // tls /path/to/cert.pem /path/to/key.pem
+    TLS: z
+      .string()
+      .default('')
+      .describe(`
+            <empty-string> --> enabled and automatically managed
+            internal --> use Caddy custom root CA for self-signed certs (for testing purpose)
+            /path/to/cert /path/to/key --> Provide custom certificates
+            `),
+  }),
+});
@@ -0,0 +1,137 @@
+# caddy-spa
+
+**Configure Caddy to serve a Single Page Application**
+
+## Purpose
+
+This cube adds a reverse proxy configuration to Caddy for serving a Single Page Application (SPA) from a local backend server, with automatic HTTPS support.
+
+## What This Cube Does
+
+1. **Adds domain configuration to Caddyfile**
+   - Creates a site block for the specified domain
+   - Configures reverse proxy to forward traffic to local application
+   - Imports TLS configuration from the `caddy` cube
+
+2. **Configures reverse proxy**
+   - Proxies all requests to `localhost:{PORT}`
+   - Preserves headers and client information
+   - Handles WebSocket connections
+
+3. **Restarts Caddy service**
+   - Applies the new configuration immediately
+
+## Configuration
+
+### Parameters
+
+- **DOMAIN** (string, default: `''`)
+  - Domain name for the SPA application
+  - Example: `'myapp.example.com'`
+  - Must have DNS pointing to your server's IP
+
+- **PORT** (number, default: `5432`)
+  - Port number where the SPA will be served
+  - Your application should be listening on this port locally
+
+## Dependencies
+
+- **caddy** cube (implicitly required) - Must be installed first to provide the `tls_cert` snippet
+
+## What Gets Configured
+
+This cube adds the following to `/etc/caddy/Caddyfile`:
+
+```
+# BEGIN DOMAIN myapp.example.com
+myapp.example.com {
+    import tls_cert
+    reverse_proxy localhost:5432
+}
+# END myapp.example.com
+```
+
+## Use Cases
+
+**Deploy a React/Vue/Angular app**:
+```javascript
+exec('caddy-spa', {
+  DOMAIN: 'app.example.com',
+  PORT: 3000
+})
+```
+
+**Deploy multiple SPAs**:
+```javascript
+exec('caddy-spa', { DOMAIN: 'app1.example.com', PORT: 3000 })
+exec('caddy-spa', { DOMAIN: 'app2.example.com', PORT: 3001 })
+exec('caddy-spa', { DOMAIN: 'app3.example.com', PORT: 3002 })
+```
+
+## How It Works
+
+1. User visits `https://myapp.example.com`
+2. Caddy receives the request on port 443 (HTTPS)
+3. Caddy automatically handles SSL/TLS encryption
+4. Request is forwarded to `localhost:5432`
+5. Your application receives the request and returns a response
+6. Caddy sends the encrypted response back to the user
+
+## Prerequisites
+
+Before deploying this cube:
+
+1. **Install the caddy cube first**
+   - Provides the base Caddy installation and TLS configuration
+
+2. **Ensure your application is running**
+   - Your SPA backend should be listening on the specified PORT
+   - Example: `npm start` or `pm2 start app.js`
+
+3. **Configure DNS**
+   - Point your domain's A record to your server's IP address
+   - Wait for DNS propagation (can take a few minutes to hours)
+
+4. **Open firewall ports**
+   - Ensure ports 80 and 443 are open (for automatic HTTPS)
+   - `sudo ufw allow 80/tcp`
+   - `sudo ufw allow 443/tcp`
+
+## Post-Installation
+
+Verify the configuration:
+```bash
+sudo caddy validate --config /etc/caddy/Caddyfile
+```
+
+Check Caddy status:
+```bash
+sudo systemctl status caddy
+```
+
+View Caddy logs:
+```bash
+sudo journalctl -u caddy -f
+```
+
+## Common Issues
+
+**502 Bad Gateway**:
+- Your application isn't running on the specified PORT
+- Check: `netstat -tlnp | grep {PORT}`
+
+**Certificate errors**:
+- DNS not pointing to your server
+- Ports 80/443 blocked by firewall
+- Check Caddy logs: `sudo journalctl -u caddy -f`
+
+**Domain not resolving**:
+- DNS propagation not complete yet
+- Verify with: `dig +short myapp.example.com`
+
+## Notes
+
+- Caddy automatically obtains and renews Let's Encrypt certificates
+- The reverse proxy preserves the original client IP and headers
+- WebSocket connections are automatically supported
+- You can add multiple domains by running this cube multiple times with different parameters
@@ -0,0 +1,32 @@
+from pyinfra.operations import  apt, server, files
+from pyinfra import host
+from io import StringIO
+
+# 🔹 Variables (Modify as Needed)
+DOMAIN = host.data.DOMAIN
+PORT = host.data.PORT
+
+
+site_block = f"""# BEGIN DOMAIN {DOMAIN}
+{DOMAIN} {{
+    import tls_cert
+    reverse_proxy localhost:{PORT}
+}}
+# END {DOMAIN}
+"""
+
+files.block(
+    path = '/etc/caddy/Caddyfile', 
+    content = site_block, 
+    present = True, 
+    before = False,
+    after = False, 
+    _sudo = True
+)
+
+server.service(
+    service='caddy',
+    running=True, 
+    restarted=True,
+    _sudo=True
+)
@@ -0,0 +1,12 @@
+import { Manifest } from '@bitsquare/nopy-cubes';
+import { z } from 'zod';
+
+export default Manifest({
+  id: 'caddy:spa',
+  name: 'Install single page application',
+  dependencies: () => [],
+  schema: z.object({
+    DOMAIN: z.string().describe('Domain name for the SPA application').default(''),
+    PORT: z.number().describe('Port number where the SPA will be served').default(5432),
+  }),
+});