Установка Turtl Server на Ubuntu 16.04

Важно: Ubuntu 16.04 устарела, но инструкция специально рассчитана на эту версию. На более новых дистрибутивах команды и пакеты могут отличаться.

О чём эта статья

Цель: установить Turtl Server (backend API) локально на Ubuntu 16.04 и настроить его для доступа через Apache обратный прокси. Подробно рассматриваются все шаги: от установки системных библиотек до запуска сервиса. Полезно для администраторов, DevOps-инженеров и тех, кто хочет держать заметки в закрытой инфраструктуре.

Ключевые варианты использования: приватный сервер заметок для команды, self-hosted альтернатива Evernote, тестирование и разработка API Turtl.

Краткие определения:

Turtl Server: backend API для клиентских приложений Turtl.
RethinkDB: документно-ориентированная БД, используемая Turtl.
Libuv: библиотека асинхронного ввода-вывода.
Clozure Common Lisp (CCL): реализация Common Lisp, необходимая для запуска Turtl.
Quicklisp: менеджер библиотек для Common Lisp.

Требования

Ubuntu 16.04 (root/sudo права)
Доступ в интернет для скачивания пакетов и репозиториев
Примерное свободное место: несколько сотен мегабайт для всех компонентов

Что мы сделаем

Установим системные зависимости
Установим Libuv вручную
Установим и настроим RethinkDB
Установим Clozure Common Lisp
Установим Quicklisp
Скачаем и настроим исходники Turtl
Запустим Turtl как системный сервис
Настроим Apache в качестве обратного прокси для Turtl
Протестируем клиент и сервер

Шаг 1 — Установка зависимостей

Обновите индекс пакетов и систему:

sudo apt update
sudo apt upgrade

Установите утилиты, которые понадобятся далее (git, wget, make и прочие):

sudo apt install wget curl libtool subversion make automake git -y

Примечание: если у вас уже установлены некоторые пакеты, apt пропустит их.

Шаг 2 — Установка Libuv на Ubuntu 16.04

Libuv — мультиплатформенная библиотека для асинхронного ввода-вывода. Turtl использует её через обёртки для Common Lisp.

Перейдите в рабочую директорию и скачайте релиз Libuv v1.9.1:

cd /usr/local/src
wget http://dist.libuv.org/dist/v1.9.1/libuv-v1.9.1.tar.gz

Распакуйте архив и удалите его:

tar -xf libuv-v1.9.1.tar.gz
rm libuv-v1.9.1.tar.gz

Перейдите в каталог libuv и соберите библиотеку через autotools:

cd libuv-v1.9.1
sh autogen.sh
./configure
make
make install

После успешной сборки библиотеки файлы будут установлены в /usr/local/lib.

Сборка Libuv

Примечание: если make install не обновляет кеш библиотек, выполните:

sudo ldconfig

Шаг 3 — Установка RethinkDB

RethinkDB — документо-ориентированная распределённая БД. Turtl использует её как хранилище данных.

Добавим официальный репозиторий RethinkDB в apt:

echo "deb http://download.rethinkdb.com/apt $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/rethinkdb.list

Добавьте ключ репозитория:

wget -qO- https://download.rethinkdb.com/apt/pubkey.gpg | sudo apt-key add -

Обновите репозитории и установите rethinkdb:

sudo apt update
sudo apt install rethinkdb -y

Скопируйте конфигурацию по умолчанию в каталог instances.d:

cp /etc/rethinkdb/default.conf.sample /etc/rethinkdb/instances.d/default.conf

Перезапустите и включите сервис:

systemctl restart rethinkdb
systemctl enable rethinkdb

Проверьте, что RethinkDB слушает порты:

netstat -plntu

Проверка RethinkDB

Совет: можно открыть веб-интерфейс RethinkDB (обычно порт 8080) для диагностики, но в production ограничьте доступ фаерволом.

Шаг 4 — Установка Clozure Common Lisp (CCL)

Turtl написан на Common Lisp, поэтому нужна реализация CCL. Установим Clozure CCL для Linux x86_64.

Скачайте архив в /usr/local/src:

cd /usr/local/src
wget https://github.com/Clozure/ccl/releases/download/v1.11.5/ccl-1.11.5-linuxx86.tar.gz

Распакуйте и удалите архив:

tar -xf ccl-1.11.5-linuxx86.tar.gz
rm -f ccl-1.11.5-linuxx86.tar.gz

Скопируйте исполняемый скрипт в /usr/local/bin:

cd /usr/local/src/ccl
sudo cp scripts/ccl64 /usr/local/bin/

Проверьте запуск:

ccl64

Вы увидите интерактивную оболочку CCL. Для выхода выполните:

(quit)

Установка Common Lisp

Если ccl64 не запускается, проверьте права на /usr/local/bin/ccl64 и зависимости (glibc и пр.).

Шаг 5 — Установка Quicklisp

Quicklisp — менеджер библиотек для Common Lisp. Turtl загружает зависимости через Quicklisp.

Создайте системного пользователя для запуска Turtl и переключитесь на него:

useradd -m -s /bin/bash turtl
passwd turtl
su - turtl

Скачайте файлы asdf.lisp и quicklisp.lisp в домашнюю папку пользователя turtl:

wget https://common-lisp.net/project/asdf/asdf.lisp
curl -O https://beta.quicklisp.org/quicklisp.lisp

Запустите CCL и загрузите quicklisp.lisp:

ccl64 --load quicklisp.lisp

В интерактивной оболочке установите Quicklisp:

(quicklisp-quickstart:install)

Когда установка завершится, добавьте Quicklisp в init-файл CCL и загрузите asdf.lisp:

(ql:add-to-init-file)
(load (compile-file "asdf.lisp"))
(quit)

Удалите скачанные файлы:

rm -f asdf.lisp quicklisp.lisp

Quicklisp будет хранить локальные проекты в ~/quicklisp/local-projects.

Quicklisp установлен

Важно: запуск ccl64 от имени пользователя turtl должен подхватывать ~/.ccl-init.lisp; если не подхватывает, проверьте путь и права.

Шаг 6 — Скачивание и установка Turtl

Выполните установку под пользователем turtl:

su - turtl
git clone https://github.com/turtl/api.git

Перейдите в каталог и создайте файл launch.lisp:

cd /home/turtl/api
vim launch.lisp

Содержимое launch.lisp:

(pushnew "./" asdf:*central-registry* :test #'equal)
(load "start")

Сохраните и закройте файл.

Склонируйте зависимости в quicklisp/local-projects:

cd ~/quicklisp/local-projects
git clone git://github.com/orthecreedence/cl-hash-util
git clone git://github.com/orthecreedence/vom
git clone git://github.com/orthecreedence/cl-async
git clone git://github.com/orthecreedence/cffi
git clone git://github.com/orthecreedence/wookie
git clone git://github.com/orthecreedence/cl-rethinkdb
git clone git://github.com/orthecreedence/cl-libuv
git clone git://github.com/orthecreedence/drakma-async
git clone https://github.com/Inaimathi/cl-cwd.git

Отредактируйте ~/.ccl-init.lisp, чтобы автоматически загружать проект при старте CCL:

vim /home/turtl/.ccl-init.lisp

Добавьте в конец файла:

(cwd "/home/turtl/api")
(load "/home/turtl/api/launch")

Скопируйте пример конфигурации Turtl и откорректируйте bind-адрес:

cp /home/turtl/api/config/config.default.lisp /home/turtl/api/config/config.lisp
vim /home/turtl/api/config/config.lisp

Найдите строку server-bind и установите локальный адрес:

defvar *server-bind* "127.0.0.1"

Сохраните файл и запустите CCL (под пользователем turtl):

ccl64

При старте CCL автоматически загрузится Quicklisp, затем проект api и будет запущён Turtl. Наблюдайте вывод, пока сервер поднимается. Для выхода из консоли нажмите Ctrl+C.

Проверьте порты:

netstat -plntu

Вы должны увидеть слушающий процесс на 127.0.0.1:8181.

Проверка установки turtl

Совет: для отладки смотрите логи в каталоге проекта и лог RethinkDB.

Шаг 7 — Запуск Turtl как сервиса

Создадим systemd-сервис, чтобы Turtl автоматически запускался и перезапускался.

Создайте файл /lib/systemd/system/turtl.service:

cd /lib/systemd/system/
vim turtl.service

Вставьте:

[Unit]
Description=turtl_service
After=network.target mysql.service postgresql.service

[Service]
User=turtl
ExecStart=/usr/local/bin/ccl64
Restart=always

[Install]
WantedBy=multi-user.target

Сохраните и перезагрузите systemd:

systemctl daemon-reload
systemctl start turtl
systemctl enable turtl
systemctl status turtl

Проверьте, что сервис запущен и перезапускается при падении. При необходимости добавьте в ExecStart дополнительные аргументы или укажите WorkingDirectory=/home/turtl/api.

Сервис turtl запущен

Рекомендация: лучше явно указать WorkingDirectory и Redirect стандартных потоков в файл журнала для упрощения отладки. Пример расширённого блока Service:

[Service]
User=turtl
WorkingDirectory=/home/turtl/api
ExecStart=/usr/local/bin/ccl64 --load /home/turtl/api/launch.lisp
Restart=on-failure
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=turtl

Шаг 8 — Настройка Apache как обратного прокси для Turtl

Мы будем проксировать внешние HTTP-запросы на локальный адрес 127.0.0.1:8181.

Установите Apache и необходимые модули:

sudo apt install -y apache2 apache2-utils apache2-bin libxml2-dev

Включите модули proxy:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_ajp
sudo a2enmod rewrite
sudo a2enmod deflate
sudo a2enmod headers
sudo a2enmod proxy_balancer
sudo a2enmod proxy_connect
sudo a2enmod proxy_html
sudo a2enmod xml2enc

Перезапустите Apache и включите автозапуск:

systemctl restart apache2
systemctl enable apache2

Создайте виртуальный хост /etc/apache2/sites-available/turtl.conf:

cd /etc/apache2/sites-available/
vim turtl.conf

Вставьте конфигурацию (обновите ServerName и ServerAdmin под ваши данные):



ServerName turtl.hakase-labs.co
ServerAdmin [email protected]

ProxyPreserveHost On
ProxyRequests off
ProxyPass / http://127.0.0.1:8181/ Keepalive=On timeout=1600
ProxyPassReverse / http://127.0.0.1:8181/

LogLevel info

CustomLog ${APACHE_LOG_DIR}/turtl.log combined

Активируйте сайт и проверьте конфигурацию Apache:

a2ensite turtl
apachectl configtest
systemctl restart apache2

Проверьте netstat — должен быть слушающий порт 80 (apache) и 8181 (локальный turtl).

Рекомендация по безопасности: в production обязательно включите HTTPS (LetsEncrypt) и настройте HSTS и ограничения по CORS.

Шаг 9 — Тестирование

Скачайте клиент Turtl (доступен для разных платформ) и откройте его.
Нажмите Create an Account и выберите I will remember my login.

Создание аккаунта в turtl

Укажите email, пароль и домен вашего сервера (пример: turtl.hakase-labs.co).

Заполнить пароль и домен

Нажмите Join и пропустите дополнительные шаги при первичной настройке.

Кнопка Join

Вы увидите пустую панель управления, где можно создавать заметки, пароли, файлы и закладки.

Панель Turtl

Если вход успешен и синхронизация работает, установка завершена.

Проверка приёма

Критерии приёмки:

Turtl API слушает на 127.0.0.1:8181
systemd-сервис turtl активен и рестартует приложение при падении
Apache возвращает 200 для корневого запроса (Proxy к локальному серверу)
Клиент Turtl может зарегистрировать и синхронизировать запись
RethinkDB работает и принимает подключения от Turtl

Ролевые чеклисты

Администратор системы:

Проверил наличие свободного места и RAM
Установил и запустил RethinkDB
Установил Libuv и Clozure CCL
Настроил systemd-сервис и сделал его автозапуск
Настроил бэкапы для БД

DevOps-инженер:

Настроил CI для развёртывания конфигураций
Настроил мониторинг процессов и алёрты
Добавил логирование stdout/stderr в централизованную систему

Оператор безопасности:

Настроил HTTPS и перенаправление с HTTP
Ограничил доступ к RethinkDB по IP
Проверил права на каталоги и файлы конфигурации

Мини-методология развёртывания

Подготовка: резервная копия, апдейт системы
Тестовый запуск на VM/контейнере
Настройка persistent storage для RethinkDB
Автоматизация через systemd/Ansible
Перенос в production с постепенным cutover

Отладка и сценарии проблем

Проблема: Turtl не запускается при старте

Проверьте systemctl status turtl и журналы journalctl -u turtl
Убедитесь, что /home/turtl/api доступен пользователю turtl
Запустите ccl64 вручную в директории проекта для просмотра ошибок

Проблема: проксирование Apache возвращает 502

Убедитесь, что локальный порт 8181 открыт и прослушивается
Проверьте логи Apache (${APACHE_LOG_DIR}/turtl.log) и логи Turtl
Проверьте, не блокирует ли firewall 127.0.0.1 (обычно нет)

Проблема: клиент не синхронизируется

Проверьте, что домен в клиенте совпадает с ServerName Apache
Убедитесь, что сертификаты HTTPS корректны (если включены)
Посмотрите логи RethinkDB на предмет ошибок при записи

Инцидентный план (rollback):

Остановить сервис turtl (systemctl stop turtl)
Вернуть конфигурации Apache и /home/turtl/api из резервной копии
Восстановить базу RethinkDB из бэкапа
Запустить сервисы и проверить состояние

Безопасность и жёсткая конфигурация

Всегда включайте HTTPS с валидным сертификатом (Let’s Encrypt). Нельзя экспонировать API без TLS.
Не открывайте RethinkDB напрямую в интернет. Ограничьте доступ через firewall или поместите БД в приватную сеть.
Права: сервис turtl должен запускаться от неправавого пользователя (turtl), каталоги — root: тurtl с правами 750/700.
Регулярно обновляйте компоненты (особенно если переходите на современный дистрибутив).

Тесты и критерии приёмки

Тесты для проверки работоспособности:

E2E: регистрация пользователя через клиент → создание заметки → синхронизация
Unit: запустить ccl64 и загрузить проект без ошибок
Integration: записать запись в RethinkDB и убедиться, что Turtl видит её

Критерий успеха: клиент может создать и синхронизировать заметку без ошибок в логах.

Миграция и совместимость

Для более новых версий Ubuntu используйте пакеты из репозиториев дистрибутива или обновлённые релизы Libuv и CCL.
Для контейнеризации (Docker) вынесите RethinkDB в отдельный сервис-контейнер и запустите CCL/Turtl в другом контейнере с общим сетью.

FAQ

Q: Можно ли использовать PostgreSQL вместо RethinkDB? A: Turtl на момент этой инструкции использует RethinkDB, замена требует значительной переработки кода бекенда.

Q: Как восстановить данные при сбое RethinkDB? A: Делайте регулярные бэкапы данных RethinkDB (snapshot/стандартные инструменты резервного копирования) и тестируйте восстановление.

Ссылки и источники

Официальная документация Turtl Server: https://turtlapp.com/docs/server/
Сообщество и обсуждения: https://community.nethserver.org/

Итог

Установка Turtl Server на Ubuntu 16.04 включает установку Libuv, RethinkDB, Clozure CCL, Quicklisp, развёртывание исходников и настройку Apache как обратного прокси. После запуска проверьте работоспособность через клиент и настройте HTTPS и бэкапы для безопасности и надёжности.

Ключевые рекомендации: запускать сервис от отдельного пользователя, ограничивать доступ к БД, включать HTTPS и автоматизировать развёртывание.