Skip to content

Commit bcf95c1

Browse files
authored
docs: add network hosting and reverse proxy troubleshooting (@isma-021) (#7970)
### Description I noticed that when trying to host Monkeytype over a local network or the internet instead of `localhost`, the frontend crashes with an `Uncaught TypeError: crypto.randomUUID is not a function` error. This happens because modern browsers restrict this API to secure contexts (HTTPS). When putting a reverse proxy in front to handle HTTPS, it's very easy to run into Mixed Content blocks or 404 errors due to incorrect `.env` configurations (like adding a trailing slash to `MONKEYTYPE_FRONTENDURL` or forgetting to completely recreate the containers). This PR updates `SELF_HOSTING.md` to: - Explain the HTTPS requirement for network deployments. - Detail how to properly configure the backend URL in the `.env` file to avoid API 404 errors (the trailing slash issue). - Highlight the importance of using `docker compose up -d --force-recreate` and clearing the browser cache, since environment variables are baked into the SPA static files at startup. ### Checks - [X] Make sure the PR title follows the Conventional Commits standard. (https://www.conventionalcommits.org for more info) - [X] Make sure to include your GitHub username prefixed with @ inside parentheses at the end of the PR title.
1 parent 0cb7f6b commit bcf95c1

1 file changed

Lines changed: 25 additions & 0 deletions

File tree

docs/SELF_HOSTING.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
- [Table of contents](#table-of-contents)
1111
- [Prerequisites](#prerequisites)
1212
- [Quickstart](#quickstart)
13+
- [Hosting over the network (HTTPS)](#hosting-over-the-network-https)
1314
- [Account System](#account-system)
1415
- [Setup Firebase](#setup-firebase)
1516
- [Update backend configuration](#update-backend-configuration)
@@ -36,6 +37,30 @@
3637
- run `docker compose up -d`
3738
- after the command exits successfully you can access [http://localhost:8080](http://localhost:8080)
3839

40+
### Hosting over the network (HTTPS)
41+
42+
If you plan to access your self-hosted Monkeytype instance over a local network or the internet (not using `localhost`), **you must serve it over HTTPS**. Modern browsers restrict key web features, such as `crypto.randomUUID`, to secure contexts. Accessing the site via HTTP over a network will cause the frontend to crash with errors like `Uncaught TypeError: crypto.randomUUID is not a function`.
43+
44+
To solve this, you need to place a reverse proxy (like Nginx, Caddy, or Traefik) in front of your containers to handle HTTPS/TLS termination.
45+
46+
#### Troubleshooting Frontend Connection Issues
47+
48+
If your reverse proxy is up but you see errors like `Looks like the server is experiencing unexpected down time` or network errors when fetching resources, your frontend is likely trying to communicate with the backend over unsecure HTTP, causing a **Mixed Content** block in the browser.
49+
50+
Ensure you configure the frontend to talk to your secure backend URL by following these rules in your `.env` file:
51+
52+
1. **Update the frontend and backend URL:** Set `MONKEYTYPE_FRONTENDURL` and `MONKEYTYPE_BACKENDURL` to your full HTTPS backend domain.
53+
2. **Do not include a trailing slash:** Ensure the URL does not end with a `/` (e.g., use `https://api.yourdomain.com`, **not** `https://api.yourdomain.com/`). A trailing slash will cause `404 Not Found` errors due to double slashes in the API calls (like `//configuration`).
54+
3. **Force container recreation:** Monkeytype is a Single Page Application (SPA), meaning environment variables are baked into the static JavaScript files during startup. If you change your `.env`, you must completely recreate the container for the changes to apply:
55+
56+
```bash
57+
docker compose up -d --force-recreate
58+
```
59+
60+
> [!TIP]
61+
> After updating your configuration and recreating the containers, clear your browser cache or perform a hard reload (Ctrl + F5) to make sure your browser isn't running an old cached version of the frontend.
62+
63+
3964
## Account System
4065

4166
By default, user sign-up and login are disabled. To enable this, you'll need to set up a Firebase project.

0 commit comments

Comments
 (0)