insta-recipe/docs/plans/GenerateSSLFromExternalCaddy.md

Plan: Generate SSL From External Caddy

Context

The user has an existing Caddy container (f414de049d3c) acting as a Certificate Authority. We will leverage Caddy's built-in Automatic HTTPS features to generate a valid certificate for localhost without manually using OpenSSL. By running a temporary Caddy command inside the container, we can trigger the internal CA to issue and store the certificates, which we then export.

User Stories

Story 1: Trigger Certificate Generation

As a developer I want to trigger the external Caddy container to issue a certificate for localhost So that I have a valid certificate signed by its CA

Acceptance Criteria:

• A temporary Caddy command is executed inside the container to serve localhost on a non-conflicting port (e.g., 8443).
• This triggers Caddy's automatic HTTPS logic to generate:
  • localhost.crt
  • localhost.key
• These files are verified to exist in Caddy's storage (/data/caddy/certificates/local/localhost/).

Story 2: Export and Configure SSL

As a developer I want to copy the generated certificates to my project and configure Vite So that the dev server uses them

Acceptance Criteria:

• The following files are copied from the container to the project's .ssl/ directory:
  • Leaf Cert: /data/caddy/certificates/local/localhost/localhost.crt
  • Private Key: /data/caddy/certificates/local/localhost/localhost.key
  • Root CA: /data/caddy/pki/authorities/local/root.crt
• vite.config.ts is updated to use these files.
• .gitignore is updated to ignore .ssl/ (but maybe keep the folder structure).

Story 3: Trust the Root CA

As a developer I want instructions to trust the Caddy Root CA on my host machine So that browsers accept the connection

Acceptance Criteria:

• README.md is updated with specific instructions for Linux (and other OSs if applicable) to trust the .ssl/root.crt.
• Example for Linux: sudo cp .ssl/root.crt /usr/local/share/ca-certificates/caddy-local.crt && sudo update-ca-certificates.

Technical Specifications

Certificate Generation (Caddy Native)

Instead of openssl, we use caddy itself.

1. Trigger Generation:

   docker exec -d f414de049d3c caddy respond --listen :8443 --domain localhost "SSL Init"
   

   • respond: Simple command to serve a static response.
   • --listen :8443: Avoids conflict with the main Caddy process on 80/443.
   • --domain localhost: Tells Caddy to manage certificates for this domain.
   • -d: Run in detached mode (background).

2. Wait & Verify: Wait a few seconds, then check:

   docker exec f414de049d3c ls -l /data/caddy/certificates/local/localhost/
   

3. Cleanup: Kill the temporary process (if it doesn't exit, though respond might run forever).

   docker exec f414de049d3c pkill -f "caddy respond"
   

File Locations

• Container Paths:
  • Cert: /data/caddy/certificates/local/localhost/localhost.crt
  • Key: /data/caddy/certificates/local/localhost/localhost.key
  • Root CA: /data/caddy/pki/authorities/local/root.crt
• Host Destination: ./.ssl/

Vite Config

Update vite.config.ts:

https: {
    key: fs.readFileSync('./.ssl/localhost.key'),
    cert: fs.readFileSync('./.ssl/localhost.crt') // Note: Caddy uses .crt extension by default
}