Развёртывание Odysseus — self‑hosted AI workspace

Руководство по развертыванию Odysseus на Ubuntu 22.04: настройка Python-окружения, установка зависимостей и запуск веб-интерфейса через Docker-Compose.

Средний

Алексей Кузнецов

Системный администратор10 июня 2026 г.4 мин чтения

Требования

Сервер с Ubuntu 22.04 LTS (или Debian 12) и доступом root
Минимум 16 ГБ ОЗУ, 4 CPU, 100 ГБ свободного SSD‑накопителя
Установленный Docker Engine ≥ 24.0 и Docker‑Compose ≥ 2.20
Базовые навыки работы в терминале и с systemd

1. Обновление системы и установка Docker

Сначала убедитесь, что система полностью обновлена. Затем установите официальные пакеты Docker, проверив, что сервис запущен и доступен без sudo.

apt update && apt upgrade -y

apt install -y ca-certificates curl gnupg lsb-release

mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

systemctl enable --now docker

# Проверка версии
docker --version

docker compose version

2. Создание пользователя‑службы и настройка прав

Для предсказуемости и безопасности создаём отдельного системного пользователя odysseus, добавляем его в группу docker и задаём домашний каталог.

useradd -r -m -d /opt/odysseus -s /usr/sbin/nologin odysseus
usermod -aG docker odysseus

# Переключаемся на нового пользователя
su - odysseus

3. Клонирование репозитория Odysseus

Склонируйте официальную ветку main. При необходимости укажите тег релиза, чтобы зафиксировать версию.

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
# При желании checkout конкретного тега, например v1.2.0
# git checkout tags/v1.2.0

4. Настройка переменных окружения

Odysseus использует файл .env для параметров модели, токенов и портов. Скопируйте шаблон и отредактируйте под свои нужды.

cp .env.example .env

# Откройте файл в редакторе nano (или vim)
nano .env

# Примерные параметры:
#   ODY_MODEL=llama3.1‑8b
#   ODY_PORT=8080
#   ODY_DATA_PATH=/opt/odysseus/data
#   ODY_LOG_LEVEL=info
#   ODY_API_KEY=your‑secret‑key   # используется для защиты API

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

5. Создание постоянных томов Docker

Для предсказуемости данных создаём именованные тома, которые будут монтироваться в контейнеры.

docker volume create odysseus_models
docker volume create odysseus_data

6. Запуск Docker‑Compose

Выполните сборку и старт сервисов. systemd‑unit обеспечит автоматический перезапуск при сбоях и после перезагрузки сервера.

docker compose up -d --build

# Проверка статуса контейнеров
docker compose ps

# Логи первого контейнера (backend)
docker compose logs -f backend

7. Создание systemd‑unit для Odysseus

Для предсказуемости работы сервисов создаём unit‑файл, который будет управлять docker‑compose от имени пользователя odysseus.

cat <<'EOF' > /etc/systemd/system/odysseus.service
[Unit]
Description=Odysseus AI workspace
After=network.target docker.service
Requires=docker.service

[Service]
Type=exec
User=odysseus
WorkingDirectory=/opt/odysseus/odysseus
ExecStart=/usr/bin/docker compose up -d --remove-orphans
ExecStop=/usr/bin/docker compose down
Restart=on-failure
TimeoutStartSec=300

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now odysseus.service

# Проверка статуса unit‑а
systemctl status odysseus.service

8. Настройка обратного прокси Nginx (опционально)

Для доступа по HTTPS и защиты API‑ключом рекомендуется разместить Nginx как reverse proxy. Пример конфигурации ниже.

apt install -y nginx

cat <<'EOF' > /etc/nginx/sites-available/odysseus.conf
server {
    listen 80;
    server_name odysseus.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;  # порт из .env
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
EOF

ln -s /etc/nginx/sites-available/odysseus.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

9. Проверка работы веб‑интерфейса

Откройте браузер и перейдите по адресу http://odysseus.example.com (или http://IP:8080, если не используете proxy). Должен отобразиться UI Odysseus. При первом запуске система скачает выбранную модель — процесс может занять от нескольких минут до часа в зависимости от скорости сети.

10. Настройка бэкапа данных

Для надёжности создайте cron‑задачу, которая будет копировать содержимое тома odysseus_data в резервный каталог на TrueNAS (NFS).

apt install -y nfs-common

# Монтируем экспорт из TrueNAS
mkdir -p /mnt/backup_odysseus
mount -t nfs truenas.local:/mnt/pool/backup_odysseus /mnt/backup_odysseus

# Добавляем запись в /etc/fstab для автомонтирования
echo "truenas.local:/mnt/pool/backup_odysseus /mnt/backup_odysseus nfs defaults 0 0" >> /etc/fstab

# Скрипт бэкапа
cat <<'EOF' > /usr/local/bin/odysseus_backup.sh
#!/bin/bash
set -e
TIMESTAMP=$(date +%Y-%m-%d_%H-%M-%S)
BACKUP_DIR="/mnt/backup_odysseus/odysseus_$TIMESTAMP"
mkdir -p "$BACKUP_DIR"
# Копируем данные из тома
docker run --rm -v odysseus_data:/data -v "$BACKUP_DIR":/backup alpine tar czf /backup/odysseus_data.tar.gz -C /data .
EOF
chmod +x /usr/local/bin/odysseus_backup.sh

# Cron: каждый день в 03:00
(crontab -l 2>/dev/null; echo "0 3 * * * /usr/local/bin/odysseus_backup.sh") | crontab -

Развёртывание Odysseus — self‑hosted AI workspace

Пошаговое руководство по установке и запуску Odysseus на Ubuntu 22.04 (или совместимом дистрибутиве). Включает подготовку окружения, установку зависимостей, конфигурацию Docker‑Compose и базовый запуск веб‑интерфейса.

Предварительные требования

Сервер с Ubuntu 22.04 LTS (или Debian 12) и доступом root
Минимум 16 ГБ ОЗУ, 4 CPU, 100 ГБ свободного SSD‑накопителя
Установленный Docker Engine ≥ 24.0 и Docker‑Compose ≥ 2.20
Базовые навыки работы в терминале и с systemd

Шаг 1: 1. Обновление системы и установка Docker

apt update && apt upgrade -y

apt install -y ca-certificates curl gnupg lsb-release

mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

systemctl enable --now docker

# Проверка версии
docker --version

docker compose version

Шаг 2: 2. Создание пользователя‑службы и настройка прав

useradd -r -m -d /opt/odysseus -s /usr/sbin/nologin odysseus
usermod -aG docker odysseus

# Переключаемся на нового пользователя
su - odysseus

Шаг 3: 3. Клонирование репозитория Odysseus

Склонируйте официальную ветку main. При необходимости укажите тег релиза, чтобы зафиксировать версию.

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
# При желании checkout конкретного тега, например v1.2.0
# git checkout tags/v1.2.0

Шаг 4: 4. Настройка переменных окружения

cp .env.example .env

# Откройте файл в редакторе nano (или vim)
nano .env

# Примерные параметры:
#   ODY_MODEL=llama3.1‑8b
#   ODY_PORT=8080
#   ODY_DATA_PATH=/opt/odysseus/data
#   ODY_LOG_LEVEL=info
#   ODY_API_KEY=your‑secret‑key   # используется для защиты API

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

Шаг 5: 5. Создание постоянных томов Docker

Для предсказуемости данных создаём именованные тома, которые будут монтироваться в контейнеры.

docker volume create odysseus_models
docker volume create odysseus_data

Шаг 6: 6. Запуск Docker‑Compose

docker compose up -d --build

# Проверка статуса контейнеров
docker compose ps

# Логи первого контейнера (backend)
docker compose logs -f backend

Шаг 7: 7. Создание systemd‑unit для Odysseus

cat <<'EOF' > /etc/systemd/system/odysseus.service
[Unit]
Description=Odysseus AI workspace
After=network.target docker.service
Requires=docker.service

[Service]
Type=exec
User=odysseus
WorkingDirectory=/opt/odysseus/odysseus
ExecStart=/usr/bin/docker compose up -d --remove-orphans
ExecStop=/usr/bin/docker compose down
Restart=on-failure
TimeoutStartSec=300

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now odysseus.service

# Проверка статуса unit‑а
systemctl status odysseus.service

Шаг 8: 8. Настройка обратного прокси Nginx (опционально)

Для доступа по HTTPS и защиты API‑ключом рекомендуется разместить Nginx как reverse proxy. Пример конфигурации ниже.

apt install -y nginx

cat <<'EOF' > /etc/nginx/sites-available/odysseus.conf
server {
    listen 80;
    server_name odysseus.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;  # порт из .env
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
EOF

ln -s /etc/nginx/sites-available/odysseus.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Шаг 9: 9. Проверка работы веб‑интерфейса

Шаг 10: 10. Настройка бэкапа данных

apt install -y nfs-common

# Монтируем экспорт из TrueNAS
mkdir -p /mnt/backup_odysseus
mount -t nfs truenas.local:/mnt/pool/backup_odysseus /mnt/backup_odysseus

# Добавляем запись в /etc/fstab для автомонтирования
echo "truenas.local:/mnt/pool/backup_odysseus /mnt/backup_odysseus nfs defaults 0 0" >> /etc/fstab

# Скрипт бэкапа
cat <<'EOF' > /usr/local/bin/odysseus_backup.sh
#!/bin/bash
set -e
TIMESTAMP=$(date +%Y-%m-%d_%H-%M-%S)
BACKUP_DIR="/mnt/backup_odysseus/odysseus_$TIMESTAMP"
mkdir -p "$BACKUP_DIR"
# Копируем данные из тома
docker run --rm -v odysseus_data:/data -v "$BACKUP_DIR":/backup alpine tar czf /backup/odysseus_data.tar.gz -C /data .
EOF
chmod +x /usr/local/bin/odysseus_backup.sh

# Cron: каждый день в 03:00
(crontab -l 2>/dev/null; echo "0 3 * * * /usr/local/bin/odysseus_backup.sh") | crontab -

Поделиться:Telegram X / Twitter VK