Skip to content

Commit

Permalink
docs: add a Docker Compose example, improve the first experience (#465)
Browse files Browse the repository at this point in the history
  • Loading branch information
@dunglas
dunglas committed Feb 12, 2021
1 parent 975bef3 commit 0846bbe
Show file tree
Hide file tree
Showing 2 changed files with 88 additions and 31 deletions.
33 changes: 21 additions & 12 deletions docs/hub/config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,15 @@ route {
```

Caddy will automatically generate a Let's Encrypt TLS certificate automatically for you! So you can use HTTPS.
To disable HTTPS entirely, explicitly set a different port than `443`:

```Caddyfile
:80, my-domain.test:3000
route {
# ...
}
```

## Directives

Expand All @@ -43,7 +52,7 @@ The following Mercure-specific directives are available:
| `transport_url <url>` | URL representation of the transport to use. Use `local://local` to disabled history, (example `bolt:///var/run/mercure.db?size=100&cleanup_frequency=0.4`), see also [the cluster mode](cluster.md) | `bolt://mercure.db` |
| `dispatch_timeout <duration>` | maximum duration of the dispatch of a single update, set to `0s` disable | `5s` |
| `write_timeout <duration>` | maximum duration before closing the connection, set to `0s` disable | `600s` |
| `demo [<assets-path>]` | enable the demo mode and the UI | |
| `demo [<assets-path>]` | enable the debug UI and expose demo endpoints | |
| `cache <num-counters> <max-cost>` | cache configuration (see [Ristretto's docs](https://github.com/dgraph-io/ristretto)), set to -1 to disable the cache | `6e7` `1e8` (100MB) |

See also [the list of built-in Caddyfile directives](https://caddyserver.com/docs/caddyfile/directives).
Expand All @@ -52,17 +61,17 @@ See also [the list of built-in Caddyfile directives](https://caddyserver.com/doc

The provided `Caddyfile` and the Docker image provide convenient environment variables:

| Environment variable | Description | Default value |
|------------------------------|----------------------------------------------------------------------|---------------------|
| `DEBUG=debug` | enable the debug mode | |
| `SERVER_NAME` | the server name or address | `localhost` |
| `MERCURE_TRANSPORT_URL` | the value passed to the `transport_url` directive | `bolt://mercure.db` |
| `MERCURE_PUBLISHER_JWT_KEY` | the JWT key to use for publishers | |
| `MERCURE_PUBLISHER_JWT_ALG` | the JWT algorithm to use for publishers | `HS256` |
| `MERCURE_SUBSCRIBER_JWT_KEY` | the JWT key to use for subscribers | |
| `MERCURE_SUBSCRIBER_JWT_ALG` | the JWT algorithm to use for subscribers | `HS256` |
| `MERCURE_EXTRA_DIRECTIVES` | a list of extra Mercure directives to pass, one per line | |
| `MERCURE_LICENSE` | the license to use ([only applicable for the HA version](cluster.md) | |
| Environment variable | Description | Default value |
|------------------------------|------------------------------------------------------------------------------------|---------------------|
| `DEBUG=debug` | enable the debug mode | |
| `SERVER_NAME` | the server name or address, set it to `:80` (or use another port) to disable HTTPS | `localhost` |
| `MERCURE_TRANSPORT_URL` | the value passed to the `transport_url` directive | `bolt://mercure.db` |
| `MERCURE_PUBLISHER_JWT_KEY` | the JWT key to use for publishers | |
| `MERCURE_PUBLISHER_JWT_ALG` | the JWT algorithm to use for publishers | `HS256` |
| `MERCURE_SUBSCRIBER_JWT_KEY` | the JWT key to use for subscribers | |
| `MERCURE_SUBSCRIBER_JWT_ALG` | the JWT algorithm to use for subscribers | `HS256` |
| `MERCURE_EXTRA_DIRECTIVES` | a list of extra Mercure directives to pass, one per line | |
| `MERCURE_LICENSE` | the license to use ([only applicable for the HA version](cluster.md) | |

## JWT Verification

Expand Down
86 changes: 67 additions & 19 deletions docs/hub/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ The Mercure.rocks hub is available as a custom build of the [Caddy web server](h

First, download the archive corresponding to your operating system and architecture [from the release page](https://github.com/dunglas/mercure/releases), extract the archive and open a shell in the resulting directory.

Note: Mac OS users must use the `Darwin` binary.
*Note:* Mac OS users must use the `Darwin` binary.

Then, on Linux and Mac OS X, run:
Then, to start the Mercure.rocks Hub in development mode on Linux and Mac OS X, run:

MERCURE_PUBLISHER_JWT_KEY='!ChangeMe!' \
MERCURE_SUBSCRIBER_JWT_KEY='!ChangeMe!' \
Expand All @@ -22,39 +22,35 @@ On Windows, start PowerShell, go into the extracted directory and run:

$env:MERCURE_PUBLISHER_JWT_KEY='!ChangeMe!'; $env:MERCURE_SUBSCRIBER_JWT_KEY='!ChangeMe!'; .\mercure.exe run -config Caddyfile.dev

The Windows Defender Firewall will ask you if you want to allow `mercure.exe` to communicate through it.
*Note:* The Windows Defender Firewall will ask you if you want to allow `mercure.exe` to communicate through it.
Allow it for both public and private networks. If you use an antivirus, or another firewall software, be sure to whitelist `mercure.exe`.

The server is now available on `https://localhost`, with the demo mode enabled. Because the `allow_anonymous` directive is set in the provided configuration, anonymous subscribers are allowed.
The server is now available on `https://localhost` (TLS is automatically enabled, [learn how to disable it](config.md)).
In development mode, anonymous subscribers are allowed and the debug UI is available on `https://localhost/.well-known/mercure/ui/`.

To run the server in production, run this command:
*Note:* if you get an error similar to `bind: address already in use`, it means that the port `80` or `443` is already used by another service (the usual suspects are Apache and NGINX). Before starting Mercure, stop the service using the port(s) first, or set the `SERVER_NAME` environment variable to use a free port (ex: `SERVER_NAME=:3000`).

To run the server in production mode, run this command:

MERCURE_PUBLISHER_JWT_KEY='!ChangeMe!' \
MERCURE_SUBSCRIBER_JWT_KEY='!ChangeMe!' \
./mercure run

[Learn how to configure the Mercure.rocks hub](config.md).
In production mode, the debugger UI is disabled and anonymous subscribers aren't allowed.
To change these default settings, [learn how to configure the Mercure.rocks hub](config.md).

When the server is up and running, the following endpoints are available:

* `POST https://example.com/.well-known/mercure`: to publish updates
* `GET https://example.com/.well-known/mercure`: to subscribe to updates

In demo mode, an UI is also available: `https://example.com/.well-known/mercure/ui/`.
* `POST https://localhost/.well-known/mercure`: to publish updates
* `GET https://localhost/.well-known/mercure`: to subscribe to updates

See [the protocol](../../spec/mercure.md) for more details about these endpoints.

To compile the development version, see [https://github.com/dunglas/mercure/blob/master/CONTRIBUTING.md](https://github.com/dunglas/mercure/blob/main/CONTRIBUTING.md).

## Custom Caddy Build

It's also possible to build your own binaries containing other [Caddy modules](https://caddyserver.com/download) using [`xcaddy`](https://github.com/caddyserver/xcaddy).

xcaddy build --with github.com/dunglas/mercure/caddy

## Docker Image

A Docker image is available on Docker Hub. The following command is enough to get a working server in demo mode:
A Docker image is available on Docker Hub. The following command is enough to get a working server in development mode:

docker run \
-e MERCURE_PUBLISHER_JWT_KEY='!ChangeMe!' \
Expand All @@ -63,7 +59,7 @@ A Docker image is available on Docker Hub. The following command is enough to ge
-p 443:443 \
dunglas/mercure caddy run -config /etc/caddy/Caddyfile.dev

The server, in demo mode, is available on `https://localhost`. Anonymous subscribers are allowed.
The server is then available on `https://localhost`. Anonymous subscribers are allowed and the debugger UI is available on `https://localhost/.well-known/mercure/ui/`.

In production, simply run:

Expand All @@ -74,13 +70,65 @@ In production, simply run:
-p 443:443 \
dunglas/mercure

The Docker image is based on the Caddy server Docker image.
HTTPS support is automatically enabled. If you run the Mercure hub behind a reverse proxy [such as NGINX](cookbooks.md#using-nginx-as-an-http-2-reverse-proxy-in-front-of-the-hub), you usually want to use unencrypted HTTP.
This can be done like that:

docker run \
-e SERVER_NAME=':80' \
-e MERCURE_PUBLISHER_JWT_KEY='!ChangeMe!' \
-e MERCURE_SUBSCRIBER_JWT_KEY='!ChangeMe!' \
-p 80:80 \
dunglas/mercure

The Docker image is based on [the Caddy Server Docker image](https://registry.hub.docker.com/_/caddy).
See [the configuration section](config.md) and [the documentation of the Docker image for Caddy](https://registry.hub.docker.com/_/caddy) to learn how to configure it to fit your needs.

## Docker Compose

If you prefer to use `docker-compose` to run the Mercure.rocks hub, here's a sample service definition:

```yaml
# docker-compose.yml
version: "3.7"

services:
caddy:
image: dunglas/mercure
restart: unless-stopped
environment:
# Uncomment the following line to disable HTTPS
#SERVER_NAME: ':80'
MERCURE_PUBLISHER_JWT_KEY: '!ChangeMe!'
MERCURE_SUBSCRIBER_JWT_KEY: '!ChangeMe!'
# Uncomment the following line to enable the development mode
#command: /usr/bin/caddy run -config /etc/caddy/Caddyfile.dev
ports:
- "80:80"
- "443:443"
volumes:
- caddy_data:/data
- caddy_config:/config

volumes:
caddy_data:
caddy_config:
```

## Arch Linux

Mercure.rocks is available [on the AUR](https://aur.archlinux.org/packages/mercure), you can install it with your favorite AUR wrapper:

yay -S mercure

Or download the `PKGBUILD` and compile and install it: `makepkg -sri`.

## Custom Caddy Build

It's also possible to [download Caddy with Mercure and other modules included](https://caddyserver.com/download?package=github.com%2Fdunglas%2Fmercure%2Fcaddy), or to build your own binaries using [`xcaddy`](https://github.com/caddyserver/xcaddy):

xcaddy build --with github.com/dunglas/mercure/caddy

## Integrations in Popular Frameworks

The Mercure.rocks is shipped by [several popular services and frameworks](../ecosystem/awesome.md#frameworks-and-services-integrations), including Symfony and API Platform.
Refer to their documentations to get started.

0 comments on commit 0846bbe

Please sign in to comment.