From 7fab916fe50400ad0b1f2120b8eb3bc3fe7c5fd5 Mon Sep 17 00:00:00 2001 From: Christoph Schaefer Date: Mon, 8 Jun 2026 09:54:55 +0200 Subject: [PATCH 1/8] docs(installation): add verified Ubuntu install guide and example app docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add step-by-step Ubuntu 24.04 installation guide for the euro-office-documentserver .deb package, tested end-to-end on a clean Multipass VM. Covers prerequisites, PostgreSQL setup, debconf pre-seeding, package install, and health check. Add example app guide covering service start, JWT config, exampleUrl requirement (derived from Docker entrypoint), browser access, and non-standard port setup — all verified in-browser including port change. Add installation index page collecting all install methods, and wire all new pages into mkdocs.yml navigation. Signed-off-by: Christoph Schaefer Co-Authored-By: Claude Sonnet 4.6 --- docs/installation/example.md | 83 ++++++++++++++++++++++++++ docs/installation/index.md | 40 +++++++++++++ docs/installation/ubuntu.md | 110 +++++++++++++++++++++++++++++++++++ mkdocs.yml | 3 + 4 files changed, 236 insertions(+) create mode 100644 docs/installation/example.md create mode 100644 docs/installation/index.md create mode 100644 docs/installation/ubuntu.md diff --git a/docs/installation/example.md b/docs/installation/example.md new file mode 100644 index 0000000..1de0039 --- /dev/null +++ b/docs/installation/example.md @@ -0,0 +1,83 @@ +# Testing with the built-in example app + +Euro-Office ships a Node.js example application that lets you open and edit documents in the browser. It is intended for testing and verification only — do not expose it on a public server. + +## Step 1 — Start the example service + +```bash +sudo systemctl start ds-example +systemctl is-active ds-example +``` + +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`: + +```bash +sudo tee /etc/euro-office/documentserver-example/local.json > /dev/null << 'EOF' +{ + "server": { + "siteUrl": "/", + "exampleUrl": "http://localhost/example/", + "token": { + "enable": true, + "secret": "REPLACE_WITH_YOUR_JWT_SECRET", + "authorizationHeader": "Authorization" + } + } +} +EOF +``` + +Replace `REPLACE_WITH_YOUR_JWT_SECRET` with the JWT secret from the document server: + +```bash +sudo grep -A1 '"browser"' /etc/euro-office/documentserver/local.json | grep '"string"' +``` + +Then restart the example service: + +```bash +sudo systemctl restart ds-example +``` + +## Step 3 — Open the example in your browser + +``` +http:///example/ +``` + +You should see a file list. Click **Create** to open a blank document in the editor. + +## Running on a non-standard port + +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`: + +```nginx +listen 0.0.0.0:; +listen [::]: default_server; +``` + +**2. `exampleUrl`** — update `/etc/euro-office/documentserver-example/local.json`: + +```json +"exampleUrl": "http://localhost:/example/" +``` + +Then reload nginx and restart the example: + +```bash +sudo systemctl reload nginx +sudo systemctl restart ds-example +``` + +## Disabling the example app + +```bash +sudo systemctl stop ds-example +sudo systemctl disable ds-example +``` diff --git a/docs/installation/index.md b/docs/installation/index.md new file mode 100644 index 0000000..ad8389d --- /dev/null +++ b/docs/installation/index.md @@ -0,0 +1,40 @@ +# Installation Guide + +Euro-Office Document Server can be installed in several ways depending on your environment and requirements. + +## Choose your installation method + +
+ +- :fontawesome-brands-ubuntu: **Ubuntu (deb)** + + --- + + Install from a `.deb` package on Ubuntu 24.04 LTS. Suitable for bare-metal and VMs. + + [:octicons-arrow-right-24: Ubuntu installation](ubuntu.md) + +- :fontawesome-brands-docker: **Docker** + + --- + + Run the official container image. Recommended for production deployments. + + [:octicons-arrow-right-24: Docker installation](docker.md) + +
+ +## Verify your installation + +Once installed, use the built-in example app to confirm the editor works end-to-end in a browser. + +[:octicons-arrow-right-24: Testing with the example app](example.md) + +## Which method should I use? + +| | Docker | Ubuntu (deb) | +|---|---|---| +| Recommended for production | Yes | Yes | +| Easiest to update | Yes | | +| Full OS control | | Yes | +| Nextcloud integration | Yes | Yes | diff --git a/docs/installation/ubuntu.md b/docs/installation/ubuntu.md new file mode 100644 index 0000000..8f5d9e0 --- /dev/null +++ b/docs/installation/ubuntu.md @@ -0,0 +1,110 @@ +# Installing Euro-Office on Ubuntu + +This guide covers installing Euro-Office Document Server on Ubuntu 24.04 LTS (Noble) from a GitHub release package. + +## System requirements + +- Ubuntu 24.04 LTS (arm64 or amd64) +- 10 GB disk space minimum +- 4 GB RAM minimum + +## Step 1 — Install prerequisites + +Euro-Office requires PostgreSQL, Redis, RabbitMQ, Nginx, and Supervisor. Install them before the package: + +```bash +sudo apt-get update +sudo apt-get install -y postgresql redis-server rabbitmq-server nginx supervisor +``` + +## Step 2 — Create the database + +The post-install script connects to PostgreSQL during installation. Create the user and database first: + +```bash +sudo -u postgres psql -c "CREATE USER ds WITH PASSWORD 'ds';" +sudo -u postgres psql -c "CREATE DATABASE ds OWNER ds;" +``` + +## Step 3 — Pre-seed the installer answers + +The package installer asks for database connection details non-interactively. Pre-seed the answers so the post-install script can configure itself without a prompt: + +```bash +echo "ds ds/db-type select postgres +ds ds/db-host string localhost +ds ds/db-port string 5432 +ds ds/db-user string ds +ds ds/db-pwd password ds +ds ds/db-name string ds" | sudo debconf-set-selections +``` + +## Step 4 — Download the package + +Download the latest release from [GitHub Releases](https://github.com/Euro-Office/DocumentServer/releases): + +```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 +``` + +**Available architectures:** `amd64`, `arm64` + +## Step 5 — Install the package + +```bash +sudo apt-get install -y /tmp/euro-office-documentserver.deb +``` + +The installer will generate fonts, WOPI keys, and JS caches. This takes a minute. A successful install ends with: + +``` +Congratulations, the Euro-Office DocumentServer has been installed successfully! +``` + +## Step 6 — Verify + +Check that all services are running: + +```bash +systemctl is-active ds-docservice ds-converter ds-metrics nginx +``` + +Expected output: +``` +active +active +active +active +``` + +Run the health check: + +```bash +curl http://localhost/healthcheck +``` + +Expected output: `true` + +## Optional: Test with the built-in example app + +To verify the editor works end-to-end in a browser, follow the [Example App guide](example.md). + +## Updating + +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 +``` + +## Uninstalling + +```bash +sudo apt-get remove --purge euro-office-documentserver +sudo -u postgres psql -c "DROP DATABASE ds;" +sudo -u postgres psql -c "DROP USER ds;" +``` diff --git a/mkdocs.yml b/mkdocs.yml index 4022248..a5e7993 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -98,6 +98,9 @@ nav: - introduction/components.md - introduction/licensing.md - Installation: + - installation/index.md + - installation/ubuntu.md + - installation/example.md - installation/docker.md - Integration: - integration/nextcloud.md From 60eec27f04a54d5f7f029d4470884f9de98367bc Mon Sep 17 00:00:00 2001 From: Christoph Schaefer Date: Mon, 8 Jun 2026 09:57:39 +0200 Subject: [PATCH 2/8] chore: exclude PLAN.md from version control Signed-off-by: Christoph Schaefer Co-Authored-By: Claude Sonnet 4.6 --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index b1c314f..cc25af3 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ site/ __pycache__/ *.pyc .DS_Store +PLAN.md From 979b109a9ad30bfb52101bd40b16765e25388fd1 Mon Sep 17 00:00:00 2001 From: Christoph Schaefer Date: Mon, 8 Jun 2026 10:11:40 +0200 Subject: [PATCH 3/8] docs(installation): rewrite Docker install guide with verified steps Replace placeholder Docker doc with a tested guide covering quick start, image tags (latest/nightly/latest-dev confirmed), example app usage, persistent volumes, full environment variable reference, update, and uninstall. Tested end-to-end with ghcr.io/euro-office/documentserver:latest. Signed-off-by: Christoph Schaefer Co-Authored-By: Claude Sonnet 4.6 --- docs/installation/docker.md | 122 +++++++++++++++++++++++++++--------- docs/installation/index.md | 2 +- 2 files changed, 95 insertions(+), 29 deletions(-) diff --git a/docs/installation/docker.md b/docs/installation/docker.md index adbcadc..4a97561 100644 --- a/docs/installation/docker.md +++ b/docs/installation/docker.md @@ -1,46 +1,112 @@ -# Docker +# Installing Euro-Office via Docker -The recommended way to run {{ brand.name }} in production is via the official -Docker image, mounted with persistent volumes and fronted by a reverse proxy -that terminates TLS. +The quickest way to run Euro-Office Document Server is via the official Docker image. -## Pull and run +## Prerequisites + +- Docker Engine 20.10 or later +- 5 GB disk space for the image +- 4 GB RAM minimum + +## Quick start ```bash -docker run -d --name {{ brand.product_slug }} \ - --restart=always \ - -p 80:80 \ - -e JWT_ENABLED=true \ - -e EXAMPLE_ENABLED=true - -e JWT_SECRET=my_personal_secret \ - {{ brand.image }} +docker run -d \ + --name euro-office \ + --restart=unless-stopped \ + -p 80:80 \ + -e JWT_ENABLED=true \ + -e JWT_SECRET=your-secret \ + ghcr.io/euro-office/documentserver:latest ``` -Key flags: +The server is ready when the health check returns `true`: -- `JWT_SECRET` — the shared secret used by your DMS to sign requests. Store it somewhere durable. -- `EXAMPLE_ENABLED` — enables the example app for trying out the editor without connecting to a DMS. Don't enable in production. +```bash +curl http://localhost/healthcheck +``` ## Image tags | Tag | Use | |---|---| -| `latest` | Most recent release. Pin in production. | -| `X.Y.Z` | Specific version. | -| `develop` | Bleeding-edge builds from `main`. Not for production. | +| `latest` | Most recent release — use in production | +| `nightly` | Nightly builds from `main` — not for production | +| `latest-dev` | Development image with build tools included | + +Pin to a specific version in production: + +```bash +ghcr.io/euro-office/documentserver:9.3.1 +``` + +## Verify with the example app + +To test the editor in a browser, enable the built-in example app: + +```bash +docker run -d \ + --name euro-office \ + --restart=unless-stopped \ + -p 8080:80 \ + -e JWT_ENABLED=true \ + -e JWT_SECRET=your-secret \ + -e EXAMPLE_ENABLED=true \ + ghcr.io/euro-office/documentserver:latest +``` + +Then open `http://localhost:8080/example/` in your browser. + +!!! warning + Disable `EXAMPLE_ENABLED` in production. The example app has no access control. + +## Persistent data + +By default, documents and configuration are lost when the container is removed. Mount volumes to persist them: + +```bash +docker run -d \ + --name euro-office \ + --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 \ + ghcr.io/euro-office/documentserver:latest +``` -## TLS +## Environment variables -Terminate TLS in front of the container with a reverse proxy such as nginx -or Caddy. +| Variable | Default | Description | +|---|---|---| +| `JWT_ENABLED` | `true` | Enable JWT authentication | +| `JWT_SECRET` | — | Shared secret — set this in production | +| `JWT_HEADER` | `Authorization` | HTTP header carrying the JWT | +| `EXAMPLE_ENABLED` | `false` | Enable the built-in example app | +| `WOPI_ENABLED` | `false` | Enable WOPI protocol support | +| `ALLOW_PRIVATE_IP_ADDRESS` | `false` | Allow document server to fetch from private IPs | +| `NGINX_WORKER_PROCESSES` | `1` | Number of nginx worker processes | +| `GENERATE_FONTS` | `true` | Regenerate font cache on startup | +| `DB_HOST` | `localhost` | PostgreSQL host (for external DB) | +| `DB_NAME` | `eurooffice` | PostgreSQL database name | +| `DB_USER` | `eurooffice` | PostgreSQL user | +| `REDIS_SERVER_HOST` | `localhost` | Redis host (for external Redis) | +| `AMQP_HOST` | `localhost` | RabbitMQ host (for external RabbitMQ) | -## Configuration +## Updating -The container accepts configuration via environment variables or -by mounting a `local.json` into `/etc/{{ brand.product_slug }}/documentserver/local.json`. +```bash +docker pull ghcr.io/euro-office/documentserver:latest +docker stop euro-office && docker rm euro-office +# re-run with the same docker run command +``` -## Source +## Uninstalling -The Docker image is built from `DocumentServer/build/` in the -[DocumentServer repository]({{ brand.repo }}/DocumentServer). To build it -yourself, see [building from source](../development/building.md). +```bash +docker stop euro-office +docker rm euro-office +docker rmi ghcr.io/euro-office/documentserver:latest +``` diff --git a/docs/installation/index.md b/docs/installation/index.md index ad8389d..96badb0 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -18,7 +18,7 @@ Euro-Office Document Server can be installed in several ways depending on your e --- - Run the official container image. Recommended for production deployments. + Run the official container image. Quickest way to get started. [:octicons-arrow-right-24: Docker installation](docker.md) From ce8e8a5d592d7544d0db210282fcc9fe0e3f868f Mon Sep 17 00:00:00 2001 From: Christoph Schaefer Date: Mon, 8 Jun 2026 11:32:09 +0200 Subject: [PATCH 4/8] docs(installation): add verified Fedora 44 install guide - Add docs/installation/fedora.md: end-to-end verified steps for Fedora 41+, covering pg_hba.conf auth config, rpm --nodeps workaround for msttcore-fonts, manual DB schema init, nginx conf.d include fix, openssl + flush-cache, and manual JWT local.json creation - Document Rocky Linux 9 incompatibility (glibc 2.34 vs 2.35 required) in the Known Issues section; Rocky Linux 10 flagged as future candidate - Update example.md: tabbed JWT lookup for deb vs rpm installs; replace localhost with server IP in exampleUrl (localhost causes malformed callbacks in containers) - Update installation index: add Fedora card and extend comparison table - Add fedora.md to mkdocs.yml nav Signed-off-by: Christoph Schaefer Co-Authored-By: Claude Sonnet 4.6 --- docs/installation/example.md | 22 +++- docs/installation/fedora.md | 237 +++++++++++++++++++++++++++++++++++ docs/installation/index.md | 20 ++- mkdocs.yml | 1 + 4 files changed, 268 insertions(+), 12 deletions(-) create mode 100644 docs/installation/fedora.md diff --git a/docs/installation/example.md b/docs/installation/example.md index 1de0039..d029107 100644 --- a/docs/installation/example.md +++ b/docs/installation/example.md @@ -20,7 +20,7 @@ sudo tee /etc/euro-office/documentserver-example/local.json > /dev/null << 'EOF' { "server": { "siteUrl": "/", - "exampleUrl": "http://localhost/example/", + "exampleUrl": "http://YOUR_SERVER_IP/example", "token": { "enable": true, "secret": "REPLACE_WITH_YOUR_JWT_SECRET", @@ -31,11 +31,21 @@ sudo tee /etc/euro-office/documentserver-example/local.json > /dev/null << 'EOF' EOF ``` -Replace `REPLACE_WITH_YOUR_JWT_SECRET` with the JWT secret from the document server: +Replace `YOUR_SERVER_IP` with the server's IP address or hostname. Do not add a trailing slash. -```bash -sudo grep -A1 '"browser"' /etc/euro-office/documentserver/local.json | grep '"string"' -``` +!!! tip "localhost vs server IP" + If you are running the server directly on your local machine (not in a container or VM), you can use `http://localhost/example` as the `exampleUrl`. In all other cases — including LXD/LXC containers, VMs, and remote servers — use the actual IP address. Using `localhost` in those environments causes the document server to generate malformed callback URLs. + +**Get the JWT secret:** + +=== "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"' + ``` + +=== "rpm install (Fedora)" + Use the secret you set manually in Step 9 of the Fedora installation guide. Then restart the example service: @@ -65,7 +75,7 @@ listen [::]: default_server; **2. `exampleUrl`** — update `/etc/euro-office/documentserver-example/local.json`: ```json -"exampleUrl": "http://localhost:/example/" +"exampleUrl": "http://YOUR_SERVER_IP:/example" ``` Then reload nginx and restart the example: diff --git a/docs/installation/fedora.md b/docs/installation/fedora.md new file mode 100644 index 0000000..53552c0 --- /dev/null +++ b/docs/installation/fedora.md @@ -0,0 +1,237 @@ +# Installing Euro-Office on Fedora + +This guide covers installing Euro-Office Document Server on Fedora 41 or later from a GitHub release RPM package. + +!!! info "Tested on Fedora 44" + These steps have been verified end-to-end on Fedora 44. + Rocky Linux 9 is **not supported** due to a glibc version incompatibility — see [Known issues](#known-issues). + +## System requirements + +- Fedora 41 or later (x86_64 or aarch64) +- 10 GB disk space minimum +- 4 GB RAM minimum + +## Step 1 — Install prerequisites + +Enable the RabbitMQ packagecloud repository: + +```bash +curl -1sLf 'https://packagecloud.io/rabbitmq/rabbitmq-server/script.rpm.sh' | sudo bash +``` + +Install all prerequisites: + +```bash +sudo dnf install -y \ + postgresql-server postgresql postgresql-contrib \ + valkey \ + rabbitmq-server \ + nginx \ + supervisor +``` + +Initialize PostgreSQL, then start and enable all services: + +```bash +sudo postgresql-setup --initdb +sudo systemctl enable --now postgresql valkey rabbitmq-server nginx supervisor +``` + +## Step 2 — Configure PostgreSQL authentication + +Fedora's PostgreSQL uses `ident` authentication by default, which blocks password-based logins. Edit `/var/lib/pgsql/data/pg_hba.conf` and change `ident` to `md5` on the two `127.0.0.1` and `::1` lines: + +``` +# before +host all all 127.0.0.1/32 ident +host all all ::1/128 ident + +# after +host all all 127.0.0.1/32 md5 +host all all ::1/128 md5 +``` + +Reload PostgreSQL: + +```bash +sudo systemctl reload postgresql +``` + +## Step 3 — Create the database + +```bash +sudo -u postgres psql -c "CREATE USER ds WITH PASSWORD 'ds';" +sudo -u postgres psql -c "CREATE DATABASE ds OWNER ds;" +``` + +## Step 4 — Download the package + +Download the latest RPM from [GitHub Releases](https://github.com/Euro-Office/DocumentServer/releases): + +```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 +``` + +**Available architectures:** `x86_64`, `aarch64` + +## Step 5 — Install the package + +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 +``` + +## Step 6 — Initialize the database schema + +The RPM installer does not run the database schema automatically. Apply it manually: + +```bash +sudo -u postgres psql -d ds \ + -f /var/www/onlyoffice/documentserver/server/schema/postgresql/createdb.sql +sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO ds;" +sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO ds;" +``` + +## Step 7 — Fix the nginx configuration + +Fedora's `/etc/nginx/nginx.conf` requires two changes before the document server can serve requests. + +**1. The conf.d directory is not included.** Find this line in the `http {}` block: + +```nginx +# include /etc/nginx/conf.d/*.conf; +``` + +Uncomment it: + +```nginx +include /etc/nginx/conf.d/*.conf; +``` + +**2. A default server block intercepts port 80.** Comment out the entire `server {}` block in the same file that listens on port 80 (it starts with `listen 80;` and typically spans 15–20 lines): + +```nginx +# server { +# listen 80; +# listen [::]:80; +# server_name _; +# root /usr/share/nginx/html; +# ... +# } +``` + +Test and reload: + +```bash +sudo nginx -t && sudo systemctl reload nginx +``` + +## Step 8 — Install OpenSSL and generate JS caches + +The cache-generation script requires `openssl`, which is not installed on Fedora by default: + +```bash +sudo dnf install -y openssl +sudo /usr/bin/documentserver-flush-cache.sh +``` + +Without this step the editor will fail to load with a path error like `Cannot GET /9.3.1-/web-apps/…`. + +## 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: + +```bash +sudo tee /etc/euro-office/documentserver/local.json > /dev/null << 'EOF' +{ + "services": { + "CoAuthoring": { + "token": { + "enable": { + "request": { "inbox": true, "outbox": true }, + "browser": true + }, + "secret": { + "inbox": { "string": "REPLACE_WITH_YOUR_SECRET" }, + "outbox": { "string": "REPLACE_WITH_YOUR_SECRET" }, + "browser": { "string": "REPLACE_WITH_YOUR_SECRET" } + } + } + } + } +} +EOF +``` + +Note the secret — you will need it when configuring the example app. + +## Step 10 — Start the document server services + +```bash +sudo systemctl enable --now ds-docservice ds-converter ds-metrics +``` + +## Step 11 — Verify + +Check that all services are running: + +```bash +systemctl is-active ds-docservice ds-converter ds-metrics nginx +``` + +Expected output: + +``` +active +active +active +active +``` + +Run the health check: + +```bash +curl http://localhost/healthcheck +``` + +Expected output: `true` + +## Optional: Test with the built-in example app + +To verify the editor works end-to-end in a browser, follow the [Example App guide](example.md). + +!!! note "Use the server IP, not localhost" + When configuring the example app on Fedora, set `exampleUrl` to the server's actual IP address rather than `localhost` (e.g. `http://192.168.1.10/example`). Using `localhost` causes malformed callback URLs. + + Since you set the JWT secret manually in Step 9, skip the `grep` command and enter that same secret directly. + +## Updating + +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 +sudo /usr/bin/documentserver-flush-cache.sh +``` + +## Uninstalling + +```bash +sudo rpm -e euro-office-documentserver +sudo -u postgres psql -c "DROP DATABASE ds;" +sudo -u postgres psql -c "DROP USER ds;" +``` + +## Known issues + +### Rocky Linux 9 not supported + +The RPM package is built on Ubuntu with glibc 2.35. Rocky Linux 9 ships glibc 2.34 — one minor version behind. This causes the font and JS generation step (`AllFonts.js`) to fail silently, leaving the editor broken with no obvious error. + +Rocky Linux 10 (which ships with a newer glibc) may work once it is available. Until then, use Fedora 41+ or the [Docker installation](docker.md) instead. diff --git a/docs/installation/index.md b/docs/installation/index.md index 96badb0..bb35864 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -22,6 +22,14 @@ Euro-Office Document Server can be installed in several ways depending on your e [:octicons-arrow-right-24: Docker installation](docker.md) +- :fontawesome-brands-fedora: **Fedora (rpm)** + + --- + + Install from an `.rpm` package on Fedora 41+. Tested on Fedora 44. + + [:octicons-arrow-right-24: Fedora installation](fedora.md) + ## Verify your installation @@ -32,9 +40,9 @@ Once installed, use the built-in example app to confirm the editor works end-to- ## Which method should I use? -| | Docker | Ubuntu (deb) | -|---|---|---| -| Recommended for production | Yes | Yes | -| Easiest to update | Yes | | -| Full OS control | | Yes | -| Nextcloud integration | Yes | Yes | +| | Docker | Ubuntu (deb) | Fedora (rpm) | +|---|---|---|---| +| Recommended for production | Yes | Yes | Yes | +| Easiest to update | Yes | | | +| Full OS control | | Yes | Yes | +| Nextcloud integration | Yes | Yes | Yes | diff --git a/mkdocs.yml b/mkdocs.yml index a5e7993..e3af0d2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,6 +100,7 @@ nav: - Installation: - installation/index.md - installation/ubuntu.md + - installation/fedora.md - installation/example.md - installation/docker.md - Integration: From 8d89757a3aba1b726a035feb1d29fab8d40bafab Mon Sep 17 00:00:00 2001 From: Christoph Schaefer Date: Mon, 8 Jun 2026 12:12:49 +0200 Subject: [PATCH 5/8] docs(development): rewrite building guide with verified steps Replace the stub with end-to-end verified build instructions: - Prerequisites: Docker CE, buildx container driver setup, SSH key - Docker image build: document required BUILDX_BAKE_ENTITLEMENTS_FS=0, --allow=fs.read=.., and --load flags with explanations - Build targets reference table (standalone, develop, packages, cluster) - Version/build number overrides for both image and package builds - Package build: verified command, output layout in deploy/packages/, warning that the output directory is not cleared between runs - Troubleshooting: cache lock race condition (--set "*.cache-to="), broken cache (docker buildx prune -a) Signed-off-by: Christoph Schaefer Co-Authored-By: Claude Sonnet 4.6 --- docs/development/building.md | 161 ++++++++++++++++++++++++++++++----- 1 file changed, 142 insertions(+), 19 deletions(-) diff --git a/docs/development/building.md b/docs/development/building.md index 1b1ab99..46e2d85 100644 --- a/docs/development/building.md +++ b/docs/development/building.md @@ -1,42 +1,165 @@ # Building from source -{{ brand.name }} builds entirely inside Docker via `docker buildx bake`, so -the only host requirements are Docker + buildx and Git. +{{ brand.name }} builds entirely inside Docker via `docker buildx bake`. The only +host requirements are Docker with the buildx container driver, and Git with SSH +access to the repositories. + +## Prerequisites + +Before building for the first time, complete the one-time setup described in +[`build/BUILD_REQUISITES.md`]({{ brand.repo }}/DocumentServer/blob/main/build/BUILD_REQUISITES.md): + +- Docker CE installed (not `podman` — RHEL-based systems default to podman) +- Your build user added to the `docker` group and re-logged in +- A buildx container driver created and bootstrapped: + + ```bash + docker buildx create \ + --name container-builder \ + --driver docker-container \ + --use + + docker buildx inspect --bootstrap + ``` + +- SSH key added to your GitHub profile (for submodule access) + +## Clone the repository + +```bash +git clone --recurse-submodules git@github.com:Euro-Office/DocumentServer.git +cd DocumentServer +``` + +If you already cloned without `--recurse-submodules`: + +```bash +git submodule update --init --recursive +``` ## Build the Docker image +All build commands run from the `build/` subdirectory: + ```bash cd DocumentServer/build -docker buildx bake +BUILDX_BAKE_ENTITLEMENTS_FS=0 docker buildx bake --allow=fs.read=.. --load ``` -This produces the same image published as `{{ brand.image }}`. +This builds the `standalone` target (the default group) and loads the resulting +image into your local Docker daemon as `ghcr.io/euro-office/documentserver:latest`. + +**Why these flags:** -## Pin a version +| Flag | Reason | +|---|---| +| `BUILDX_BAKE_ENTITLEMENTS_FS=0` | Newer BuildKit versions gate filesystem access behind entitlement checks. This disables the check since the access is explicitly granted below. | +| `--allow=fs.read=..` | The build reads source files from the parent directory (`context = ".."` in `docker-bake.hcl`). BuildKit requires explicit permission for this. | +| `--load` | Imports the finished image into the local Docker daemon. Without this flag the image is built but not accessible via `docker run`. | + +Verify the image was created: ```bash -PRODUCT_VERSION=8.1.0 docker buildx bake +docker images ghcr.io/euro-office/documentserver ``` -`PRODUCT_VERSION` is stamped into the image and surfaced via `/healthcheck`. +## Build targets + +| Target / group | Command | Output | +|---|---|---| +| `standalone` (default) | `docker buildx bake` | `ghcr.io/euro-office/documentserver:latest` | +| `develop` | `docker buildx bake develop` | `ghcr.io/euro-office/documentserver:latest-dev` — includes build tools | +| `packages` | `docker buildx bake packages` | `.deb` and `.rpm` files in `build/deploy/packages/` | +| `cluster` | `docker buildx bake cluster` | Orchestrated cluster images (`cluster-docs`, `cluster-example`, `cluster-utils`) | + +## Override the version + +The version is read from the `VERSION` file at the repository root. Override it at +build time via environment variables: + +```bash +PRODUCT_VERSION=9.3.1 BUILD_NUMBER=42 \ + BUILDX_BAKE_ENTITLEMENTS_FS=0 \ + docker buildx bake --allow=fs.read=.. --load +``` + +`BUILD_NUMBER` is appended to the version string (e.g. `9.3.1-42`). It defaults +to `dev.1` when not set. ## Build distribution packages ```bash -docker buildx bake packages +cd DocumentServer/build +BUILDX_BAKE_ENTITLEMENTS_FS=0 docker buildx bake packages \ + --allow=fs.read=.. \ + --allow=fs=./deploy/packages ``` -Produces `.deb` and `.rpm` artifacts under `out/`. See -[packaging plan]({{ brand.repo }}/DocumentServer/blob/main/deb-plan.md) for -the layout these packages target. +Packages are written to `build/deploy/packages/`. Both `.deb` and `.rpm` are +produced for each architecture in a single run: -## Prerequisites +``` +deploy/packages/ + euro-office-documentserver_9.3.1-dev.1_arm64.deb + euro-office-documentserver-9.3.1-dev.1.aarch64.rpm +``` + +The `--allow=fs=./deploy/packages` flag grants BuildKit write access to that +output directory. + +!!! warning "Output directory is not cleared between runs" + The `deploy/packages/` directory accumulates packages across builds. Remove + old packages before building if you want only the current run's output: + + ```bash + rm -rf deploy/packages && mkdir -p deploy/packages + ``` + +!!! note + The `packages` target builds the full source first (same pipeline as `standalone`) + before producing the packages. Expect the same build time as a full image build + on a cold cache. + +### Override version and build number + +```bash +PRODUCT_VERSION=9.3.1 BUILD_NUMBER=42 \ + BUILDX_BAKE_ENTITLEMENTS_FS=0 \ + docker buildx bake packages \ + --allow=fs.read=.. \ + --allow=fs=./deploy/packages +``` + +This produces `euro-office-documentserver_9.3.1-42_.deb` and the equivalent `.rpm`. + +## Troubleshooting -The full prerequisite checklist (Docker user-without-root, buildx container -driver, Git SSH keys) is documented in -[`DocumentServer/build/BUILD_REQUISITES.md`]({{ brand.repo }}/DocumentServer/blob/main/build/BUILD_REQUISITES.md). -That file is the current source of truth. +### Cache layer lock errors -!!! note "Coming soon" - Migration of the BUILD_REQUISITES content into this page, plus - documentation for the `cluster` and `develop` bake groups. +When building with a warm cache, multiple targets may attempt to write the same +cache layer in parallel, producing errors like: + +``` +ERROR: (*service).Write failed: rpc error: code = Unavailable desc = ref layer-sha256:... locked +``` + +These are transient and BuildKit retries them automatically — the build completes +successfully. If the errors cause an actual build failure, disable cache writes +for that run: + +```bash +BUILDX_BAKE_ENTITLEMENTS_FS=0 docker buildx bake \ + --allow=fs.read=.. \ + --load \ + --set "*.cache-to=" +``` + +### Broken build cache + +If a build stalls or fails with errors about missing paths inside the build cache +(e.g. `cannot change to '/build-cache1/third_party/workdir/icu/icu'`), prune the +BuildKit cache and retry: + +```bash +docker buildx prune -a +``` From 9429700ef4290f42853ae94c08804e7601fe634e Mon Sep 17 00:00:00 2001 From: Christoph Schaefer Date: Mon, 8 Jun 2026 12:24:47 +0200 Subject: [PATCH 6/8] docs: add verify section to build guide and fix index links - Add "Run and verify the image" section to building.md with docker run command, healthcheck, example app, and cleanup steps - Fix index.md: Install and Development links pointed to docker.md instead of installation/index.md and building.md - Add dedicated Build card on home page so building guide is reachable without the sidebar - Fix nav titles in mkdocs.yml: explicit labels for Ubuntu, Fedora, Docker, example app, and Building from source entries Signed-off-by: Christoph Schaefer Co-Authored-By: Claude Sonnet 4.6 --- docs/development/building.md | 43 ++++++++++++++++++++++++++++++++++++ docs/index.md | 15 +++++++++---- mkdocs.yml | 10 ++++----- 3 files changed, 59 insertions(+), 9 deletions(-) diff --git a/docs/development/building.md b/docs/development/building.md index 46e2d85..b013202 100644 --- a/docs/development/building.md +++ b/docs/development/building.md @@ -63,6 +63,49 @@ Verify the image was created: docker images ghcr.io/euro-office/documentserver ``` +## Run and verify the image + +Start the locally built image: + +```bash +docker run -d \ + --name euro-office-dev \ + --restart=unless-stopped \ + -p 8080:80 \ + -e JWT_ENABLED=true \ + -e JWT_SECRET=dev-secret \ + ghcr.io/euro-office/documentserver:latest +``` + +Wait for the container to finish initialising, then check the health endpoint: + +```bash +curl http://localhost:8080/healthcheck +``` + +Expected output: `true` + +To open the built-in example app in a browser: + +```bash +docker run -d \ + --name euro-office-dev \ + --restart=unless-stopped \ + -p 8080:80 \ + -e JWT_ENABLED=true \ + -e JWT_SECRET=dev-secret \ + -e EXAMPLE_ENABLED=true \ + ghcr.io/euro-office/documentserver:latest +``` + +Then open `http://localhost:8080/example/` in your browser. + +Stop and remove the container when done: + +```bash +docker stop euro-office-dev && docker rm euro-office-dev +``` + ## Build targets | Target / group | Command | Output | diff --git a/docs/index.md b/docs/index.md index 42e0299..d191770 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,9 +27,9 @@ It is not a standalone application; it requires a compatible storage backend to --- - Docker, Docker Compose, Debian/Ubuntu, and RHEL/Fedora installation paths. + Docker, Ubuntu (deb), and Fedora (rpm) installation guides. - [:octicons-arrow-right-24: Installation guide](installation/docker.md) + [:octicons-arrow-right-24: Installation guide](installation/index.md) - :material-code-tags:{ .lg .middle } **Develop** @@ -39,12 +39,19 @@ It is not a standalone application; it requires a compatible storage backend to [:octicons-arrow-right-24: Developer setup](development/setup.md) +- :material-hammer-wrench:{ .lg .middle } **Build** + + --- + + Build the Docker image and distribution packages from source. + + [:octicons-arrow-right-24: Building from source](development/building.md) ## What's inside - **[Introduction](introduction/overview.md)** — what {{ brand.name }} is and how its pieces fit together. -- **[Installation](installation/docker.md)** — production deployment via Docker, packages, and native installs. +- **[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/setup.md)** — building {{ brand.name }} from source. +- **[Development](development/building.md)** — building {{ brand.name }} from source. diff --git a/mkdocs.yml b/mkdocs.yml index e3af0d2..99dc1f7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -99,13 +99,13 @@ nav: - introduction/licensing.md - Installation: - installation/index.md - - installation/ubuntu.md - - installation/fedora.md - - installation/example.md - - installation/docker.md + - Ubuntu: installation/ubuntu.md + - Fedora: installation/fedora.md + - Docker: installation/docker.md + - Verify with Example App: installation/example.md - Integration: - integration/nextcloud.md - Development: - development/setup.md - - development/building.md + - Building from source: development/building.md - development/contributing.md From ef8edaeba6ebcac47c8741c87fb84198d775c443 Mon Sep 17 00:00:00 2001 From: Christoph Schaefer Date: Mon, 8 Jun 2026 13:36:27 +0200 Subject: [PATCH 7/8] docs(development): document branded build with brand-icons pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add "Build a branded image" section covering the brand-server.hcl command, required --allow flags, and what changes between default and branded builds - Explain the brand-icons pipeline: SVG → PNG/ICO generation via Alpine + rsvg-convert, injection into server/example/packages stages - Document the five source SVGs in brands/nextcloud-office-brand/svg/ as the single source of truth for visual customisation - Add honest note that nextcloud-office-brand SVGs currently match the Euro-Office defaults — branded build compiles correctly but looks identical until different artwork is provided Signed-off-by: Christoph Schaefer Co-Authored-By: Claude Sonnet 4.6 --- docs/development/building.md | 61 ++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/development/building.md b/docs/development/building.md index b013202..6338fdc 100644 --- a/docs/development/building.md +++ b/docs/development/building.md @@ -106,6 +106,67 @@ Stop and remove the container when done: docker stop euro-office-dev && docker rm euro-office-dev ``` +## Build a branded image + +The default build produces a Euro-Office image. To build for a different brand +(e.g. Nextcloud Office), include the brand-specific HCL file alongside the main +bake file: + +```bash +cd DocumentServer/build +BUILDX_BAKE_ENTITLEMENTS_FS=0 docker buildx bake \ + -f docker-bake.hcl \ + -f brands/nextcloud-office-brand/brand-server.hcl \ + --allow=fs.read=.. \ + --allow=fs=./brands/nextcloud-office-brand/generated \ + --load +``` + +The additional `--allow=fs=./brands/nextcloud-office-brand/generated` flag grants +BuildKit write access to the directory where the brand asset generation step +exports its output. + +**What changes in a branded build:** + +| | Default (Euro-Office) | Branded (Nextcloud Office) | +|---|---|---| +| Image tag | `ghcr.io/euro-office/documentserver:latest` | `ghcr.io/nextcloud-office/documentserver:latest` | +| Install path inside image | `/var/www/euro-office/` | `/var/www/nextcloud-office/` | +| `COMPANY_NAME` env var | `Euro-Office` | `Nextcloud Office` | +| Visual assets | Built-in defaults | Generated from `brands/nextcloud-office-brand/svg/` | + +**How the brand asset pipeline works:** + +Including a brand HCL overrides the dummy `brand-icons` target in `docker-bake.hcl` +with a real build step. That step runs `build-icons.bake.Dockerfile` — an Alpine +container with `rsvg-convert` — which renders the five source SVGs into PNGs, ICOs, +and correctly named SVG copies for each component (server admin panel, welcome page, +example app). The generated files are written to +`brands/nextcloud-office-brand/generated/` and then injected into the `server`, +`example`, and `packages` build stages via `COPY --from=brand-icons`. + +**Customising the visual identity:** + +The visual output depends entirely on the five source SVGs in +`brands/nextcloud-office-brand/svg/`: + +``` +svg/ + logo-dark.svg # square app icon, dark theme + logo-light.svg # square app icon, light theme + logo-large-dark.svg # wide logo, dark theme + logo-large-light.svg # wide logo, light theme + splash.svg # splash screen +``` + +Replace these files with your own artwork and rebuild. Everything in `generated/` +is derived from them — do not edit the generated files directly. + +!!! note + The `nextcloud-office-brand` source SVGs currently contain the same artwork as + the Euro-Office defaults. A branded build will compile and run correctly, but + will look identical until different SVG files are placed in `svg/`. + ## Build targets | Target / group | Command | Output | From 422f235df1df6002bf6bc41f63e3e5c068e6178b Mon Sep 17 00:00:00 2001 From: Christoph Schaefer Date: Mon, 8 Jun 2026 19:26:23 +0200 Subject: [PATCH 8/8] docs(installation): add verified Debian 12 install guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add docs/installation/debian.md: verified on clean LXD container - One Debian-specific step vs Ubuntu: enable contrib component in /etc/apt/sources.list for ttf-mscorefonts-installer - All prerequisites (postgresql, redis, rabbitmq, nginx, supervisor) available in default Debian 12 repos — no extra sources needed - Example app verified in browser at container IP - Add Debian card to installation index, extend comparison table - Add Debian to mkdocs.yml nav Signed-off-by: Christoph Schaefer Co-Authored-By: Claude Sonnet 4.6 --- docs/installation/debian.md | 129 ++++++++++++++++++++++++++++++++++++ docs/installation/index.md | 20 ++++-- mkdocs.yml | 1 + 3 files changed, 144 insertions(+), 6 deletions(-) create mode 100644 docs/installation/debian.md diff --git a/docs/installation/debian.md b/docs/installation/debian.md new file mode 100644 index 0000000..659353e --- /dev/null +++ b/docs/installation/debian.md @@ -0,0 +1,129 @@ +# Installing Euro-Office on Debian + +This guide covers installing Euro-Office Document Server on Debian 12 (Bookworm) from a GitHub release package. + +## System requirements + +- Debian 12 (Bookworm) — arm64 or amd64 +- 10 GB disk space minimum +- 4 GB RAM minimum + +## Step 1 — Enable the contrib component + +The `ttf-mscorefonts-installer` package required by Euro-Office lives in Debian's +`contrib` component, which is not enabled by default. Edit `/etc/apt/sources.list` +and add `contrib` to each line: + +``` +deb http://deb.debian.org/debian bookworm main contrib +deb http://deb.debian.org/debian bookworm-updates main contrib +deb http://deb.debian.org/debian-security/ bookworm-security main contrib +``` + +Then update the package index: + +```bash +sudo apt-get update +``` + +## Step 2 — Install prerequisites + +All prerequisites are available in the default Debian 12 repositories — no extra +package sources required: + +```bash +sudo apt-get install -y postgresql redis-server rabbitmq-server nginx supervisor +``` + +## Step 3 — Create the database + +The post-install script connects to PostgreSQL during installation. Create the user +and database first: + +```bash +sudo -u postgres psql -c "CREATE USER ds WITH PASSWORD 'ds';" +sudo -u postgres psql -c "CREATE DATABASE ds OWNER ds;" +``` + +## Step 4 — Pre-seed the installer answers + +```bash +echo "ds ds/db-type select postgres +ds ds/db-host string localhost +ds ds/db-port string 5432 +ds ds/db-user string ds +ds ds/db-pwd password ds +ds ds/db-name string ds" | sudo debconf-set-selections +``` + +## Step 5 — Download the package + +Download the latest release from [GitHub Releases](https://github.com/Euro-Office/DocumentServer/releases): + +```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 +``` + +**Available architectures:** `amd64`, `arm64` + +## Step 6 — Install the package + +```bash +sudo apt-get install -y /tmp/euro-office-documentserver.deb +``` + +The installer generates fonts, WOPI keys, and JS caches. This takes a minute. A +successful install ends with: + +``` +Congratulations, the Euro-Office DocumentServer has been installed successfully! +``` + +## Step 7 — Verify + +Check that all services are running: + +```bash +systemctl is-active ds-docservice ds-converter ds-metrics nginx +``` + +Expected output: + +``` +active +active +active +active +``` + +Run the health check: + +```bash +curl http://localhost/healthcheck +``` + +Expected output: `true` + +## Optional: Test with the built-in example app + +To verify the editor works end-to-end in a browser, follow the [Example App guide](example.md). + +## Updating + +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 +``` + +## Uninstalling + +```bash +sudo apt-get remove --purge euro-office-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 bb35864..3f9e050 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -22,6 +22,14 @@ Euro-Office Document Server can be installed in several ways depending on your e [:octicons-arrow-right-24: Docker installation](docker.md) +- :fontawesome-brands-debian: **Debian (deb)** + + --- + + Install from a `.deb` package on Debian 12 (Bookworm). + + [:octicons-arrow-right-24: Debian installation](debian.md) + - :fontawesome-brands-fedora: **Fedora (rpm)** --- @@ -40,9 +48,9 @@ Once installed, use the built-in example app to confirm the editor works end-to- ## Which method should I use? -| | Docker | Ubuntu (deb) | Fedora (rpm) | -|---|---|---|---| -| Recommended for production | Yes | Yes | Yes | -| Easiest to update | Yes | | | -| Full OS control | | Yes | Yes | -| Nextcloud integration | Yes | Yes | Yes | +| | Docker | Ubuntu (deb) | Debian (deb) | Fedora (rpm) | +|---|---|---|---|---| +| Recommended for production | Yes | Yes | Yes | | +| Easiest to update | Yes | | | | +| Full OS control | | Yes | Yes | Yes | +| Nextcloud integration | Yes | Yes | Yes | Yes | diff --git a/mkdocs.yml b/mkdocs.yml index 99dc1f7..a7ac488 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,6 +100,7 @@ nav: - Installation: - installation/index.md - Ubuntu: installation/ubuntu.md + - Debian: installation/debian.md - Fedora: installation/fedora.md - Docker: installation/docker.md - Verify with Example App: installation/example.md