# Joplin Server Documentation

**URL:** <https://discourse.joplinapp.org/t/joplin-server-documentation/24026>\
**Category:** Features\
**Created:** [26 February 2022 04:27 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026 "2022-02-26T04:27:54Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![joplin\_user](https://avatars.discourse-cdn.com/v4/letter/j/977dab/32.png) [@joplin\_user](https://discourse.joplinapp.org/u/joplin_user)\
**Post date:** [26 February 2022 04:27 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/1 "2022-02-26T04:27:54Z")

</div>

Hello All, is anyone aware of a more detailed Joplin Server install guide than on Git? [joplin/README.md at dev · laurent22/joplin · GitHub](https://github.com/laurent22/joplin/blob/dev/packages/server/README.md)

I had quite a needlessly difficult time getting Joplin Server stood up following the above document. If there is no other guide, I would love to help improve the documentation and fill in any gaps as a new user of Joplin Server.

Thanks!

---

<div class="post-metadata">

**Author:** ![anon33605855](https://avatars.discourse-cdn.com/v4/letter/a/a9adbd/32.png) [@anon33605855](https://discourse.joplinapp.org/u/anon33605855)\
**Post date:** [26 February 2022 19:30 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/2 "2022-02-26T19:30:48Z")

</div>

I don't think there is. But I found it really straightforward (and still do, even using the .env file and the provided docker-compose.yml only is more than enough to set it up, but of course, ymmv), what caused the issues for you?

---

<div class="post-metadata">

**Author:** ![joplin\_user](https://avatars.discourse-cdn.com/v4/letter/j/977dab/32.png) [@joplin\_user](https://discourse.joplinapp.org/u/joplin_user)\
**Post date:** [28 February 2022 00:32 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/3 "2022-02-28T00:32:54Z")

</div>

Thanks for the reply. Below are a few questions I would have if I were a new user of Joplin Server who had no idea what Docker was. I think the documentation could be improved by helping answer some of these questions and fill in the gaps.

1. The first line reads "First copy .env-sample to .env and edit the values in there:"

2. "To start the server with default configuration, run:"

3. "A sample docker-compose file is available to show how to use Docker to install both the database and server and connect them:"

4. "Setup reverse proxy"

5. "Once the server is exposed to the internet, you can open the admin UI and get it ready for synchronisation. For the following instructions, we'll assume that the Joplin server is running on [https://example.com/joplin."](https://example.com/joplin.%22)

There is also existing documentation around Joplin Server that I think would be very helpful to integrate directly into the website if it is not already. E.g. [Share notebooks and collaborate on them using Joplin Server 2.0](https://discourse.joplinapp.org/t/share-notebooks-and-collaborate-on-them-using-joplin-server-2-0/18125)

---

<div class="post-metadata">

**Author:** ![anon33605855](https://avatars.discourse-cdn.com/v4/letter/a/a9adbd/32.png) [@anon33605855](https://discourse.joplinapp.org/u/anon33605855)\
**Post date:** [28 February 2022 08:49 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/4 "2022-02-28T08:49:03Z")

</div>

I’ll reply later in length a bit later, but honestly, if the questions are these or like these, one should not try and set up Joplin Server. It is not for beginners as it is but for people with at least intermediate IT experience and expertise.

---

<div class="post-metadata">

**Author:** ![Roland](https://avatars.discourse-cdn.com/v4/letter/r/3ab097/32.png) [@Roland](https://discourse.joplinapp.org/u/Roland)\
**Post date:** [1 March 2022 17:18 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/5 "2022-03-01T17:18:06Z")

</div>

I fully agree with @anon33605855. Since I need to share notebooks with other profiles, the server currently seems the only way to go. But I didn't get it to work and gave up due to the slim description. I'm not a pro, but I know my way around on my Linux server. Never needed to look into docker or such stuff.  
So in short, a easy how to would be great. I know, documentation is a lot of work and not very popular.  
But I'm quiet sure that a lot of people would love to get there own Joplin server up and running.

---

<div class="post-metadata">

**Author:** ![anon33605855](https://avatars.discourse-cdn.com/v4/letter/a/a9adbd/32.png) [@anon33605855](https://discourse.joplinapp.org/u/anon33605855)\
**Post date:** [1 March 2022 17:23 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/6 "2022-03-01T17:23:01Z")

</div>

Half offtopic:

If you need help, I can set the server up for you in minutes. 🙂 Ping me if you do.

---

<div class="post-metadata">

**Author:** ![laurent](https://avatars.discourse-cdn.com/v4/letter/l/ce7236/32.png) [@laurent](https://discourse.joplinapp.org/u/laurent)\
**Post date:** [1 March 2022 17:26 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/7 "2022-03-01T17:26:51Z")

</div>

It might help to know on what part specifically you were stuck. The doc is actually quite long and is supposed to be comprehensive. But maybe what's missing is integration with various reverse proxies, however I'm not sure that's something we'll document. If you self host you probably need to learn how to do this independently of Joplin Server, and there are plenty of already existing tutorials for this.

---

<div class="post-metadata">

**Author:** ![dixon1e](https://yyz2.discourse-cdn.com/flex028/user_avatar/discourse.joplinapp.org/dixon1e/32/12954_2.png) [@dixon1e](https://discourse.joplinapp.org/u/dixon1e)\
**Post date:** [2 March 2022 02:57 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/8 "2022-03-02T02:57:47Z")

</div>

New here. If there is a group a folk who want to learn how to set up Joplin, I would be interested in that. Maybe an online thing for an hour, via video?

EDIT: I just did a quick scan of the README. It's clear this is a containerized application, and based on the answer to "where do you want to run this" and "how much do you care about your data" you will have some options. For the experienced, this is straightforward.

I would definitely want to do this with a group just to learn among other folks (best way!) and would provide Zoom if there is a call for it.

---

<div class="post-metadata">

**Author:** ![MrKanister](https://yyz2.discourse-cdn.com/flex028/user_avatar/discourse.joplinapp.org/mrkanister/32/20054_2.png) [@MrKanister](https://discourse.joplinapp.org/u/MrKanister)\
**Post date:** [2 March 2022 17:31 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/9 "2022-03-02T17:31:14Z")

</div>

There is also my guide for Joplin-Server on ARM64, but of course it is not official and can't be found directly through a link or something. But by searching a bit and choosing the official image it should show everything very detailed for beginners:

> [@Guide for Joplin-Server on Raspberry Pi](https://discourse.joplinapp.org/t/guide-for-joplin-server-on-raspberry-pi/14702):
>
> Hi, this is an extensive guide on how to host your own Joplin server on a Raspberry Pi. I had a setup like this running on a Pi 4 and a Pi 5. Technically it would also work on Pi 3 models which support 64-bit operating systems. If you spot any mistakes, please reply to me! The guide was updated on 11.06.2025. 1 Dynamic DNS If you don't get a static IP address from your ISP, you will need a Dynamic DNS service. This sets a hostname which will be redirected to your IP. There are a lot of pro…

Kind Regards!

---

<div class="post-metadata">

**Author:** ![235462849350](https://avatars.discourse-cdn.com/v4/letter/2/bc8723/32.png) [@235462849350](https://discourse.joplinapp.org/u/235462849350)\
**Post date:** [2 March 2022 21:13 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/10 "2022-03-02T21:13:30Z")

</div>

@anon33605855 :  
I also get stuck setting up the Joplin Server with docker, looks like the database settings are not correct and I can`t call the correct login page.

I will get a new server the next weeks and will try again from scratch. But I would be happy if I can come back to you:)

---

<div class="post-metadata">

**Author:** ![anon33605855](https://avatars.discourse-cdn.com/v4/letter/a/a9adbd/32.png) [@anon33605855](https://discourse.joplinapp.org/u/anon33605855)\
**Post date:** [2 March 2022 21:19 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/11 "2022-03-02T21:19:17Z")

</div>

Sure thing! If you wish, just let me know when you get the new server and I'll set it all up for you. 🙂

---

<div class="post-metadata">

**Author:** ![dixon1e](https://yyz2.discourse-cdn.com/flex028/user_avatar/discourse.joplinapp.org/dixon1e/32/12954_2.png) [@dixon1e](https://discourse.joplinapp.org/u/dixon1e)\
**Post date:** [3 March 2022 05:23 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/12 "2022-03-03T05:23:00Z")

</div>

Love the idea of running this on a Raspberry Pi and carrying it around. The guide looks like a lot of work has been done to figure this out. Will read and understand some more.

Well done - thank you.

---

<div class="post-metadata">

**Author:** ![joplin\_user](https://avatars.discourse-cdn.com/v4/letter/j/977dab/32.png) [@joplin\_user](https://discourse.joplinapp.org/u/joplin_user)\
**Post date:** [3 March 2022 14:41 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/13 "2022-03-03T14:41:37Z")

</div>

Hello All,

Thank you for the replies and interest in this topic. My apologies for the delay in responding - I wanted to have something more substantive before I replied. I've copy/pasted the README here and made a number of updates ([joplin/packages/server/README.md at dev · laurent22/joplin · GitHub](https://github.com/laurent22/joplin/blob/dev/packages/server/README.md)). @laurent - I am hoping that you would kindly take the time to parse through the edit and adjust any corrections that are needed and/or provide feedback as needed. The only input I can currently provide is that of someone who has just installed Joplin Server, so I'm sure I am missing some details etc.

Edits:

- Added Requirements header.
- Added requirement to list Docker Engine.
- Added direct URL to .env-sample.
- Clarification around where to copy the .env-sample file.
- Adjusted header language for configuring Docker.
- Adjusted header language for test starting the server.
- Removed the step to adjust the APP\_BASE\_URL and APP\_PORT as it doesn't appear to be required for testing.
- Minor formatting improvement.
- Added note that a reverse proxy is not required if Joplin Server is only to be run over LAN.
- Improved language around configuring storage.
- Added Docker Compose to the Requirements if a PostgreSQL is not going to be used.
- Added steps pertaining to docker-compose to configure POSTGRES\_PASSWORD={POSTGRES\_PASSWORD}, POSTGRES\_USER={POSTGRES\_USER}, APP\_BASE\_URL=${APP\_BASE\_URL}. I experienced issues starting the container if these were not set.
- Added distinct steps for configuring the APP\_BASE\_URL for local vs internet accessibility.
- Added additional information around setting the APP\_PORT for local vs internet accessibility.
- Added step to open the Admin Page if Joplin Server is configured locally only.
- Adjusted Website Configuration header to better reflect step.
- Adjusted the Admin User credential header to better reflect step.
- Updated setting the Admin user's steps for clarity.

# Installing

## Requirements

- Docker Engine run Joplin Server. See [Install Docker Engine](https://docs.docker.com/engine/install/) for steps to install Docker Engine for your operating system.
- Docker Compose is required to store item contents (notes, tags, etc.) if PostgreSQL is not used. See [Install Docker Compose](https://docs.docker.com/compose/install/) for steps to install Docker Compose for your operating system.

## Configure Docker for Joplin Server

1. Copy `.env-sample` (located [here](https://github.com/laurent22/joplin/blob/dev/.env-sample)) to the location of your Docker configuration files. Example: /home/[user]/docker
2. Rename the file `.env-sample` to `.env`.

## Test Starting the Server

1. Run the following command to test starting the server using the default configuration:

```shell
docker run --env-file .env -p 22300:22300 joplin/server:latest

```

The server will listen on port **22300** on **localhost**. By default, the server will use SQLite, which allows you to test the app without setting up a database. When running the server for production use, you should connect the container to a database, as described below.

## Supported Docker Tags

The following tags are available:

- `latest` is always the most recent released version
- `beta` is always the most recent beta released version
- Major versions, such as `2`, `2-beta`
- Specific minor versions, such as `2.1`, `2.2`, `2.3-beta`
- Specific patch versions, such as `2.0.4`, `2.2.8-beta`

## Setup the Database

You can setup the container to either use an existing PostgreSQL server, or connect it to a new database using docker-compose.

### Using an Existing PostgreSQL Server

To use an existing PostgresSQL server, set the following environment variables in the .env file:

```conf
DB_CLIENT=pg
POSTGRES_PASSWORD=joplin
POSTGRES_DATABASE=joplin
POSTGRES_USER=joplin
POSTGRES_PORT=5432
POSTGRES_HOST=localhost

```

Ensure that the provided database and user exist as Joplin server will not create them. When running on macOS or Windows through Docker Desktop, a mapping of localhost is made automatically. On Linux, you can add `--net=host --add-host=host.docker.internal:127.0.0.1` to the `docker run` command line to make the mapping happen. Any other `POSTGRES_HOST` than localhost or 127.0.0.1 should work as expected without further action.

### Using Docker-Compose

1. Using the sample [docker-compose file](https://github.com/laurent22/joplin/blob/dev/docker-compose.server.yml), create a docker compose file in the location of your Docker configuration files. Example: /home/[user]/docker/docker-compose.yml
2. Update the following fields:

```conf
POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
POSTGRES_USER=${POSTGRES_USER}
APP_BASE_URL=${APP_BASE_URL}

```

- `APP_BASE_URL`: This is the base public URL where the service will be running.
  - If Joplin Server needs to be accessible over the internet, configure `APP_BASE_URL` as follows: `https://example.com/joplin`.
  - If Joplin Server does not need to be accessible over the internet, set the the `APP_BASE_URL` to your server's hostname. For Example: `http://[hostname]:22300`. The base URL can include the port.

- `APP_PORT`: The local port on which the Docker container will listen.
  - You would typically map this port to 443 (TLS) with a reverse proxy.
  - If Joplin Server does not need to be accessible over the internet, the port can be mapped to 22300.

## Setup Reverse Proxy (Optional)

Configuring a reverse proxy is not required for core functionality and is only required if Joplin Server needs to be accessible over the internet. See the following documentation for configuring a reverse proxy with Apache or Nginx.

- [Apache Reverse Proxy](https://httpd.apache.org/docs/current/mod/mod_proxy.html)
- [Nginx Reverse Proxy](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/)

## Setup Storage (Optional)

By default, the item contents (notes, tags, etc.) are stored in the database and no additional steps are required to get that working.

However, since that content can be quite large, you have the option to store it outside the database by setting the `STORAGE_DRIVER` environment variable.

### Setting up Storage on a New Installation

To save item contents (notes, tags, etc.) to the local filesystem instead, use:

```
STORAGE_DRIVER=Type=Filesystem; Path=/path/to/dir

```

After this is set, all item contents will be saved under the defined `/path/to/dir` directory.

### Migrating Storage for an Existing Installation

Migrating storage is a bit more complicated because the old content will have to be migrated to the new storage. This is done by providing a fallback driver, which tells the server where to look if a particular item is not yet available on the new storage.

To migrate from the database to the file system, you would set the environment variables as follows:

```
STORAGE_DRIVER=Type=Filesystem; Path=/path/to/dir
STORAGE_DRIVER_FALLBACK=Type=Database; Mode=ReadAndWrite

```

From then on, all new and updated content will be added to the filesystem storage. When reading an item, if the server cannot find it in the filesystem, it will look for it in the database.

Fallback drivers have two write modes:

- In **ReadAndClear** mode, it's going to clear the fallback driver content every time an item is moved to the main driver. It means that over time the old storage will be cleared and all content will be on the new storage.

- In **ReadAndWrite** mode, it's going to write the content to the fallback driver too. This is purely for safey - it allows deploying the new storage (such as the filesystem or S3) but still keep the old storage up-to-date. So if something goes wrong it's possible to go back to the old storage until the new one is working.

It's recommended to start with ReadAndWrite mode.

This simple setup with main and fallback driver is sufficient to start using a new storage, however old content that never gets updated will stay on the database. To migrate this content too, you can use the `storage import` command. It takes a connection string and move all items from the old storage to the new one.

For example, to move all content from the database to the filesytem:

```
docker exec -it CONTAINER_ID node packages/server/dist/app.js storage import --connection 'Type=Filesystem; Path=/path/to/dir'

```

On the database, you can verify that all content has been migrated by running this query:

```sql
SELECT count(*), content_storage_id FROM items GROUP BY content_storage_id;

```

If everything went well, all items should have a `content_storage_id` \> 1 ("1" being the database).

### Other Storage Driver

Besides the database and filesystem, it's also possible to use AWS S3 for storage using the same environment variable:

```
STORAGE_DRIVER=Type=S3; Region=YOUR_REGION_CODE; AccessKeyId=YOUR_ACCESS_KEY; SecretAccessKeyId=YOUR_SECRET_ACCESS_KEY; Bucket=YOUR_BUCKET

```

## Verify Access to the Admin Page

Once Joplin Server is exposed to the internet, you can open the admin UI and get it ready for synchronisation. For the following instructions, we'll assume that the Joplin server is running on `https://example.com/joplin`.

If Joplin Server is running running locally only, access the Admin Page using `http://[hostname]:22300`

### Update the Admin User Credentials

By default, Joplin Server will be setup with an admin user with email **admin@localhost** and password **admin**. For security purposes, the admin user's credentials should be changed. On the Admin Page, login as the admin user. In the upper right, select the Profile button update the admin password.

### Create a User for Sync

While the admin user can be used for synchronisation, it is recommended to create a separate non-admin user for it. To do so, navigate to the Users page - from there you can create a new user. Once this is done, you can use the email and password you specified to sync this user account with your Joplin clients.

## Checking the logs

Checking the log can be done the standard Docker way:

```bash
# With Docker:
docker logs --follow CONTAINER

# With docker-compose:
docker-compose --file docker-compose.server.yml logs

```

# Setup for Development

## Setup up the Database

### SQLite

By default the server supports SQLite for development, so nothing needs to be setup.

### PostgreSQL

To use Postgres, from the monorepo root, run `docker-compose --file docker-compose.server-dev.yml up`, which will start the PostgreSQL database.

## Starting the Server

From `packages/server`, run `npm run start-dev`

# Changelog

[View the changelog](https://github.com/laurent22/joplin/blob/dev/readme/changelog_server.md)

# License

See LICENSE.md in this directory

```auto

```

---

<div class="post-metadata">

**Author:** ![joplin\_user](https://avatars.discourse-cdn.com/v4/letter/j/977dab/32.png) [@joplin\_user](https://discourse.joplinapp.org/u/joplin_user)\
**Post date:** [3 March 2022 14:43 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/14 "2022-03-03T14:43:12Z")

</div>

Really appreciate the offer! I was able to get Joplin Server setup the other day, but I've posted above a few suggested updates to the README. 🙂

---

<div class="post-metadata">

**Author:** ![joplin\_user](https://avatars.discourse-cdn.com/v4/letter/j/977dab/32.png) [@joplin\_user](https://discourse.joplinapp.org/u/joplin_user)\
**Post date:** [12 March 2022 09:35 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/15 "2022-03-12T09:35:03Z")

</div>

Hi @laurent - I just wanted to follow up on the above suggested edits I made to see if you had a chance to share your thoughts. Thanks!

---

<div class="post-metadata">

**Author:** ![laurent](https://avatars.discourse-cdn.com/v4/letter/l/ce7236/32.png) [@laurent](https://discourse.joplinapp.org/u/laurent)\
**Post date:** [12 March 2022 09:39 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/16 "2022-03-12T09:39:38Z")

</div>

Thanks for looking into this but could you create a pull request please? That way we can see directly what has changed in the readme.

---

<div class="post-metadata">

**Author:** ![joplin\_user](https://avatars.discourse-cdn.com/v4/letter/j/977dab/32.png) [@joplin\_user](https://discourse.joplinapp.org/u/joplin_user)\
**Post date:** [12 March 2022 09:51 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/17 "2022-03-12T09:51:43Z")

</div>

Sure thing @laurent, I will look into that, thanks!

---

<div class="post-metadata">

**Author:** ![joplin\_user](https://avatars.discourse-cdn.com/v4/letter/j/977dab/32.png) [@joplin\_user](https://discourse.joplinapp.org/u/joplin_user)\
**Post date:** [12 March 2022 10:04 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/18 "2022-03-12T10:04:24Z")

</div>

Pull request created: [Update README.md by ScriptInfra · Pull Request #6260 · laurent22/joplin · GitHub](https://github.com/laurent22/joplin/pull/6260)

---

<div class="post-metadata">

**Author:** ![235462849350](https://avatars.discourse-cdn.com/v4/letter/2/bc8723/32.png) [@235462849350](https://discourse.joplinapp.org/u/235462849350)\
**Post date:** [10 October 2022 21:12 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/19 "2022-10-10T21:12:04Z")

</div>

Is the official joplin-server docker still maintained? Last update was 8 month ago, wasn`t it?

---

<div class="post-metadata">

**Author:** ![joplin\_user](https://avatars.discourse-cdn.com/v4/letter/j/977dab/32.png) [@joplin\_user](https://discourse.joplinapp.org/u/joplin_user)\
**Post date:** [10 October 2022 21:34 UTC](https://discourse.joplinapp.org/t/joplin-server-documentation/24026/20 "2022-10-10T21:34:01Z")

</div>

It looks like there are recent commits for Server: [Commits · laurent22/joplin · GitHub](https://github.com/laurent22/joplin/commits)

[Next page](https://discourse.joplinapp.org/t/joplin-server-documentation/24026.md?page=2)