Как установить и настроить Joplin Server на VPS

MAATRIX

Joplin — удобный опенсорсный блокнот с шифрованием, markdown и клиентами на все платформы, но по умолчанию он синхронизируется через Dropbox, OneDrive или Joplin Cloud — то есть ваши заметки лежат на чужих серверах. Joplin Server решает эту проблему: вы поднимаете собственную точку синхронизации на своём VPS, и все данные — от паролей до рабочих черновиков — остаются под вашим контролем. Ниже — рабочая установка через Docker Compose с PostgreSQL, HTTPS-сертификатом и подключением клиентов.

Что нужно перед установкой

Joplin Server — легковесное Node.js-приложение, оно не требовательно к ресурсам. Для личного использования и небольшой команды (до 10-15 человек) достаточно:

• VPS с 1 vCPU и 1-2 ГБ RAM — этого хватает с запасом, база данных заметок редко превышает пару гигабайт даже при активном использовании с вложениями;
• Ubuntu 24.04 или Debian 12 — в статье команды даны под Ubuntu, для Debian они идентичны;
• Домен или поддомен (например, notes.example.com), направленный A-записью на IP сервера — без домена не получится честно выпустить HTTPS-сертификат, а без HTTPS клиенты Joplin будут ругаться на синхронизацию;
• Docker и Docker Compose — если ещё не установлены, разверните их по отдельной инструкции, там разобраны нюансы для продакшена.

Открытых портов наружу нужно всего два — 80 и 443 для реверс-прокси. Сам Joplin Server будет слушать только на localhost, наружу его слать не нужно.

Docker Compose: Joplin Server и PostgreSQL

Joplin Server умеет работать с SQLite, но для сервера, который будет крутиться постоянно и синхронизировать несколько устройств, разработчики сами рекомендуют PostgreSQL — он устойчивее к параллельным запросам и проще в бэкапе. Создайте директорию проекта и файлы:

mkdir -p /opt/joplin-server/data/postgres
cd /opt/joplin-server

Файл .env с паролем базы — не коммитьте его никуда, сгенерируйте случайную строку:

cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
APP_BASE_URL=https://notes.example.com
EOF

Замените notes.example.com на реальный домен. Теперь docker-compose.yml:

services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: joplin
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: joplin
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    networks:
      - joplin_net

  app:
    image: joplin/server:latest
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "127.0.0.1:22300:22300"
    environment:
      APP_PORT: 22300
      APP_BASE_URL: ${APP_BASE_URL}
      DB_CLIENT: pg
      POSTGRES_HOST: db
      POSTGRES_PORT: 5432
      POSTGRES_DATABASE: joplin
      POSTGRES_USER: joplin
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      MAILER_ENABLED: "0"
      STORAGE_DRIVER: "Type=Filesystem; Path=/app/data"
    volumes:
      - ./data/attachments:/app/data
    networks:
      - joplin_net

networks:
  joplin_net:

Обратите внимание на STORAGE_DRIVER. По умолчанию Joplin Server хранит вложения (файлы, картинки) прямо в PostgreSQL как blob-объекты — это работает, но раздувает базу и усложняет бэкап. Вынос вложений в файловую систему через Filesystem-драйвер держит базу компактной, а сами файлы бэкапятся как обычная директория.

MAILER_ENABLED: "0" отключает почтовые уведомления — без него при первом запуске сервер будет ругаться в логи на отсутствие SMTP. Если нужны письма для сброса пароля пользователям (актуально, если сервер общий на команду), позже добавьте блок MAILER_HOST, MAILER_PORT, MAILER_SECURITY, MAILER_AUTH_USER, MAILER_AUTH_PASSWORD — данные обычного SMTP-релея подойдут.

Поднимаем:

docker compose up -d
docker compose logs -f app

В логах должно появиться что-то вроде Server started без ошибок подключения к БД. Если видите ECONNREFUSED на порт 5432 — контейнер db ещё не успел проинициализироваться, подождите 10-15 секунд, depends_on гарантирует только порядок старта контейнеров, но не готовность PostgreSQL принимать соединения.

Реверс-прокси и SSL-сертификат

Joplin Server слушает на 127.0.0.1:22300 без TLS — снаружи его нужно прикрыть реверс-прокси с HTTPS. Проще всего это сделать через Caddy — он сам выпускает и продлевает сертификат Let's Encrypt, конфиг занимает три строки. Если Caddy ещё не установлен, разверните его по инструкции по установке Caddy с авто-SSL.

Конфиг /etc/caddy/Caddyfile:

notes.example.com {
    reverse_proxy 127.0.0.1:22300
}

Перезапустите Caddy:

systemctl reload caddy

Через 10-30 секунд домен должен открыться по HTTPS с валидным сертификатом. Если предпочитаете Nginx с Certbot — это тоже рабочий вариант, просто потребует чуть больше ручной настройки сертификата отдельно от конфига прокси.

Важный момент: APP_BASE_URL в .env должен точно совпадать с адресом, по которому клиенты будут стучаться на сервер, включая протокол https://. Если поменяете домен позже — обновите переменную и пересоздайте контейнер app (docker compose up -d --force-recreate app), иначе клиенты будут получать битые ссылки на вложения.

Первый запуск и учётные записи

Откройте https://notes.example.com в браузере — увидите веб-интерфейс администрирования Joplin Server. Данные для входа по умолчанию:

• Email: admin@localhost
• Пароль: admin

Это первое, что нужно поменять. Зайдите под этим аккаунтом → Users → откройте профиль администратора → смените email на реальный и задайте длинный пароль. Оставлять дефолтные креды на публично доступном сервере — это фактически открытая дверь к вашим заметкам.

Дальше, если сервер не только для вас, создайте пользователей: Users → New User, укажите email, задайте пароль (или, если настроен MAILER, пользователь получит письмо с приглашением сам задать пароль). Каждому пользователю можно ограничить квоту на объём хранимых данных через поле Max Item Size — полезно, если сервер общий на команду и кто-то один не должен занять всё место вложениями.

Веб-интерфейс также показывает базовую статистику: сколько пользователей, общий объём хранилища, версию приложения — удобно для быстрой проверки, что всё живо, без захода в логи контейнера.

Подключение клиентов Joplin

На каждом устройстве, где стоит Joplin (desktop, Android, iOS), настройка одинаковая:

1. Откройте Настройки → Синхронизация (в десктопном приложении: Tools → Options → Synchronisation).
2. В поле Target выберите Joplin Server.
3. Укажите:

• Email: ваш email пользователя
• Password: пароль пользователя
• Joplin Server URL: https://notes.example.com

1. Нажмите Synchronise (или Check synchronisation configuration — она проверит соединение без реального запуска синка).

Если конфигурация подтвердилась — жмите синхронизацию. Первый синк с уже существующим блокнотом заметок может занять несколько минут в зависимости от объёма — Joplin шифрует и загружает каждую заметку и вложение отдельными запросами, это не мгновенно, особенно если у вас накопилось много прикреплённых файлов.

Отдельно стоит включить End-to-End Encryption (в тех же настройках синхронизации, вкладка Encryption) — тогда даже администратор Joplin Server физически не сможет прочитать содержимое ваших заметок в базе, он видит только зашифрованные блобы. Единственный нюанс — обязательно сохраните мастер-пароль шифрования в надёжном месте: Joplin Server его не хранит и восстановить доступ без него нельзя.

Бэкапы, обновление и обслуживание

Бэкапить нужно два места: базу PostgreSQL и директорию вложений.

# дамп базы
docker compose exec db pg_dump -U joplin joplin > joplin_$(date +%F).sql

# вложения — обычная директория, можно rsync или tar
tar czf attachments_$(date +%F).tar.gz ./data/attachments

Вынесите эти команды в cron и складывайте архивы на отдельное хранилище (не на тот же диск, где крутится сервер) — если интересует более системный подход к бэкапам с ретеншеном и шифрованием, посмотрите сравнение решений для бэкапа сервера, принципы там применимы и к Joplin.

Обновление до новой версии — обычная процедура для Docker-стека:

docker compose pull
docker compose up -d

Перед крупным обновлением (смена мажорной версии Joplin Server) стоит сделать свежий дамп базы — на всякий случай, миграции схемы у Joplin Server применяются автоматически при старте контейнера, и откатить их вручную сложнее, чем восстановиться из бэкапа.

Раз в пару месяцев стоит заглядывать в объём директории data/postgres и data/attachments — если сервер общий на несколько активных пользователей с большими вложениями (сканы, фото), место может закончиться быстрее, чем кажется. df -h в cron с алертом на 80% занятости диска решает эту проблему заранее.

Частые вопросы