Debian Codegraph @

distrib/docker/README.md

raw
1 # Ergo Docker
2
3 This folder holds Ergo's Docker compose file. The Dockerfile is in the root
4 directory. Ergo is published automatically to the GitHub Container Registry at
5 [ghcr.io/ergochat/ergo](https://ghcr.io/ergochat/ergo).
6
7 Most users should use either the `stable` tag (corresponding to the
8 `stable` branch in git, which tracks the latest stable release), or
9 a tag corresponding to a tagged version (e.g. `v2.8.0`). The `master`
10 tag corresponds to the `master` branch, which is not recommended for
11 production use. The `latest` tag is not recommended.
12
13 ## Quick start
14
15 The Ergo docker image is designed to work out of the box - it comes with a
16 usable default config and will automatically generate self-signed TLS
17 certificates. To get a working ircd, all you need to do is run the image and
18 expose the ports:
19
20 ```shell
21 docker run --init --name ergo -d -p 6667:6667 -p 6697:6697 ghcr.io/ergochat/ergo:stable
22 ```
23
24 This will start Ergo and listen on ports 6667 (plain text) and 6697 (TLS).
25 The first time Ergo runs it will create a config file with a randomised
26 oper password. This is output to stdout, and you can view it with the docker
27 logs command:
28
29 ```shell
30 # Assuming your container is named `ergo`; use `docker container ls` to
31 # find the name if you're not sure.
32 docker logs ergo
33 ```
34
35 You should see a line similar to:
36
37 ```
38 Oper username:password is admin:cnn2tm9TP3GeI4vLaEMS
39 ```
40
41 We recommend the use of `--init` (`init: true` in docker-compose) to solve an
42 edge case involving unreaped zombie processes when Ergo's script API is used
43 for authentication or IP validation. For more details, see
44 [krallin/tini#8](https://github.com/krallin/tini/issues/8).
45
46 ## Persisting data
47
48 Ergo has a persistent data store, used to keep account details, channel
49 registrations, and so on. To persist this data across restarts, you can mount
50 a volume at /ircd.
51
52 For example, to create a new docker volume and then mount it:
53
54 ```shell
55 docker volume create ergo-data
56 docker run --init --name ergo -d -v ergo-data:/ircd -p 6667:6667 -p 6697:6697 ghcr.io/ergochat/ergo:stable
57 ```
58
59 Or to mount a folder from your host machine:
60
61 ```shell
62 mkdir ergo-data
63 docker run --init --name ergo -d -v $(pwd)/ergo-data:/ircd -p 6667:6667 -p 6697:6697 ghcr.io/ergochat/ergo:stable
64 ```
65
66 ## Customising the config
67
68 Ergo's config file is stored at /ircd/ircd.yaml. If the file does not
69 exist, the default config will be written out. You can copy the config from
70 the container, edit it, and then copy it back:
71
72 ```shell
73 # Assuming that your container is named `ergo`, as above.
74 docker cp ergo:/ircd/ircd.yaml .
75 vim ircd.yaml # edit the config to your liking
76 docker cp ircd.yaml ergo:/ircd/ircd.yaml
77 ```
78
79 You can use the `/rehash` command to make Ergo reload its config, or
80 send it the HUP signal:
81
82 ```shell
83 docker kill -s SIGHUP ergo
84 ```
85
86 ## Using custom TLS certificates
87
88 TLS certs will by default be read from /ircd/fullchain.pem, with a private key
89 in /ircd/privkey.pem. You can customise this path in the ircd.yaml file if
90 you wish to mount the certificates from another volume. For information
91 on using Let's Encrypt certificates, see
92 [this manual entry](https://github.com/ergochat/ergo/blob/master/docs/MANUAL.md#using-valid-tls-certificates).
93
94 ## Using docker-compose
95
96 This folder contains a sample docker-compose file which can be used
97 to start an Ergo instance with ports exposed and data persisted in
98 a docker volume. Simply download the file and then bring it up:
99
100 ```shell
101 curl -O https://raw.githubusercontent.com/ergochat/ergo/master/distrib/docker/docker-compose.yml
102 docker-compose up -d
103 ```
104
105 ## Building
106
107 If you wish to manually build the docker image, you need to do so from
108 the root of the Ergo repository (not the `distrib/docker` directory):
109
110 ```shell
111 docker build .
112 ```
113