Skip to content
Klutch.sh Docs

Deploying an OlyOffice App

Introduction

OlyOffice (compatible with the ONLYOFFICE Document Server image) provides self-hosted document viewing and collaborative editing through a REST API. Deploying OlyOffice with a Dockerfile on Klutch.sh delivers reproducible builds, managed secrets, and persistent storage for document caches and logs—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your OlyOffice Dockerfile (GitHub is the only supported git source)
  • JWT secret for securing callbacks
  • Optional: external storage for large document caches

For onboarding, see the Quick Start.

Architecture and ports

  • OlyOffice serves HTTP on internal port 8080 (mapped from the default 80 inside the container); choose HTTP traffic.
  • Persistent storage is required for data, certificates, and logs.

Repository layout

olyoffice/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t olyoffice-local .
docker run -p 8080:8080 \
  -e JWT_ENABLED=true \
  -e JWT_SECRET=changeme \
  olyoffice-local

Dockerfile for OlyOffice (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM onlyoffice/documentserver:latest


# Align to port 8080 inside the container for Klutch.sh HTTP traffic
ENV DS_PORT=8080 \
    JWT_ENABLED=true \
    JWT_SECRET=changeme


EXPOSE 8080
CMD ["/bin/sh", "-c", "perl -pi -e 's/80/${DS_PORT}/g' /etc/nginx/includes/ds-*.conf && /app/ds/run-document-server.sh"]

Notes:

  • Pin the image tag (e.g., onlyoffice/documentserver:8.0.x) for stability and upgrade intentionally.
  • Replace JWT_SECRET with a strong value; keep it in Klutch.sh secrets.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • DS_PORT=8080
  • JWT_ENABLED=true
  • JWT_SECRET=<strong-secret>
  • Optional: JWT_HEADER=AuthorizationJwt if you customize the header, JWT_IN_BODY=true if you send tokens in the body.

If you deploy without the Dockerfile and need Nixpacks overrides (not typical for this image):

  • NIXPACKS_START_CMD=perl -pi -e 's/80/${DS_PORT}/g' /etc/nginx/includes/ds-*.conf && /app/ds/run-document-server.sh

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/www/onlyoffice/Data — document cache, certificates, and fonts.
  • /var/log/onlyoffice — logs for troubleshooting.

Ensure these paths are writable inside the container.

Deploy OlyOffice on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above, including a strong JWT_SECRET.
  5. Attach persistent volumes for /var/www/onlyoffice/Data and /var/log/onlyoffice, sizing them for your document cache and log retention.
  6. Deploy. Your OlyOffice instance will be reachable at https://example-app.klutch.sh; point your host application to this URL for document editing.

Sample API usage

Health check:

Terminal window
curl -I https://example-app.klutch.sh/healthcheck

Request a conversion (example payload):

Terminal window
curl -X POST "https://example-app.klutch.sh/ConvertService.ashx" \
  -H "Content-Type: application/json" \
  -H "AuthorizationJwt: <jwt_token>" \
  -d '{"async":false,"filetype":"docx","outputtype":"pdf","title":"sample","key":"123","url":"https://example.com/sample.docx"}'

Health checks and production tips

  • Add an HTTP probe to /healthcheck for readiness.
  • Enforce HTTPS at the edge; forward internally to port 8080.
  • Keep JWT_SECRET in Klutch.sh secrets and rotate it regularly.
  • Monitor disk usage on /var/www/onlyoffice/Data; resize before it fills.
  • Pin image versions and test upgrades in staging; back up volumes before updates.

OlyOffice on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 8080 configured, and volumes persisted, you can deliver collaborative document editing without extra YAML or workflow overhead.