Joplin API Server docker image

Docker image for a standalone Joplin Terminal Web Clipper (aka Joplin Data API)

What is this?

This is not an image for the Joplin server.

If you want to use Joplin, go to the installation page.

If you want to self host the Joplin server, go to the Joplin Sever documentation. You will probably end up using the official Joplin server image.

If you are already using Joplin and want to use its REST API (also called Joplin Data API) you will soon realize that you need a Joplin client application with the Web Clipper enabled.

The image in this repository gives you a easy and programatic way to get a REST API that you can use for accessing your Joplin notes, notebooks, resources, etc. This is done by spawning a headless Joplin Terminal Application with joplin server start.

Take into account that this image behaves, on one hand, as a Joplin client. It needs to synchronize from a Joplin Server, Joplin Cloud, S3, WebDAV, etc. (whatever you are already using). On the other hand, the image publishes the API of Web Clipper; you can find the list of endpoints in the Joplin Data API documentation.

Configuring the image

The following environment variables can be used and that will set up how the container synchronizes and how to connect with the API:

JOPLIN_SYNC_TARGET can be:
- none which does not really make sense unless you want a standalone Joplin API with no synchronization between any other clients.
- filesystem
- onedrive
- nextcloud
- webdav
- dropbox
- s3
- joplin_server for self hosted Joplin Server deployments.
- joplin_cloud if you are using the Joplin Cloud service.
JOPLIN_SYNC_URL to configure the URL of the sync service (used by multiple targets)
JOPLIN_SYNC_PATH to configure the path (used by multiple targets). Make sure to check in the Synchronisation documentation whether you need the url or the path configuration for your target (or maybe both in the case of s3).
JOPLIN_SYNC_USERNAME username for synchronizing.
JOPLIN_SYNC_PASSWORD password for synchronizing.
JOPLIN_API_TOKEN secret token for connecting to the API. If omitted, Joplin will automatically populate it with a random token.
JOPLIN_SYNC_INTERVAL the synchronization interval. Use a valid value, default is 300 (synchronization every 5 minutes).

Profile, volume and Joplin settings

The volume for this image is located at /joplin-profile. This will contain all the synchronization data (notes, attachments, etc.) as well as settings for Joplin itself.

Note that the file settings.json will contain most configuration and will be modified/created during initialization according to the environment variables specified. For instance, the api.token configuration value will be in that file either with an autogenerated value (if JOPLIN_API_TOKEN was not specified) or with the value of the JOPLIN_API_TOKEN environment variable.

Example of a web application consuming the API

Let's say that you have a web application that needs access to the Joplin Data API. You can prepare a docker-compose.yml with the following contents:

services:
  joplin-api-server:
    image: ghcr.io/alexbarcelo/joplin-api-server:latest
    env:
      - JOPLIN_API_TOKEN
      ## Set up the appropriate synchronization target variables
      # - JOPLIN_SYNC_TARGET=x
      # - JOPLIN_SYNC_URL=
      # - JOPLIN_SYNC_USERNAME
      # - JOPLIN_SYNC_PASSWORD
    volumes:
      joplin-data: /joplin-profile
  
  my-awesome-app:
    image: my-awesome-image
    env:
      - JOPLIN_API_SERVER=http://joplin-api-server:41184
      - JOPLIN_API_TOKEN
    ports:
      - 5000:5000

volumes:
  joplin-data:

It is an untested incomplete example, but it should illustrate the basic idea behing this image. By using this architecture, the REST API for Joplin is completely internal (running across the compose-created internal network) and the port is not published. Which, in terms of attack surface, is a positive outcome. If you need to publish the port (because your needs, because you are in the developing stage, whatever your reasons) you can of course publish the 41184 port from the joplin-api-server container.

Sync shenanigans

WIP