Caddy-in-dev troubleshooting doc / could we support HTTP2 out of the box?

[thruflo]

I just wanted to do a pass on this updated section of https://electric-sql.com/docs/guides/troubleshooting#solution-mdash-run-caddy and am raising an issue for us to discuss before doing.

I hopped back into this doc as a user on the weekend because I was getting slow shapes and I knew I needed to run Caddy to solve.

One detail is that I needed to run caddy start first before I could run caddy trust. I then needed to think about stopping caddy to follow the example command. I was then confused by the https aspect. Should I be using http://localhost:3001 or https://localhost:3001 I wondered. How is that working etc.?

Then I generally found myself with one more terminal tab open. Which is a minor annoyance but they all add up.

---

My thoughts / questions here are:

1. @samwillis with current docs, could we eyeball them together for 5 mins and I'll push a PR with some wording tweaks
2. is there no solution here that could work with Docker? I.e.: could we not package something in the Electric docker image so that it supports HTTP2?

I see e.g.: https://github.com/stephenlb/http2-proxy -- is it out of date / did things change? Is it a certificate issue with the local browser? I'm guessing from the current wording it is. If so, could we use the caddy trust dance to get the cert in there but still run Caddy in Electric? Then have an env var to enable Caddy proxying in dev?

[samwillis]

is there no solution here that could work with Docker

It is possible to run Caddy, or any other HTTP2 server in Docker, however the issue that arrises is around the https certificate. The browsers in their wisdom decided that HTTP2 would only be enabled with SSL, while technology not required, and so you have to run a https server to get http2. That then means you either need to have a self signed cert, and click though the "warning, this isn't a valid certificate warning" or install a root certiface on your OS so that your self signed cert doesn't trigger the warning.

Caddy in a Docker container will not have installed it root certificate and so the user will have to manually trust the certificate it's using.

This is then further complicated by the fact many users will have a separate dev server for their shape proxy (such as a hono dev server) from whatever they are using for front end development (say Vite). If the "invalid" self signed https certificate is only used from a fetch call inside the Electric client, the user is never presented with the "warning .... click here to trust" message.

It's the installing of that self signed root certificate that Caddy does (both automatically and when running caddy trust) that makes this all "Just work".

[thruflo]

Got it, thanks!

Still though, can the Caddy-we-put-in-docker not use the same root CA that caddy trust installs?

Then the workflow is “caddy trust once then set env var ongoing” rather than “caddy trust once and always run separate process”.

[samwillis]

We should try!

[xamgore]

To not overcomplicate things during development, couldn't we just use Vite? It's the number 1 tool for each frontend developer. Example config vite.config.ts:

export default defineConfig(() => ({
  plugins: [
    basicSsl({
      name: 'dev environment',
      domains: ['localhost', '127.0.0.1'],
      certDir: resolve(__dirname),
    }),
  ],
  server: {
    allowedHosts: ['localhost'],
    https: {
      // same as in the basicSsl plugin configuration upwards
      cert: resolve(__dirname, '_cert.pem'),
    },
    proxy: {
      '/v1/shape': {
        target: 'http://127.0.0.1:3000',
        changeOrigin: true,
      },
    }
  }
}))

It was not possible to use https with proxy. With v7.2.0 being published it's possible. See the PR for more details.

[KyleAMathews]

@xamgore what caddy gives is self-generated certs that just work — vite requires you to create your own cert which is far far harder than just using caddy.

[xamgore]

Caddy is a nice web server, which is perfectly fit for production environments.

Speaking about developer experience Vite is the absolute winner in frontend realm. The landing page explains that clearly why: hot module replacement, plugins for React/Vue/... based developmet, great UX.

In my personal experience, Vite has the easiest way to configure self-signed certificates.

You just do npm install @vitejs/plugin-basic-ssl and set up the config, like where to put the certificate files, in case you want to approve them on the system/browser level. I have put an example just in case. The plugin probably has some defaults, but I decided to set them up for clarity.