diff --git a/Makefile b/Makefile index 78a8438..5300386 100644 --- a/Makefile +++ b/Makefile @@ -39,6 +39,7 @@ whitelabel-check: install ## Build with example overrides and grep for brand le BRAND_COMPANY='Acme Inc.' \ BRAND_CLI=acme \ BRAND_PRODUCT_SLUG=acme \ + BRAND_PACKAGE_PATH_NAME=acme \ BRAND_IMAGE=acme/documentserver \ BRAND_URL=https://acme.example \ BRAND_REPO=https://github.com/acme \ diff --git a/brand.yml b/brand.yml index 13e4507..4536def 100644 --- a/brand.yml +++ b/brand.yml @@ -4,7 +4,8 @@ # 1. Edit the values below, OR # 2. Set the matching BRAND_* environment variables at build time: # BRAND_NAME, BRAND_SHORT_NAME, BRAND_TAGLINE, BRAND_COMPANY, -# BRAND_PRODUCT_SLUG, BRAND_CLI, BRAND_URL, BRAND_REPO, BRAND_DOCS_URL +# BRAND_PRODUCT_SLUG, BRAND_PACKAGE_PATH_NAME, BRAND_CLI, BRAND_URL, +# BRAND_REPO, BRAND_DOCS_URL # 3. Replace docs/assets/logo.svg and docs/assets/favicon.svg with your own. # 4. Override theme colors via BRAND_PRIMARY_COLOR / BRAND_ACCENT_COLOR # (any Material palette name: indigo, deep purple, teal, blue, etc.). @@ -18,6 +19,10 @@ brand: tagline: Your sovereign office company: Euro-Office product_slug: eurooffice + # On-disk/package namespace used in install paths (/etc, /var/log, /var/www, + # /var/lib), the package/artifact name, and example container names. + # Branded builds differ here, e.g. nextcloud-office. + package_path_name: euro-office cli: eurooffice image: ghcr.io/euro-office/documentserver url: https://euro-office.com diff --git a/docs/configuration/commands.md b/docs/configuration/commands.md new file mode 100644 index 0000000..5eaab59 --- /dev/null +++ b/docs/configuration/commands.md @@ -0,0 +1,70 @@ +# Command-line Tools + +Euro-Office Document Server ships a set of `documentserver-*` helper scripts for +administration. On a package install they are on the `PATH` (in `/usr/bin`) and +run as root: + +```bash +sudo documentserver-jwt-status.sh +``` + +In Docker, run them inside the container: + +```bash +docker exec {{ brand.package_path_name }} documentserver-jwt-status.sh +``` + +## Available commands + +| Command | Purpose | +|---|---| +| `documentserver-configure.sh` | Configure the database, message broker, Redis, JWT, and port. Package install only | +| `documentserver-jwt-status.sh` | Print the current JWT enabled state, secret, and header | +| `documentserver-generate-allfonts.sh` | Regenerate the font cache. See [Custom fonts](fonts.md) | +| `documentserver-pluginsmanager.sh` | Install and update editor plugins. See [Installing plugins](plugins.md) | +| `documentserver-flush-cache.sh` | Bump the cache tag so browsers reload editor assets | +| `documentserver-update-securelink.sh` | Set or rotate the nginx secure-link secret | +| `documentserver-static-gzip.sh` | Pre-compress static assets and enable nginx `gzip_static` | +| `documentserver-prepare4shutdown.sh` | Drain the server before a graceful shutdown or restart | +| `documentserver-letsencrypt.sh` | Obtain and configure a Let's Encrypt certificate | + +## Common tasks + +**Check JWT configuration** — confirm whether token validation is on and which secret is in use: + +```bash +sudo documentserver-jwt-status.sh +``` + +**Configure connections** (package install) — point the server at external services: + +```bash +sudo documentserver-configure.sh \ + --databasetype postgres \ + --databasehost db.internal \ + --databasename eurooffice \ + --databaseuser eurooffice \ + --databasepassword your-password \ + --jwtsecret at-least-32-chars-long-for-hs256 +``` + +Run `documentserver-configure.sh --help` to see all options. The package +supports `postgres`, `mariadb`, and `mysql`. + +**Issue a TLS certificate** — pass the contact email and domain: + +```bash +sudo documentserver-letsencrypt.sh admin@example.com docs.example.com +``` + +**Rotate the secure-link secret** — omit the value to generate a random one: + +```bash +sudo documentserver-update-securelink.sh --secure_link_secret a-random-secret-for-nginx-secure-link +``` + +**Drain before maintenance** — stop accepting new editing sessions before restarting: + +```bash +sudo documentserver-prepare4shutdown.sh +``` diff --git a/docs/configuration/fonts.md b/docs/configuration/fonts.md new file mode 100644 index 0000000..485bd69 --- /dev/null +++ b/docs/configuration/fonts.md @@ -0,0 +1,42 @@ +# Installing Custom Fonts + +Euro-Office Document Server ships with a built-in font set. To make additional fonts available in the editors, add them to the server and regenerate the font cache. + +Supported formats: TrueType (`.ttf`, `.tte`), OpenType (`.otf`, `.otc`, `.ttc`), and Web Open Font Format (`.woff`, `.woff2`). + +## Bare-metal (deb/rpm) + +1. Copy your font files to `/usr/share/fonts/`: + + ```bash + sudo cp myfont.ttf /usr/share/fonts/ + ``` + +2. Regenerate the font cache: + + ```bash + sudo documentserver-generate-allfonts.sh + ``` + +The new fonts appear in the editor font list. No restart is required. + +## Docker + +Mount a host directory with your fonts into the container and let it regenerate the cache on startup: + +```bash +docker run -d \ + --name {{ brand.package_path_name }} \ + --restart=unless-stopped \ + -p 80:80 \ + -e JWT_ENABLED=true \ + -e JWT_SECRET=at-least-32-chars-long-for-hs256 \ + -v /path/on/your/host/fonts:/usr/share/fonts/custom \ + ghcr.io/euro-office/documentserver:latest +``` + +Fonts are picked up automatically because `GENERATE_FONTS` is enabled by default. To add fonts to a running container, drop the files into the host directory and restart it: + +```bash +docker restart {{ brand.package_path_name }} +``` diff --git a/docs/configuration/logging.md b/docs/configuration/logging.md new file mode 100644 index 0000000..906cfb5 --- /dev/null +++ b/docs/configuration/logging.md @@ -0,0 +1,79 @@ +# Logging + +Euro-Office Document Server uses [log4js](https://log4js-node.github.io/log4js-node/) +for its server-side logs. You control how much is logged with the log level, and +read the output from per-service log files. + +## Log level + +The level is set in the log4js config: + +``` +/etc/{{ brand.package_path_name }}/documentserver/log4js/production.json +``` + +Change `categories.default.level` (default `WARN`) to one of the log4js levels, +from least to most verbose: + +``` +OFF · FATAL · ERROR · WARN · INFO · DEBUG · TRACE +``` + +```json +{ + "categories": { + "default": { "appenders": ["default"], "level": "DEBUG" } + } +} +``` + +### Package install (deb/rpm) + +Edit `production.json`, then restart the services to apply: + +```bash +sudo systemctl restart ds-docservice ds-converter ds-metrics +``` + +### Docker + +Do not edit the file by hand. Set the log level with an environment variable and +recreate the container; the entrypoint writes it into `production.json`: + +```bash +docker run -d \ + --name {{ brand.package_path_name }} \ + --restart=unless-stopped \ + -p 80:80 \ + -e DS_LOG_LEVEL=DEBUG \ + ghcr.io/euro-office/documentserver:latest +``` + +!!! warning + `DEBUG` and `TRACE` are verbose. Use them to diagnose a problem, then set the + level back to `WARN` for normal operation. + +## Log files + +Logs are written per service under `/var/log/{{ brand.package_path_name }}/documentserver/`: + +| File | Component | +|---|---| +| `docservice/out.log`, `docservice/err.log` | DocService (collaboration server) | +| `converter/out.log` | FileConverter (document conversion) | +| `metrics/out.log` | Metrics | +| `adminpanel/out.log` | Admin panel | +| `nginx.access.log` | nginx access log | + +### Viewing logs in Docker + +The application logs are written to the files above inside the container, not to +`docker logs`. Tail them directly: + +```bash +docker exec {{ brand.package_path_name }} tail -f /var/log/{{ brand.package_path_name }}/documentserver/docservice/out.log +``` + +To keep logs on the host, mount the log directory as a volume +(`-v /path/to/logs:/var/log/{{ brand.package_path_name }}/documentserver`) as shown in the +[Docker installation guide](../installation/docker.md#persistent-data). diff --git a/docs/configuration/plugins.md b/docs/configuration/plugins.md new file mode 100644 index 0000000..0fbcb6e --- /dev/null +++ b/docs/configuration/plugins.md @@ -0,0 +1,115 @@ +# Installing Plugins + +Plugins extend the editors with extra panels and tools. Once installed on the +server, a plugin is available to all users of that document server. This guide +applies to self-hosted Euro-Office installations. + +Plugins live in the `sdkjs-plugins` directory of the document server: + +``` +/var/www/{{ brand.package_path_name }}/documentserver/sdkjs-plugins/ +``` + +## Finding plugins + +!!! note "No app directory yet" + + Euro-Office does not yet have an in-product app directory for browsing and + installing plugins. Until then, install plugins manually as described below. + For a curated list of plugins known to work with Euro-Office, see + [Plugins](../integration/plugins.md). + +Because Euro-Office is a fork of ONLYOFFICE, plugins built for the ONLYOFFICE +editors are generally compatible. Each plugin is a folder containing a +`config.json` manifest and its assets. The upstream plugins are maintained +together in one repository, with each plugin under +[`sdkjs-plugins/content`](https://github.com/ONLYOFFICE/onlyoffice.github.io/tree/master/sdkjs-plugins/content) +(`wordscounter`, `thesaurus`, `translator`, and others). Before installing, +check that the plugin supports your editor version. + +## Package install (deb/rpm) + +1. Get the plugin folder you want. Since the upstream plugins live in a single + repository, clone it and copy the individual plugin into the plugins + directory: + + ```bash + git clone --depth 1 https://github.com/ONLYOFFICE/onlyoffice.github.io + sudo cp -r onlyoffice.github.io/sdkjs-plugins/content/wordscounter \ + /var/www/{{ brand.package_path_name }}/documentserver/sdkjs-plugins/ + ``` + + For a plugin distributed in its own repository, clone it directly into a + folder under `sdkjs-plugins/` instead. + +2. Register it and reload the editors: + + ```bash + sudo documentserver-pluginsmanager.sh + ``` + + This fixes file ownership, restarts the document service, and flushes the + editor cache so the plugin appears. + +## Docker + +Mount the plugin from the host so it survives container recreation. Clone the +plugin folder to a directory on the host and bind-mount it into the document +server's `sdkjs-plugins` directory: + +```bash +git clone --depth 1 https://github.com/ONLYOFFICE/onlyoffice.github.io +cp -r onlyoffice.github.io/sdkjs-plugins/content/wordscounter \ + /path/on/your/host/plugins/wordscounter +``` + +```bash +docker run -d \ + --name {{ brand.package_path_name }} \ + --restart=unless-stopped \ + -p 80:80 \ + -e JWT_ENABLED=true \ + -e JWT_SECRET=at-least-32-chars-long-for-hs256 \ + -v /path/on/your/host/plugins/wordscounter:/var/www/{{ brand.package_path_name }}/documentserver/sdkjs-plugins/wordscounter \ + ghcr.io/euro-office/documentserver:latest +``` + +Mount each plugin into its own subdirectory under `sdkjs-plugins/` rather than +mounting over the whole directory, which would hide the built-in plugins. After +starting the container, register the plugin so the editors pick it up: + +```bash +docker exec {{ brand.package_path_name }} documentserver-pluginsmanager.sh +``` + +!!! tip + Mounting keeps the plugin on the host, so it persists when the container is + recreated. You only need to re-run the register command after recreating the + container. + +## Per-user plugins from the editor + +The above installs a plugin server-wide for every user. The editors also include +a built-in **Plugins** tab with a plugin manager, where individual users can add +plugins for their own session without server access. This is useful for testing +a plugin before deploying it for everyone. + +## Removing a plugin + +Remove the plugin's folder and re-register so the editors stop loading it. + +=== "Package install" + + ```bash + sudo rm -rf /var/www/{{ brand.package_path_name }}/documentserver/sdkjs-plugins/wordscounter + sudo documentserver-pluginsmanager.sh + ``` + +=== "Docker" + + Remove the `-v` mount for the plugin and recreate the container, then delete + the plugin folder from the host: + + ```bash + rm -rf /path/on/your/host/plugins/wordscounter + ``` diff --git a/docs/configuration/server.md b/docs/configuration/server.md new file mode 100644 index 0000000..30e38e8 --- /dev/null +++ b/docs/configuration/server.md @@ -0,0 +1,139 @@ +# Server Configuration + +Euro-Office Document Server is configured in one of two ways depending on how it +was installed: + +- **Package install (deb/rpm)** — edit a JSON config file on disk. +- **Docker** — set environment variables; the container writes the config file for you on startup. + +Both end up writing the same file: `local.json`. + +## The configuration file + +Settings live in `/etc/{{ brand.package_path_name }}/documentserver/`, loaded in this order, with +later files overriding earlier ones: + +``` +default.json → production-linux.json → local.json +``` + +!!! warning + Do not edit `default.json` or `production-linux.json`. They are replaced on + upgrade. Put all of your changes in `local.json`. + +Create `local.json` next to `default.json` and include only the keys you are +changing, keeping the full nested structure. For example, to set the JWT secret +and point at an external PostgreSQL database: + +```json +{ + "services": { + "CoAuthoring": { + "secret": { + "inbox": { "string": "at-least-32-chars-long-for-hs256" }, + "outbox": { "string": "at-least-32-chars-long-for-hs256" }, + "session": { "string": "at-least-32-chars-long-for-hs256" } + }, + "sql": { + "type": "postgres", + "dbHost": "db.internal", + "dbName": "eurooffice", + "dbUser": "eurooffice", + "dbPass": "your-password" + } + } + } +} +``` + +The JWT secret must be at least **32 characters** long. This is required by the +HS256 signing algorithm used by the document server and the Nextcloud integration. +A secret shorter than 32 characters will be rejected when signing or verifying +tokens. Generate a suitable secret with: + +```bash +openssl rand -hex 32 +``` + +Restart the server to apply changes: + +```bash +sudo supervisorctl restart all +``` + +## Common settings + +| Setting | Key path in `local.json` | +|---|---| +| JWT enabled (incoming) | `services.CoAuthoring.token.enable.browser`, `…token.enable.request.inbox` | +| JWT enabled (outgoing) | `services.CoAuthoring.token.enable.request.outbox` | +| JWT secret | `services.CoAuthoring.secret.{inbox,outbox,session}.string` | +| JWT header / in-body | `services.CoAuthoring.token.inbox.header`, `…token.inbox.inBody` | +| Database | `services.CoAuthoring.sql.{type,dbHost,dbPort,dbName,dbUser,dbPass}` | +| Redis | `services.CoAuthoring.redis.{host,port}` | +| RabbitMQ | `rabbitmq.url` | +| WOPI | `wopi.enable` | +| Allow private-IP requests | `services.CoAuthoring.request-filtering-agent.allowPrivateIPAddress` | + +## Docker + +In Docker you do not edit `local.json` directly. Set environment variables and +the container generates `local.json` on startup. To change a setting later, +update the variable and recreate the container. + +```bash +docker run -d \ + --name {{ brand.package_path_name }} \ + --restart=unless-stopped \ + -p 80:80 \ + -e JWT_SECRET=at-least-32-chars-long-for-hs256 \ + -e DB_TYPE=postgres \ + -e DB_HOST=db.internal \ + -e DB_NAME=eurooffice \ + -e DB_USER=eurooffice \ + -e DB_PWD=your-password \ + ghcr.io/euro-office/documentserver:latest +``` + +### Environment variables + +| Variable | Default | Description | +|---|---|---| +| `JWT_ENABLED` | `true` | Enable JWT validation | +| `JWT_SECRET` | random | Shared JWT secret (see note below) | +| `JWT_SECRET_INBOX` / `JWT_SECRET_OUTBOX` | `JWT_SECRET` | Separate secrets per direction | +| `JWT_HEADER` | `Authorization` | HTTP header carrying the token | +| `JWT_IN_BODY` | `false` | Accept the token in the request body | +| `DB_TYPE` | `postgres` | Database engine. The standalone image supports `postgres` only; other engines require the cluster image | +| `DB_HOST` | `localhost` | Database host | +| `DB_PORT` | `5432` | Database port | +| `DB_NAME` | `eurooffice` | Database name | +| `DB_USER` | `eurooffice` | Database user | +| `DB_PWD` | — | Database password | +| `AMQP_HOST` | `localhost` | RabbitMQ host | +| `AMQP_PORT` | `5672` | RabbitMQ port | +| `AMQP_USER` / `AMQP_PWD` | `guest` | RabbitMQ credentials | +| `REDIS_SERVER_HOST` | `localhost` | Redis host | +| `REDIS_SERVER_PORT` | `6379` | Redis port | +| `REDIS_SERVER_PASS` | — | Redis password | +| `WOPI_ENABLED` | `false` | Enable WOPI protocol support | +| `PLUGINS_ENABLED` | `true` | Enable editor plugins | +| `METRICS_ENABLED` | `false` | Send StatsD metrics | +| `GENERATE_FONTS` | `true` | Regenerate the font cache on startup | +| `ALLOW_PRIVATE_IP_ADDRESS` | `false` | Allow fetching documents from private IPs | +| `NGINX_WORKER_PROCESSES` | `1` | Number of nginx worker processes | + +!!! note "Persisting the JWT secret" + If `JWT_SECRET` is not set, a random secret is generated on first start and + stored under `/var/www/{{ brand.package_path_name }}/Data/.private/`. Mount the `Data` + directory as a volume to keep it stable across container restarts, or set + `JWT_SECRET` explicitly. + +!!! warning "JWT secret length" + When using the Nextcloud integration, the JWT secret must be at least + **32 characters**. A shorter secret will cause token generation to fail with + "JWT secret key is too short". Generate a suitable secret with: + + ```bash + openssl rand -hex 32 + ``` diff --git a/docs/development/building.md b/docs/development/building.md index 6338fdc..b4d1d19 100644 --- a/docs/development/building.md +++ b/docs/development/building.md @@ -73,7 +73,7 @@ docker run -d \ --restart=unless-stopped \ -p 8080:80 \ -e JWT_ENABLED=true \ - -e JWT_SECRET=dev-secret \ + -e JWT_SECRET=at-least-32-chars-long-for-hs256 \ ghcr.io/euro-office/documentserver:latest ``` @@ -93,7 +93,7 @@ docker run -d \ --restart=unless-stopped \ -p 8080:80 \ -e JWT_ENABLED=true \ - -e JWT_SECRET=dev-secret \ + -e JWT_SECRET=at-least-32-chars-long-for-hs256 \ -e EXAMPLE_ENABLED=true \ ghcr.io/euro-office/documentserver:latest ``` diff --git a/docs/index.md b/docs/index.md index d191770..0ee1207 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,43 +15,44 @@ It is not a standalone application; it requires a compatible storage backend to
-- :material-rocket-launch:{ .lg .middle } **Quickstart** +- :material-book-open-variant:{ .lg .middle } **Introduction** --- - Get {{ brand.name }} running and connected to your platform in minutes. + What {{ brand.name }} is and how its pieces fit together. - [:octicons-arrow-right-24: Install with Docker](installation/docker.md) + [:octicons-arrow-right-24: Overview](introduction/overview.md) -- :material-package-down:{ .lg .middle } **Install** +- :material-package-down:{ .lg .middle } **Installation** --- - Docker, Ubuntu (deb), and Fedora (rpm) installation guides. + Production deployment via Docker, Ubuntu (deb), and Fedora (rpm). [:octicons-arrow-right-24: Installation guide](installation/index.md) -- :material-code-tags:{ .lg .middle } **Develop** +- :material-cog:{ .lg .middle } **Configuration** --- - Build {{ brand.name }} from source, run the dev environment, contribute. + Server settings, custom fonts, plugins, logging, and command-line tools. - [:octicons-arrow-right-24: Developer setup](development/setup.md) + [:octicons-arrow-right-24: Server configuration](configuration/server.md) -- :material-hammer-wrench:{ .lg .middle } **Build** +- :material-connection:{ .lg .middle } **Integration** --- - Build the Docker image and distribution packages from source. + Connecting {{ brand.name }} to Nextcloud and other DMS platforms. - [:octicons-arrow-right-24: Building from source](development/building.md) + [:octicons-arrow-right-24: Integration guide](integration/nextcloud.md) -
+- :material-code-tags:{ .lg .middle } **Development** -## What's inside + --- -- **[Introduction](introduction/overview.md)** — what {{ brand.name }} is and how its pieces fit together. -- **[Installation](installation/index.md)** — production deployment via Docker, Ubuntu (deb), and Fedora (rpm). -- **[Integration](integration/nextcloud.md)** — connecting {{ brand.name }} to Nextcloud and other DMS platforms. -- **[Development](development/building.md)** — building {{ brand.name }} from source. + Build {{ brand.name }} from source, run the dev environment, contribute. + + [:octicons-arrow-right-24: Developer setup](development/setup.md) + + diff --git a/docs/installation/debian.md b/docs/installation/debian.md index 659353e..07a0683 100644 --- a/docs/installation/debian.md +++ b/docs/installation/debian.md @@ -62,8 +62,8 @@ Download the latest release from [GitHub Releases](https://github.com/Euro-Offic ```bash # Replace and with your values, e.g. 9.3.1-rc.1 and amd64 or arm64 -wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/euro-office-documentserver__.deb" \ - -O /tmp/euro-office-documentserver.deb +wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/{{ brand.package_path_name }}-documentserver__.deb" \ + -O /tmp/{{ brand.package_path_name }}-documentserver.deb ``` **Available architectures:** `amd64`, `arm64` @@ -71,7 +71,7 @@ wget "https://github.com/Euro-Office/DocumentServer/releases/download/v ## Step 6 — Install the package ```bash -sudo apt-get install -y /tmp/euro-office-documentserver.deb +sudo apt-get install -y /tmp/{{ brand.package_path_name }}-documentserver.deb ``` The installer generates fonts, WOPI keys, and JS caches. This takes a minute. A @@ -115,15 +115,15 @@ To verify the editor works end-to-end in a browser, follow the [Example App guid Download the new release package and reinstall: ```bash -wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/euro-office-documentserver__.deb" \ - -O /tmp/euro-office-documentserver.deb -sudo apt-get install -y /tmp/euro-office-documentserver.deb +wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/{{ brand.package_path_name }}-documentserver__.deb" \ + -O /tmp/{{ brand.package_path_name }}-documentserver.deb +sudo apt-get install -y /tmp/{{ brand.package_path_name }}-documentserver.deb ``` ## Uninstalling ```bash -sudo apt-get remove --purge euro-office-documentserver +sudo apt-get remove --purge {{ brand.package_path_name }}-documentserver sudo -u postgres psql -c "DROP DATABASE ds;" sudo -u postgres psql -c "DROP USER ds;" ``` diff --git a/docs/installation/docker.md b/docs/installation/docker.md index 4a97561..8306a05 100644 --- a/docs/installation/docker.md +++ b/docs/installation/docker.md @@ -12,11 +12,11 @@ The quickest way to run Euro-Office Document Server is via the official Docker i ```bash docker run -d \ - --name euro-office \ + --name {{ brand.package_path_name }} \ --restart=unless-stopped \ -p 80:80 \ -e JWT_ENABLED=true \ - -e JWT_SECRET=your-secret \ + -e JWT_SECRET=at-least-32-chars-long-for-hs256 \ ghcr.io/euro-office/documentserver:latest ``` @@ -46,11 +46,11 @@ To test the editor in a browser, enable the built-in example app: ```bash docker run -d \ - --name euro-office \ + --name {{ brand.package_path_name }} \ --restart=unless-stopped \ -p 8080:80 \ -e JWT_ENABLED=true \ - -e JWT_SECRET=your-secret \ + -e JWT_SECRET=at-least-32-chars-long-for-hs256 \ -e EXAMPLE_ENABLED=true \ ghcr.io/euro-office/documentserver:latest ``` @@ -66,19 +66,22 @@ By default, documents and configuration are lost when the container is removed. ```bash docker run -d \ - --name euro-office \ + --name {{ brand.package_path_name }} \ --restart=unless-stopped \ -p 80:80 \ -e JWT_ENABLED=true \ - -e JWT_SECRET=your-secret \ - -v /path/to/data:/var/lib/euro-office/documentserver \ - -v /path/to/logs:/var/log/euro-office/documentserver \ - -v /path/to/config:/etc/euro-office/documentserver \ + -e JWT_SECRET=at-least-32-chars-long-for-hs256 \ + -v /path/to/data:/var/lib/{{ brand.package_path_name }}/documentserver \ + -v /path/to/logs:/var/log/{{ brand.package_path_name }}/documentserver \ + -v /path/to/config:/etc/{{ brand.package_path_name }}/documentserver \ ghcr.io/euro-office/documentserver:latest ``` ## Environment variables +The most common variables are listed below. For the full set, including the +`local.json` keys each one maps to, see [Server configuration](../configuration/server.md). + | Variable | Default | Description | |---|---|---| | `JWT_ENABLED` | `true` | Enable JWT authentication | @@ -99,14 +102,14 @@ docker run -d \ ```bash docker pull ghcr.io/euro-office/documentserver:latest -docker stop euro-office && docker rm euro-office +docker stop {{ brand.package_path_name }} && docker rm {{ brand.package_path_name }} # re-run with the same docker run command ``` ## Uninstalling ```bash -docker stop euro-office -docker rm euro-office +docker stop {{ brand.package_path_name }} +docker rm {{ brand.package_path_name }} docker rmi ghcr.io/euro-office/documentserver:latest ``` diff --git a/docs/installation/example.md b/docs/installation/example.md index d029107..189b19f 100644 --- a/docs/installation/example.md +++ b/docs/installation/example.md @@ -13,10 +13,10 @@ Expected output: `active` ## Step 2 — Configure the example app -The example app needs to know its own URL so the document server can fetch and save files correctly. Edit `/etc/euro-office/documentserver-example/local.json`: +The example app needs to know its own URL so the document server can fetch and save files correctly. Edit `/etc/{{ brand.package_path_name }}/documentserver-example/local.json`: ```bash -sudo tee /etc/euro-office/documentserver-example/local.json > /dev/null << 'EOF' +sudo tee /etc/{{ brand.package_path_name }}/documentserver-example/local.json > /dev/null << 'EOF' { "server": { "siteUrl": "/", @@ -41,7 +41,7 @@ Replace `YOUR_SERVER_IP` with the server's IP address or hostname. Do not add a === "deb install (Ubuntu)" The installer generates a JWT secret automatically. Look it up with: ```bash - sudo grep -A1 '"browser"' /etc/euro-office/documentserver/local.json | grep '"string"' + sudo grep -A1 '"browser"' /etc/{{ brand.package_path_name }}/documentserver/local.json | grep '"string"' ``` === "rpm install (Fedora)" @@ -65,14 +65,14 @@ You should see a file list. Click **Create** to open a blank document in the edi If nginx is configured to listen on a port other than 80, update two settings: -**1. nginx listen port** — edit `/etc/euro-office/documentserver/nginx/ds.conf`: +**1. nginx listen port** — edit `/etc/{{ brand.package_path_name }}/documentserver/nginx/ds.conf`: ```nginx listen 0.0.0.0:; listen [::]: default_server; ``` -**2. `exampleUrl`** — update `/etc/euro-office/documentserver-example/local.json`: +**2. `exampleUrl`** — update `/etc/{{ brand.package_path_name }}/documentserver-example/local.json`: ```json "exampleUrl": "http://YOUR_SERVER_IP:/example" diff --git a/docs/installation/fedora.md b/docs/installation/fedora.md index 53552c0..ab8bcfe 100644 --- a/docs/installation/fedora.md +++ b/docs/installation/fedora.md @@ -71,8 +71,8 @@ Download the latest RPM from [GitHub Releases](https://github.com/Euro-Office/Do ```bash # Replace with your value, e.g. 9.3.1-rc.1 -wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/euro-office-documentserver-.x86_64.rpm" \ - -O /tmp/euro-office-documentserver.rpm +wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/{{ brand.package_path_name }}-documentserver-.x86_64.rpm" \ + -O /tmp/{{ brand.package_path_name }}-documentserver.rpm ``` **Available architectures:** `x86_64`, `aarch64` @@ -82,7 +82,7 @@ wget "https://github.com/Euro-Office/DocumentServer/releases/download/v The `msttcore-fonts` package is not available in Fedora's repositories. Install with `--nodeps` to skip that dependency: ```bash -sudo rpm -ivh --nodeps /tmp/euro-office-documentserver.rpm +sudo rpm -ivh --nodeps /tmp/{{ brand.package_path_name }}-documentserver.rpm ``` ## Step 6 — Initialize the database schema @@ -143,10 +143,10 @@ Without this step the editor will fail to load with a path error like `Cannot GE ## Step 9 — Configure JWT authentication -The RPM installer does not generate a JWT configuration. Create `/etc/euro-office/documentserver/local.json` with a secret of your choice — all three entries must use the same value: +The RPM installer does not generate a JWT configuration. Create `/etc/{{ brand.package_path_name }}/documentserver/local.json` with a secret of your choice — all three entries must use the same value: ```bash -sudo tee /etc/euro-office/documentserver/local.json > /dev/null << 'EOF' +sudo tee /etc/{{ brand.package_path_name }}/documentserver/local.json > /dev/null << 'EOF' { "services": { "CoAuthoring": { @@ -214,16 +214,16 @@ To verify the editor works end-to-end in a browser, follow the [Example App guid Download the new release RPM and upgrade in place: ```bash -wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/euro-office-documentserver-.x86_64.rpm" \ - -O /tmp/euro-office-documentserver.rpm -sudo rpm -Uvh --nodeps /tmp/euro-office-documentserver.rpm +wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/{{ brand.package_path_name }}-documentserver-.x86_64.rpm" \ + -O /tmp/{{ brand.package_path_name }}-documentserver.rpm +sudo rpm -Uvh --nodeps /tmp/{{ brand.package_path_name }}-documentserver.rpm sudo /usr/bin/documentserver-flush-cache.sh ``` ## Uninstalling ```bash -sudo rpm -e euro-office-documentserver +sudo rpm -e {{ brand.package_path_name }}-documentserver sudo -u postgres psql -c "DROP DATABASE ds;" sudo -u postgres psql -c "DROP USER ds;" ``` diff --git a/docs/installation/index.md b/docs/installation/index.md index 3f9e050..a51bbbe 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -2,6 +2,15 @@ Euro-Office Document Server can be installed in several ways depending on your environment and requirements. +## Supported platforms + +| Platform | Version | Package | +|---|---|---| +| Ubuntu | 24.04 LTS | `.deb` | +| Debian | 12 (Bookworm) | `.deb` | +| Fedora | 41+ (tested on 44) | `.rpm` | +| Docker | — | Container image | + ## Choose your installation method
@@ -46,6 +55,10 @@ Once installed, use the built-in example app to confirm the editor works end-to- [:octicons-arrow-right-24: Testing with the example app](example.md) +## Running behind a reverse proxy + +For production deployments you typically place the document server behind a reverse proxy that terminates TLS and forwards requests to it. The [document-server-proxy](https://github.com/Euro-Office/document-server-proxy) project provides a ready-made reverse proxy setup you can use as a starting point. + ## Which method should I use? | | Docker | Ubuntu (deb) | Debian (deb) | Fedora (rpm) | diff --git a/docs/installation/ubuntu.md b/docs/installation/ubuntu.md index 8f5d9e0..c234ef2 100644 --- a/docs/installation/ubuntu.md +++ b/docs/installation/ubuntu.md @@ -45,8 +45,8 @@ Download the latest release from [GitHub Releases](https://github.com/Euro-Offic ```bash # Replace and with your values, e.g. 9.3.1-rc.1 and amd64 or arm64 -wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/euro-office-documentserver__.deb" \ - -O /tmp/euro-office-documentserver.deb +wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/{{ brand.package_path_name }}-documentserver__.deb" \ + -O /tmp/{{ brand.package_path_name }}-documentserver.deb ``` **Available architectures:** `amd64`, `arm64` @@ -54,7 +54,7 @@ wget "https://github.com/Euro-Office/DocumentServer/releases/download/v ## Step 5 — Install the package ```bash -sudo apt-get install -y /tmp/euro-office-documentserver.deb +sudo apt-get install -y /tmp/{{ brand.package_path_name }}-documentserver.deb ``` The installer will generate fonts, WOPI keys, and JS caches. This takes a minute. A successful install ends with: @@ -96,15 +96,15 @@ To verify the editor works end-to-end in a browser, follow the [Example App guid Download the new release package and reinstall: ```bash -wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/euro-office-documentserver__.deb" \ - -O /tmp/euro-office-documentserver.deb -sudo apt-get install -y /tmp/euro-office-documentserver.deb +wget "https://github.com/Euro-Office/DocumentServer/releases/download/v/{{ brand.package_path_name }}-documentserver__.deb" \ + -O /tmp/{{ brand.package_path_name }}-documentserver.deb +sudo apt-get install -y /tmp/{{ brand.package_path_name }}-documentserver.deb ``` ## Uninstalling ```bash -sudo apt-get remove --purge euro-office-documentserver +sudo apt-get remove --purge {{ brand.package_path_name }}-documentserver sudo -u postgres psql -c "DROP DATABASE ds;" sudo -u postgres psql -c "DROP USER ds;" ``` diff --git a/docs/integration/nextcloud.md b/docs/integration/nextcloud.md index 2d18b1d..f313d73 100644 --- a/docs/integration/nextcloud.md +++ b/docs/integration/nextcloud.md @@ -20,7 +20,7 @@ Nextcloud app that connects to a running {{ brand.name }} document server. 1. In Nextcloud, go to **Settings** → **Administration** → **{{ brand.name }}**. 2. Enter the URL of your {{ brand.name }} document server, including the protocol and port (e.g. `https://{{ brand.product_slug }}.example.com`). -3. Enter the JWT secret you configured in your document server. +3. Enter the JWT secret you configured in your document server. It must be at least **32 characters**. Generate one with `openssl rand -hex 32`. 4. Click **Save**. ## Source diff --git a/docs/integration/plugins.md b/docs/integration/plugins.md index a66c173..7637c30 100644 --- a/docs/integration/plugins.md +++ b/docs/integration/plugins.md @@ -2,7 +2,8 @@ Plugins extend the {{ brand.name }} editors with additional panels, tools, and integrations. The plugins below are currently maintained and known to work with -{{ brand.name }}. +{{ brand.name }}. For how to install one on the server, see +[Installing plugins](../configuration/plugins.md). !!! info "Plugin directory coming soon" diff --git a/main.py b/main.py index 7104f28..7dd5c7e 100644 --- a/main.py +++ b/main.py @@ -18,6 +18,7 @@ "tagline": "BRAND_TAGLINE", "company": "BRAND_COMPANY", "product_slug": "BRAND_PRODUCT_SLUG", + "package_path_name": "BRAND_PACKAGE_PATH_NAME", "cli": "BRAND_CLI", "image": "BRAND_IMAGE", "url": "BRAND_URL", diff --git a/mkdocs.yml b/mkdocs.yml index f2f3126..51bf732 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -104,6 +104,12 @@ nav: - Fedora: installation/fedora.md - Docker: installation/docker.md - Verify with Example App: installation/example.md + - Configuration: + - Server configuration: configuration/server.md + - Custom fonts: configuration/fonts.md + - Installing plugins: configuration/plugins.md + - Logging: configuration/logging.md + - Command-line tools: configuration/commands.md - Integration: - integration/index.md - Nextcloud: integration/nextcloud.md