Skip to content

Commit

Permalink
doc(readme): update docker informations
Browse files Browse the repository at this point in the history 
	Adds more details about the available configuration variables
and how to fire up a working local environment.

Signed-off-by: Pierre 'McFly' Marty <[email protected]>
  • Loading branch information
@pm-McFly
pm-McFly committed Jan 27, 2025
1 parent ef00214 commit 8f560f6
Show file tree
Hide file tree
Showing 4 changed files with 184 additions and 156 deletions.
38 changes: 0 additions & 38 deletions DOCKER-VARIABLES.md
View file

This file was deleted.

122 changes: 10 additions & 112 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,6 @@
<img src="https://github.com/artembru/ToM-server/assets/146178981/4a5da817-466f-4d4a-8804-3881b672bc42">
</a>




<p align="center">
<a href="https://twake-chat.com">Website</a>
•
Expand Down Expand Up @@ -38,47 +35,7 @@ Here is the architecture principle:

REST API Endpoints documentation is available on https://linagora.github.io/ToM-server/

[Try it with docker](#twake-chat-docker)

## Development

The local instance will be started using `docker.localhost` as root domain. Please make sure that your hosts file contains:

```conf
127.0.0.1 docker.localhost auth.docker.localhost matrix.docker.localhost tom.docker.localhost
```

```bash
# pushd .compose/ssl/
# mkcert -install
# mkcert docker.localhost *.docker.localhost
# cat docker.localhost+1.pem docker.localhost+1-key.pem > both.pem
# popd

pushd .compose/
echo -e "TZ=$(timedatectl show | grep -Poh '(?<=^Timezone=).*')\nUID=$(id -u)\nGID=$(id -g)" > .env

## OR - manual edition
# cp .env.template .env
# $EDITOR .env
popd

pushd .compose/lemon
./init-db.sh # Creates a user 'dwho' with pass 'dwho'

## Add a new user
# defaults -> ./create-user.sh 'dwho' 'Doctor Who' 'dwho'
# ./create-user.sh 'nickname' 'givenname' 'password'
popd

docker-compose up # -d
# docker compose up # -d
```

## Scripts

* `npm run build`: build all packages
* `npm run test`: test all packages
[Try it with docker](./docker.md)

## Modules

Expand All @@ -99,74 +56,15 @@ docker-compose up # -d
[Matrix specification](https://spec.matrix.org/latest/server-server-api/#server-discovery)
* [@twake/retry-promise](packages/retry-promise): simple module extending javascript Promise with retry strategy

## Twake-Chat docker

This repository provides different docker images. The main is [Tom Server](./Dockerfile) itself. Here are its environment variables:

* Required:
* `BASE_URL`: Public URL
* Database:
* `DATABASE_ENGINE` _(`pg` or `sqlite`)_
* `DATABASE_HOST` _(path for `sqlite`)_
* `DATABASE_NAME`
* `DATABASE_USER`
* `DATABASE_PASSWORD`
* `DATABASE_SSL`
* `OIDC_ISSUER`: URL of SSO server
* LDAP service:
* `LDAP_BASE`
* `LDAP_FILTER`
* `LDAP_USER`
* `LDAP_PASSWORD`
* `LDAP_URI`
* Matrix server:
* `SERVER_NAME` _(same value than in Matrix's homeserver.yaml)_
* `MATRIX_SERVER` _(real Matrix server)_
* `TEMPLATE_DIR` _(default: `node_modules/@twake/server/templates`)_
* Recommended:
* `ADDITIONAL_FEATURES`: set true to have all search features; false for a public instance
* Cron service:
* `CRON_SERVICE` _(default: true)_: enable cron tasks
* `PEPPER_CRON` _(default: `9 1 * * *`)_
* `UPDATE_USERS_CRON` _(default: `*/15 * * * *`)_
* `UPDATE_FEDERATED_IDENTITY_HASHES_CRON` _(default: `3 3 * * *`)_
* Logs:
* `LOG_TRANSPORTS`: set to `Console`
* `LOG_LEVEL`: default to "error", possible values: "error", "warn", "info", "http", "verbose", "debug", "silly"
* `TRUSTED_PROXIES`: IP list of server allowed to set `X-Frowarded-For` header
* Rate limits _(see [express-rate-limit](https://www.npmjs.com/package/express-rate-limit))_:
* `RATE_LIMITING_WINDOW`
* `RATE_LIMITING_NB_REQUESTS`
* Optional:
* `FEDERATED_IDENTITY_SERVICES`: list of federated identity services
* Use a CrowdSec service:
* `CROWDSEC_URI`
* `CROWDSEC_KEY`
* Add Jitsi into metadata:
* `JITSI_BASE_URL`
* `JITSI_JWT_ALGORITHM`
* `JITSI_JWT_ISSUER`
* `JITSI_SECRET`
* `JITSI_PREFERRED_DOMAIN`
* `JITSI_USE_JWT`
* Matrix database _(for automatic channels)_:
* `MATRIX_DATABASE_ENGINE`
* `MATRIX_DATABASE_HOST`
* `MATRIX_DATABASE_NAME`
* `MATRIX_DATABASE_PASSWORD`
* `MATRIX_DATABASE_SSL`
* `MATRIX_DATABASE_USER`
* Opensearch features:
* `OPENSEARCH_CA_CERT_PATH`
* `OPENSEARCH_HOST`
* `OPENSEARCH_IS_ACTIVATED`
* `OPENSEARCH_MAX_RETRIES`
* `OPENSEARCH_NUMBER_OF_SHARDS`
* `OPENSEARCH_NUMBER_OF_REPLICAS`
* `OPENSEARCH_PASSWORD`
* `OPENSEARCH_SSL`
* `OPENSEARCH_USER`
* `OPENSEARCH_WAIT_FOR_ACTIVE_SHARDS`
## Requirements

- [ ] Node >=18

## Commands

* `npm run build`: build all packages
* `npm run test`: test all packages
* `node ./server.mjs`: run the server

## Copyright and license

Expand Down
2 changes: 1 addition & 1 deletion docker-compose.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ services:
- OIDC_ISSUER=https://auth.docker.localhost

Check notice

Code scanning / devskim

Accessing localhost could indicate debug code, or could hinder scaling. Note

Do not leave debug code in production
- SERVER_NAME=docker.localhost

Check notice

Code scanning / devskim

Accessing localhost could indicate debug code, or could hinder scaling. Note

Do not leave debug code in production
- USERDB_ENGINE=sqlite
- LOG_LEVEL=debug
- LOG_LEVEL=silly
- LOG_TRANSPORTS=Console
- TEMPLATE_DIR=/usr/src/app/packages/tom-server/templates
- TRUSTED_PROXIES=uniquelocal
Expand Down
178 changes: 173 additions & 5 deletions docker.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,116 @@
# Use Tawe-on-Matrix server with docker
# Serve Tawe-on-Matrix as a container

Image are published in docker hub:
* [The ToM Server itself](https://hub.docker.com/r/linagora/tom-server)
* [The Federated Identity Service](https://hub.docker.com/r/linagora/tom-federated-identity-service)

## The ToM server image
- [The ToM Server itself](https://hub.docker.com/r/linagora/tom-server)
- [The Federated Identity Service](https://hub.docker.com/r/linagora/tom-federated-identity-service)

### Synopsis
## ToM Variables

| Status | Description |
| ------------ | ------------------------------------------------------------ |
| **required** | Server cannot starts without |
| recommended | Server can start without, but we advise to use it |
| *optional* | Use it to turn on specific features, depending to your needs |

---

Set of variables used to configure ToM features and behavior.

| Name | Description | Default | Status |
| --------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------- | ------------ |
| `BASE_URL` | Public URL. `https://tom.example.com` | `none` | **required** |
| `DATABASE_ENGINE` | The Database engine to use *(`pg` for PostgreSQL or `sqlite`)* | `none` | **required** |
| `DATABASE_HOST` | `pg`: URL to connect to, `sqlite`: path to the .db file | `none` | **required** |
| `DATABASE_NAME` | Name of the databse to use *(for `pg` only)* | `none` | **required** |
| `DATABASE_USER` | User that will connect to the database *(for `pg` only)* | `none` | **required** |
| `DATABASE_PASSWORD` | User's password *(for `pg` only)* | `none` | **required** |
| `DATABASE_SSL` | Wether or not to use SSL for db connection *(for `pg` only)* | `false` | **required** |
| `OIDC_ISSUER` | URL of SSO server | `none` | **required** |
| `LDAP_BASE` | Example: `dc=example,dc=com` | `none` | recommended |
| `LDAP_FILTER` | Example: `(objectClass=person)` | `none` | recommended |
| `LDAP_USER` | full LDAP `dn` used to connect | `none` | recommended |
| `LDAP_PASSWORD` | Password corresponding to the `dn` | `none` | recommended |
| `LDAP_URI` | URL of the LDAP directory, e.g. `ldaps://ldap.company.com` | `none` | recommended |
| `TEMPLATE_DIR` | Path to folder containing mail templates | `node_modules/@twake/server/templates` | recommended |
| `RATE_LIMITING_WINDOW` | How long to remember requests for, in milliseconds. | `600000` | recommended |
| `RATE_LIMITING_NB_REQUESTS` | How many requests to allow. | `100` | recommended |
| `ADDITIONAL_FEATURES` | Set true to have all search features | `false` | recommended |
| `FEDERATED_IDENTITY_SERVICES` | List of federated identity services | `[]` | recommended |
| `CRON_SERVICE` | Enable cron tasks | `false` | *optional* |
| `PEPPER_CRON` | When should the pepper (i.e hash salt) be updated *(cron syntax)* | `9 1 * * *` | *optional* |
| `UPDATE_USERS_CRON` | When should the users data be refreshed *(cron syntax)* | `*/10 * * * *` | *optional* |
| `UPDATE_FEDERATED_IDENTITY_HASHES_CRON` | When should the users hashed data should be sent to federation server *(cron syntax)* | `*/10 * * * *` | *optional* |
| `USERDB_ENGINE` | The database engine used to store user data. *(`ldap` or `sqlite`)* | `ldap` | *optional* |
| `LOG_TRANSPORTS` | | `Console` | *optional* |
| `LOG_LEVEL` | Possible values: `error`, `warn`, `info`, `http`, `verbose`, `debug`, `silly` | `Console` | *optional* |
| `TRUSTED_PROXIES` | IP list of server allowed to set `X-Frowarded-For` header | `[]` | *optional* |

### Matrix

Configure the interconnection of ToM and a Matrix server.

| Name | Description | Default | Status |
| -------------------------- | ------------------------------------------------------------------------------------------- | -------- | ------------ |
| `SERVER_NAME` | same value than in Matrix's homeserver.yaml | `none` | **required** |
| `MATRIX_SERVER` | Example: `matrix.company.com` | `none` | **required** |
| `MATRIX_DATABASE_ENGINE` | The Database engine used by the Matrix server *(`pg` for PostgreSQL or `sqlite`)* | `none` | *optional* |
| `MATRIX_DATABASE_HOST` | `pg`: URL to connect to the Matrix PGSQL instance, `sqlite`: path to the homeserver.db file | `none` | *optional* |
| `MATRIX_DATABASE_NAME` | Name of the databse to use *(for `pg` only)* | `none` | *optional* |
| `MATRIX_DATABASE_USER` | User that will connect to the database *(for `pg` only)* | `none` | *optional* |
| `MATRIX_DATABASE_PASSWORD` | User's password *(for `pg` only)* | `none` | *optional* |
| `MATRIX_DATABASE_SSL` | Wether or not to use SSL for db connection *(for `pg` only)* | `false` | *optional* |

### Jitsi

Tells ToM to also add Jitsi metadata to the `.well-known`.

| Name | Description | Default | Status |
| ------------------------ | ----------- | -------- | ---------- |
| `JITSI_BASE_URL` | | `none` | *optional* |
| `JITSI_JWT_ALGORITHM` | | `none` | *optional* |
| `JITSI_JWT_ISSUER` | | `none` | *optional* |
| `JITSI_SECRET` | | `none` | *optional* |
| `JITSI_PREFERRED_DOMAIN` | | `none` | *optional* |
| `JITSI_USE_JWT` | | `false` | *optional* |

### Crowdsec

To secure your installation with [the help of the crowd](https://github.com/crowdsecurity/crowdsec).

| Name | Description | Default | Status |
| -------------- | --------------------------------- | ------- | ---------- |
| `CROWDSEC_URI` | API URI to use | `none` | *optional* |
| `CROWDSEC_KEY` | The secret key for authentication | `none` | *optional* |

### OpenSearch

| Name | Description | Default | Status |
| ----------------------------------- | ------------------------------------------ | ------- | ---------- |
| `OPENSEARCH_IS_ACTIVATED` | Enable or not the OpenSearch integration | `false` | *optional* |
| `OPENSEARCH_HOST` | URI of the OpenSearch instance | `none` | *optional* |
| `OPENSEARCH_MAX_RETRIES` | | `none` | *optional* |
| `OPENSEARCH_NUMBER_OF_SHARDS` | | `none` | *optional* |
| `OPENSEARCH_NUMBER_OF_REPLICAS` | | `none` | *optional* |
| `OPENSEARCH_USER` | The user that connects to OpenSearch | `none` | *optional* |
| `OPENSEARCH_PASSWORD` | | `none` | *optional* |
| `OPENSEARCH_WAIT_FOR_ACTIVE_SHARDS` | Must ToM wait for active shards | `none` | *optional* |
| `OPENSEARCH_SSL` | Wether to use SSL to connect to OpenSearch | `false` | *optional* |
| `OPENSEARCH_CA_CERT_PATH` | Path of the CA to use for SSL termination | `none` | *optional* |

## Use the ToM Image

The ToM server is made to be configured with environment variables, allowing a
fast, easy and flexible configuration - especially for container deployments.

To make the server fits your needs, simply add/remove the corresponding
variables. Though, please note that some remain required. One can use [the
table above](#tom-variables) detailling all available vars.

In the following example, ToM is deployed with its additional features, on the
'example.com' domain, using a PostgreSQL instance for it's own database
storage, another is used for storing Synpase data, and an LDAP directory is
used to store user information (such as nickname, auth credentials, or email):

```shell
$ docker run -d -p 3000:3000 \
Expand Down Expand Up @@ -36,3 +140,67 @@ $ docker run -d -p 3000:3000 \
-e RATE_LIMITING_WINDOW=10
-e RATE_LIMITING_NB_REQUESTS=100
linagora/tom-server
```

## Start a Lightweight Local Environment

To facilitate your debuts we provide a [`docker-compose.yml`](./docker-compose.yml)
featuring a complete environment to run and try ToM.

This environment uses `docker.localhost` as default domain, and stores its
rootCA in [`./.compose/ssl/`](./.compose/ssl/). Feel free to use another domain,
but remember to update the configurations (in the `.compose` folder)
accordingly.

### `/etc/hosts`

```conf
127.0.0.1 docker.localhost # base domain
127.0.0.1 auth.docker.localhost # SSO
127.0.0.1 matrix.docker.localhost # matrix server
127.0.0.1 tom.docker.localhost # tom server
127.0.0.1 chat.docker.localhost # matrix client (Twake Chat)
```

### Kickstart

```bash
## Uncomment the following to create your own certificate
# pushd .compose/ssl/
# mkcert -install
# mkcert docker.localhost *.docker.localhost
# cat docker.localhost+1.pem docker.localhost+1-key.pem > both.pem
# popd

## Add your Timezone, UID and GID to the synapse container
pushd .compose/
echo "TZ=$(timedatectl show | grep -Poh '(?<=^Timezone=).*')" | tee .env
echo "UID=$(id -u)" | tee -a .env
echo "GID=$(id -g)" | tee -a .env

## OR - manual edition
# cp .env.template .env
# $EDITOR .env
popd

## Initialize LemonLDAP::NG (SSO) database
pushd .compose/lemon
./init-db.sh

## Add more users
# ./create-user.sh 'nickname' 'givenname' 'password'
popd

## Fire up!
docker-compose up # -d
# docker compose up # -d
```

### Default users

| Name | Nickname | Password |
| ------------- | -------- | -------- |
| Doctor Who | dwho | dwho |
| R. Tyler | rtyler | rtyler |
| Jar Jar Binks | jbinks | jbinks |

0 comments on commit 8f560f6

Please sign in to comment.