Skip to content

Feature/110 install documentation#2

Open
chrip wants to merge 8 commits into
mainfrom
feature/110-install-documentation
Open

Feature/110 install documentation#2
chrip wants to merge 8 commits into
mainfrom
feature/110-install-documentation

Conversation

@chrip
Copy link
Copy Markdown

@chrip chrip commented Jun 8, 2026 •
edited
Loading

Summary

Closes #110 (partial — Rocky Linux blocked, docs.nextcloud.com tasks are separate).

All steps were verified interactively on real machines before being written into documentation.

  • Ubuntu (deb): verified on a clean Multipass VM (Ubuntu 24.04 LTS)
  • Fedora (rpm): verified on a clean LXD container (Fedora 44)
  • Docker: verified locally with ghcr.io/euro-office/documentserver
  • Building from source: verified locally — Docker image, packages (.deb + .rpm), and branded build

Pages added / rewritten

Page Status
installation/index.md New — landing page with method cards
installation/ubuntu.md New — verified Ubuntu 24.04 install guide
installation/fedora.md New — verified Fedora 44 install guide
installation/docker.md Rewritten — replaces placeholder with verified steps
installation/example.md New — example app verification (deb + rpm tabs)
development/building.md Rewritten — verified Docker image, package, and branded builds
docs/index.md Updated — cards wired to real pages

Notable findings documented

  • Rocky Linux 9: glibc 2.34 incompatibility with the RPM. Documented as known issue in fedora.md.
  • Fedora quirks: nginx conf.d not included by default, missing openssl, manual DB schema init, manual JWT config — all documented.
  • BuildKit entitlements: BUILDX_BAKE_ENTITLEMENTS_FS=0 + --allow=fs.read=.. required for all bake builds.
  • Branded build: brand-server.hcl changes COMPANY_NAME and install paths but visual assets are currently identical to Euro-Office defaults — documented honestly.

Out of scope

  • Rocky Linux docs — blocked until RPM is rebuilt on a RHEL 9 base image
  • docs.nextcloud.com tasks — tracked separately in #110

Assisted-by: claude-code:claude-sonnet-4-6

chrip and others added 8 commits June 8, 2026 09:57
@chrip @claude
docs(installation): add verified Ubuntu install guide and example app…
7fab916 
… docs

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 <christoph.schaefer@nextcloud.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@chrip @claude
chore: exclude PLAN.md from version control
60eec27 
Signed-off-by: Christoph Schaefer <christoph.schaefer@nextcloud.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@chrip @claude
docs(installation): rewrite Docker install guide with verified steps
979b109 
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 <christoph.schaefer@nextcloud.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@chrip @claude
docs(installation): add verified Fedora 44 install guide
ce8e8a5 
- 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 <christoph.schaefer@nextcloud.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@chrip @claude
docs(development): rewrite building guide with verified steps
8d89757 
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 <christoph.schaefer@nextcloud.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@chrip @claude
docs: add verify section to build guide and fix index links
9429700 
- 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 <christoph.schaefer@nextcloud.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@chrip @claude
docs(development): document branded build with brand-icons pipeline
ef8edae 
- 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 <christoph.schaefer@nextcloud.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@chrip @claude
docs(installation): add verified Debian 12 install guide
422f235 
- 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 <christoph.schaefer@nextcloud.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Install documentation

1 participant

@chrip