Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,16 @@ about how to read this document in [CONTRIBUTING.md](/CONTRIBUTING.md).

## Unreleased

### Added

- `web`: `MOUSEHOLE_BASE_PATH` serves the whole app — UI and API — under a URL
path prefix such as `/mousehole`, so Mousehole can share a hostname with other
apps behind a reverse proxy. Redirects, the UI's base URL, and the session
cookie's scope all follow the prefix, and the bundle is built with relative
asset URLs with the deployment's base written into the document the server
serves, so one build works at the origin root and under any prefix. See
[Hosting Under a Subpath](/docs/hosting-under-a-subpath.md).

### Fixed

- `config`: `MOUSEHOLE_INSECURE_ALLOW_NO_AUTH` is now exclusive with
Expand Down
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,6 @@ COPY src ./src
COPY --from=build-web ${BUN_BUILD_DIR}/dist ./dist

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD bun -e "process.exit((await fetch('http://localhost:5010/health')).ok ? 0 : 1)"
CMD bun -e "const base = (process.env.MOUSEHOLE_BASE_PATH ?? '').trim().replace(/^\\/+|\\/+$/g, ''); const url = ['http://localhost:5010', base, 'health'].filter(Boolean).join('/'); process.exit((await fetch(url)).ok ? 0 : 1)"

CMD ["bun", "run", "src/index.ts"]
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,9 @@ The Dockerfile includes a default healthcheck that hits the
service is live, and therefore, it is suitable for use in container
orchestration.

If you set `MOUSEHOLE_BASE_PATH`, the healthcheck probes `<base>/health`
instead, read from the environment at run time.

If you change the port on which Mousehole listens with the `MOUSEHOLE_PORT`
environment variable, make sure to override the
[healthcheck command](/Dockerfile) accordingly.
Expand Down Expand Up @@ -137,6 +140,9 @@ You can trigger an immediate update from the web UI with **Update Now**.
- `MOUSEHOLE_ALLOWED_ORIGINS`: Comma-separated allowlist of `Origin` header
values. Defaults to same-origin only. See
[Origin Allowlist](/docs/security-guide.md#origin-allowlist).
- Sharing one hostname with other apps? To serve Mousehole under a subpath such
as `https://host/mousehole/`, see
[Hosting Under a Subpath](/docs/hosting-under-a-subpath.md).

### Other tuning

Expand Down Expand Up @@ -168,6 +174,9 @@ You can trigger an immediate update from the web UI with **Update Now**.
[Session Duration](/docs/security-guide.md#session-duration).
- `MOUSEHOLE_STATE_DIR_PATH`: _(Default `/var/lib/mousehole`)_ The directory
where the service will store its internal data.
- `MOUSEHOLE_BASE_PATH`: _(Default unset: the origin root)_ Serve the whole app
under this URL path prefix, e.g. `/mousehole`. See
[Hosting Under a Subpath](/docs/hosting-under-a-subpath.md).

### Docker Secrets

Expand Down
8 changes: 8 additions & 0 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

Mousehole provides an API for programmatic access to its functionality.

Endpoint paths below are relative to Mousehole's mount point: `/state` at the
origin root, and `/mousehole/state` when
[`MOUSEHOLE_BASE_PATH`](/docs/hosting-under-a-subpath.md) is `/mousehole`.

## Authentication

Protected endpoints accept a Bearer token. Set the `MOUSEHOLE_AUTH_TOKEN`
Expand All @@ -18,6 +22,10 @@ Example with curl:
curl -H "Authorization: Bearer mytoken" http://localhost:5010/state
```

Behind a reverse proxy serving Mousehole under a prefix, the URL is
`http://host/mousehole/state` (see
[Hosting Under a Subpath](/docs/hosting-under-a-subpath.md)).

A request with a missing or invalid credential is rejected with `401` and a
`WWW-Authenticate` header (see [Errors](#errors)).

Expand Down
121 changes: 121 additions & 0 deletions docs/hosting-under-a-subpath.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# Hosting Under a Subpath

By default Mousehole serves its web UI and API at the origin root
(`http://host:5010/web/`). If Mousehole shares a hostname with other apps behind
a reverse proxy, you'll want it reachable at a subpath such as
`https://host/mousehole/` instead.

There is one way to arrange that: keep the prefix in the request. The proxy
forwards `/mousehole/...` unchanged and you set
`MOUSEHOLE_BASE_PATH=/mousehole`.

The whole app moves together: UI at `<prefix>/web/`, API at
`<prefix>/{login,logout,updates,state,cookie,events,health}`, and `<prefix>`
redirects into the app. A trailing slash is optional throughout: `/mousehole`
and `/mousehole/` answer alike, and so do `/mousehole/web` and
`/mousehole/web/`.

## Setting `MOUSEHOLE_BASE_PATH`

Set `MOUSEHOLE_BASE_PATH` to the path prefix:

```yaml
environment:
MOUSEHOLE_BASE_PATH: "/mousehole"
```

Then:

| Root deployment | With `MOUSEHOLE_BASE_PATH=/mousehole` |
| ------------------------- | ------------------------------------- |
| `http://host:5010/` | `http://host:5010/mousehole` |
| `http://host:5010/web/` | `http://host:5010/mousehole/web/` |
| `http://host:5010/health` | `http://host:5010/mousehole/health` |
| `http://host:5010/state` | `http://host:5010/mousehole/state` |

The value is normalised: surrounding whitespace and trailing slashes are
dropped and a leading slash is added, so `mousehole/`, `/mousehole` and
`/mousehole` all name the same prefix.

A value that isn't a plain URL path stops Mousehole at startup with a message
naming `MOUSEHOLE_BASE_PATH`. Each segment may contain only letters, digits and
`-._~`: no scheme or host, no `//`, no `.` or `..` segment, and no whitespace,
`?`, `#`, backslash, `;`, `:`, `%`, or non-ASCII.

The session cookie's `Path` is set to the prefix, so the browser only sends the
session to Mousehole, not to the other apps on the hostname.

[`MOUSEHOLE_ALLOWED_HOSTS`](/docs/security-guide.md#host-allowlist) and
[`MOUSEHOLE_ALLOWED_ORIGINS`](/docs/security-guide.md#origin-allowlist) stay
host-only, never a path.

## Reverse proxy examples

Each example forwards the path unchanged, which is what
`MOUSEHOLE_BASE_PATH=/mousehole` expects: every route is registered under the
prefix, so a proxy that strips it before forwarding asks for paths the app does
not serve.

### nginx

No trailing slash on `proxy_pass`: that would strip `/mousehole`.

```nginx
location = /mousehole {
return 302 /mousehole/;
}

location /mousehole/ {
proxy_pass http://127.0.0.1:5010;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
# Server-Sent Events (GET /mousehole/events) stream until the client leaves.
proxy_buffering off;
}
```

### Caddy

```caddyfile
:8080 {
redir /mousehole /mousehole/
handle /mousehole/* {
reverse_proxy 127.0.0.1:5010 {
# Server-Sent Events (GET /mousehole/events) stream until the client leaves.
flush_interval -1
}
}
}
```

`handle_path` would strip the prefix, so use `handle` and browse
`http://localhost:8080/mousehole/web/`.

### Traefik

No `stripPrefix` middleware: the router's `PathPrefix` rule forwards the path
as-is.

```yaml
http:
routers:
mousehole:
rule: PathPrefix(`/mousehole`)
service: mousehole
services:
mousehole:
loadBalancer:
servers:
- url: "http://127.0.0.1:5010"
```

## Docker healthcheck

The image's built-in healthcheck reads `MOUSEHOLE_BASE_PATH` at run time and
probes `<prefix>/health`, so it keeps working under a prefix. If you override
`MOUSEHOLE_PORT`, override the [healthcheck](/README.md#healthcheck) to match.

## Development

`bun dev` serves the UI through Vite at `/web/` and does not simulate a prefix,
so verify a prefixed deployment against a built image behind your proxy.
13 changes: 11 additions & 2 deletions docs/security-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,12 @@ environment:
MOUSEHOLE_ALLOWED_ORIGINS: "http://localhost:5010,http://127.0.0.1:5010,https://mousehole.myhomelab.lan"
```

If Mousehole is reachable at a subpath such as `https://host/mousehole/` rather
than the origin root, see
[Hosting Under a Subpath](/docs/hosting-under-a-subpath.md). A base path never
enters either allowlist: both stay host-only (scheme + host + optional port, no
path).

### Backwards Compatibility Mode

Before v0.4.0, Mousehole had no authentication nor Host/Origin checks. To
Expand Down Expand Up @@ -164,7 +170,9 @@ attacks.
This list is set using the `MOUSEHOLE_ALLOWED_HOSTS` environment variable.
Separate multiple values with commas. Valid values are hostnames or IP
addresses, with optional ports. If a port is provided, _only_ that port is
allowed for that host. Without a port, _any_ port is allowed for that host.
allowed for that host. Without a port, _any_ port is allowed for that host. A
value carries no path, regardless of any
[base path](/docs/hosting-under-a-subpath.md) Mousehole is served under.

The default is `localhost,127.0.0.1,[::1]`.

Expand Down Expand Up @@ -203,7 +211,8 @@ Tightening this down prevents

This list is set using the `MOUSEHOLE_ALLOWED_ORIGINS` environment variable.
Separate multiple values with commas. Valid values are full origins: scheme,
host, and optional port, no path.
host, and optional port, no path (including any
[base path](/docs/hosting-under-a-subpath.md) Mousehole is served under).

The default policy is
[same-origin](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Same-origin_policy):
Expand Down
Loading