Self-Hosting
Hosted demo
We are hosting a demo at os-aps.sciflow.cloud
The demo us using the :latest images. To get access to the current development version (which may not work at all times, you can access os-aps-next.sciflow.cloud)
Please feel free to ask any questions in the #development channel over on Slack.
Running the App
To run the app locally, create a new directory for the data, navigate to it in your terminal, and use Docker to set up the container. Files such as manuscripts and configuration data will be stored in this directory. Below is a step-by-step guide:
1. Start the Server with Docker
Run the following command to start the server:
docker run \
--rm \
-p 127.0.0.1:3000:3000/tcp \
--platform linux/amd64 \
--name os-aps-demo \
--volume "$(pwd):/data" \
--env LOCAL_STORAGE_PATH=/data/manuscripts \
--env INSTANCE_TITLE="Personal Demo Instance" \
--env FONT_PATH=/data/fonts/ \
--env TRANSFORM_IMAGE_URL=http://localhost:3001 \
registry.gitlab.com/sciflow/development/server:latest
- Parameters:
--volume "$(pwd):/data"
mounts the current directory for persistent storage.--env INSTANCE_TITLE
sets the instance title visible in the app.--env LOCAL_STORAGE_PATH
specifies where manuscript files will be stored.--env FONT_PATH
defines the location of fonts for document rendering.--env TRANSFORM_IMAGE_URL
connects the app to a transformation service for images.
Once the server starts, open http://localhost:3000 in your browser to access the app.
2. Optional: Customize Your Domain
If you plan to access the app from a specific domain, add this line to your
docker run
command:
--env INSTANCE_URL="https://yourdomain:port"
This ensures compatibility with browsers that enforce Cross-Origin Resource Sharing (CORS) policies.
3. Customize Templates
To use custom export templates, follow these steps:
- Create a
templates
directory inside your data directory. - Download or create templates and place them in the
templates
folder. - Modify the
docker run
command to include the following environment variable:
--env TEMPLATE_SOURCE=/data/templates \
- Reload your export to see changes reflected.
Example template repository: Generic Monograph Template.
Templates are evaluated during export, allowing you to test changes without restarting the server.
4. S3 Storage Configuration (Optional)
If you wish to use S3 for file storage, specify the following:
--env S3_ENDPOINT="your-s3-endpoint" \
--env S3_ACCESS_KEY="your-access-key" \
--env S3_SECRET_KEY="your-secret-key" \
--env S3_REGION="your-region" \
--env S3_IMPORTER_BUCKET="your-bucket-name" \
5. Using PowerShell on Windows
If you’re using PowerShell, replace line breaks in the docker run
command with
backticks (```):
docker run `
--rm `
-p 127.0.0.1:3000:3000/tcp `
--platform linux/amd64 `
--name os-aps-demo `
--volume "${PWD}:/data" `
--env LOCAL_STORAGE_PATH=/data/manuscripts `
--env INSTANCE_TITLE="Personal Demo Instance" `
--env FONT_PATH=/data/fonts/ `
--env TRANSFORM_IMAGE_URL=http://localhost:3001 `
registry.gitlab.com/sciflow/development/server:latest
6. Debugging and Logs
To debug issues, check the container logs using:
docker logs os-aps-demo
If needed, add -it
and bash
to the docker run
command to open a shell
inside the container for troubleshooting.
7. Image Transformation Sidecar (Optional)
If you are using a sidecar container for image transformations, run the following Docker container alongside your main application. The sidecar uses LibreOffice to transform WMF and EMF files into PDF or PNG formats. It supports additional processing such as cropping whitespace from PDFs using pdfcrop and extracting images as PNGs using pdftoppm. The sidecar ensures compatibility with various input formats by leveraging robust file conversion and transformation tools.
docker run \
--rm \
-p 127.0.0.1:3001:3001/tcp \
--name file-transform-sidecar \
registry.gitlab.com/sciflow/development/file-transform-sidecar:latest
- Update the
TRANSFORM_IMAGE_URL
in the main app tohttp://localhost:3001
.
Development Setup
If you’d like to go beyond customizing templates (e.g., modify how exports are rendered or debug the backend), see the Development Setup Guide.
This updated version ensures users understand how to deploy the app using Docker without relying on Knative, providing clear instructions for configuration, customization, and debugging.