Миграция со старой версии DashLit

Старые версии DashLit хранили дашборд в dashboard.json. Текущая версия хранит пользователей, дашборды, группы и ссылки в SQLite и умеет импортировать старый файл при создании первого пользователя.

Подготовка

1. Остановите старый контейнер.
2. Сделайте резервную копию всего каталога данных.
3. Сохраните исходный dashboard.json до проверки результата.
4. Запускайте новую версию с пустой базой данных.

Автоматическая миграция предлагается только при отсутствии пользователей. Благодаря этому старый файл не может неожиданно изменить работающую установку.

Размещение файла

Положите dashboard.json рядом с базой SQLite. В стандартном контейнере оба файла находятся в /data:

/data/
├── dashboard.json     # данные старой версии
└── bookmarks.db       # база текущей версии

Если задан нестандартный DATABASE_PATH, JSON должен лежать рядом с указанным файлом, а не просто в DATA_DIR.

Замена старого Docker Compose

Старый docker-compose.yml можно обновить на месте, не создавая отдельное развёртывание. Сначала сохраните копии старого файла и каталога данных, оставьте существующий bind mount с dashboard.json, затем замените старый образ и устаревшие параметры текущим сервисом и добавьте постоянный JWT_SECRET.

Например, если старые данные находятся в ./data:

services:
  dashlit:
    image: ghcr.io/codewec/dashlit:main
    container_name: dashlit
    restart: unless-stopped
    ports:
      - '3000:8080'
    environment:
      JWT_SECRET: '${JWT_SECRET}'
    volumes:
      - ./data:/data

Рядом с Compose-файлом создайте .env с длинным случайным JWT_SECRET. До запуска DashLit проверьте возможность записи в существующий каталог. Самый простой вариант настройки прав:

sudo chmod -R 777 ./data

Для более точечной настройки используйте числовой UID/GID контейнера. После этого обычный пользователь хоста может потерять право записи:

sudo chown -R 10001:10001 ./data
sudo chmod -R 750 ./data

После этого запустите обновлённый сервис командой docker compose up -d. DashLit автоматически найдёт существующий /data/dashboard.json.

Запуск миграции

1. Откройте страницу входа DashLit.
2. Убедитесь, что под формой появилась надпись Legacy version data found.
3. Включите переключатель импорта.
4. Создайте первого пользователя с паролем или через OIDC.
5. DashLit создаст приватный дашборд Legacy dashboard, назначит его первому пользователю и сделает персональным дашбордом по умолчанию.
6. Проверьте группы, ссылки, адреса, описания и иконки.

При OIDC выбор передаётся в краткоживущей HttpOnly-cookie. Данные дашборда и выбор миграции не сохраняются в local storage браузера.

Место для скриншота миграции
Добавьте страницу входа с сообщением и переключателем импорта.

Какие данные переносятся

Сохраняются порядок групп и ссылок, названия и описания групп, а также названия, описания, URL и иконки ссылок.

Старые визуальные поля без аналога в новой модели — цвет иконки, режим отображения URL и target ссылки — не импортируются.

Если предложение миграции не появилось

• Проверьте, что dashboard.json и bookmarks.db находятся в одном каталоге.
• Убедитесь, что файл читается пользователем контейнера с UID/GID 10001.
• При bind mount убедитесь, что каталог доступен для записи; выполните sudo chmod -R 777 ./data или используйте более точечные команды с назначением владельца выше.
• Найдите в логах сообщение об ошибке JSON или неподдерживаемом формате.
• Убедитесь, что пользователь ещё не создан. Поиск выполняется только при запуске сервера с пустой таблицей пользователей.

Если пользователь уже создан, остановите DashLit и восстановите пустую базу до регистрации либо начните с нового каталога данных. Не удаляйте заполненную базу без проверенной резервной копии.

После проверки

После проверки импорта и создания новой резервной копии работающему приложению dashboard.json больше не нужен. Сохраните архивную копию, пока не убедитесь в успешной миграции.