CottonУстановка для новичка

От первого знакомства с сервером до собственного Cotton Cloud.

Разберитесь, чем домашний сервер, NAS и VPS отличаются, зачем нужны Docker и reverse proxy, а затем пройдите один полный сценарий на Ubuntu VPS с постоянной базой PostgreSQL и автоматическим HTTPS.

Ubuntu VPSDocker ComposePostgreSQLHTTPS через CaddyПостоянное хранилищеПервый сервер
С самого начала

Сначала разберёмся в деталях. Потом установим.

Эта инструкция не предполагает, что вы уже администрировали сервер. Сначала разберём все термины и связи, затем пройдём один конкретный путь: VPS с Ubuntu 24.04, Docker Compose и автоматический HTTPS через Caddy.

Выбор компьютера

Сервер — это просто компьютер, который всегда доступен.

Это необязательно стойка в дата-центре. Cotton может жить на компьютере дома или на арендованной виртуальной машине. Важно, где физически лежат файлы, как компьютер выходит в интернет и кто отвечает за его работу.

Ваш обычный компьютер

Подходит для
Коротко попробовать Cotton перед выбором постоянного места.
Главный плюс
Не нужно покупать железо или арендовать VPS.
Что будет сложнее
Cotton выключится вместе с компьютером или при переходе в сон.

Домашний сервер или mini PC

Подходит для
Личное или семейное облако с файлами у вас дома.
Главный плюс
Вы контролируете диски и получаете быструю локальную сеть.
Что будет сложнее
Удалённый доступ, электричество, диски и бэкапы — ваша ответственность.

NAS с поддержкой Docker

Подходит для
Домашний архив, если NAS уже стабильно запускает контейнеры.
Главный плюс
Хранилище и управление дисками уже собраны в одной коробке.
Что будет сложнее
Поддержка Docker и права на папки различаются у производителей NAS.

VPS с Ubuntu

Подходит для
Самый прямой первый запуск в интернете со своим доменом.
Главный плюс
Всегда включён, доступен из интернета и легко заменяется.
Что будет сложнее
Ежемесячная оплата и аренда достаточного места под файлы.
Весь маршрут

Что происходит, когда вы открываете своё облако.

Браузер не подключается напрямую к базе или папке с файлами. DNS находит сервер, Caddy принимает защищённое соединение, а Cotton решает, какие данные прочитать или записать.

Ваш браузер или приложение
защищённый HTTPS
Домен и DNS
указывает на IP
Ваш серверВсё внутри этой рамки работает на вашем сервере
Caddy: вход по HTTPS
передаёт запрос
Cotton: само приложение
читает и записывает
PostgreSQL: пользователи и карта файлов
Хранилище: зашифрованные чанки
Caddy — публичная входная дверь. Cotton — продукт. PostgreSQL и /data/cotton — состояние, которое нельзя терять.
Что переживает перезапуск

Контейнеры можно заменить. Ваши данные — нельзя.

При обновлении Docker обычно заменяет контейнер. Это безопасно только потому, что настоящее состояние хранится за пределами заменяемых контейнеров.

Можно пересоздать

  • Контейнер Caddy
  • Контейнер Cotton
  • Контейнер PostgreSQL

Нужно хранить и бэкапить

  • Volume postgres_data
  • /data/cotton
  • Мастер-ключ
  • Сертификаты Caddy
Бэкап одной базы без /data/cotton не восстановит байты файлов. Зашифрованные файлы без мастер-ключа могут оказаться невосстановимыми.
Зачем Docker

Docker делает установку повторяемой.

Без Docker пришлось бы вручную ставить правильную версию .NET, инструменты PostgreSQL, программы для превью, пользователей, права и обновления. Docker упаковывает приложение, а Compose записывает, как все сервисы запускаются вместе.

Образ

Готовая упаковка приложения. В bvdcode/cotton уже есть Cotton и необходимые ему системные инструменты.

Контейнер

Запущенный экземпляр образа. Его можно остановить или заменить, но он не должен быть единственным местом хранения данных.

Compose

Один YAML-файл, который поднимает PostgreSQL, Cotton и Caddy в общей приватной сети.

Volume или подключённая папка

Хранилище вне заменяемого контейнера. Там постоянно живут база, чанки файлов и сертификаты.

HTTPS

Зачем перед Cotton нужен Caddy или Traefik.

Cotton слушает порт 8080 внутри Docker. Reverse proxy занимает публичные порты 80 и 443, получает TLS-сертификат и передаёт каждый HTTPS-запрос в Cotton. То, что часто называют SSL, сегодня работает как TLS; HTTPS — это обычный веб-трафик, защищённый TLS. Пользователь видит только обычный адрес https://.

Рекомендуется здесь

Caddy

Самый короткий первый запуск: один домен в Caddyfile, после чего сертификат получается и продлевается автоматически.

Для готовой инфраструктуры

Traefik

Удобен, когда один Docker-хост уже раздаёт много сервисов через labels и общие middleware. Для первого Cotton добавляет лишние понятия.

Путь из этой статьи

Один конкретный вариант вместо лабиринта выбора.

Команды ниже рассчитаны на Ubuntu Server 24.04 LTS на VPS. Это не единственный правильный способ, но это понятная база, которую новичок может воспроизвести.

VPS с Ubuntu 24.04

Чистый сервер и пользователь с правом запускать sudo. Размер диска выбирайте с учётом объёма будущих файлов.

Один домен

Например, cloud.example.com. До запуска Caddy вы направите его на IP-адрес сервера.

Доступ по SSH

Провайдер выдаёт IP сервера и пароль или SSH-ключ. SSH — это удалённый терминал для выполнения команд ниже.

Открытые порты 22, 80 и 443

22 нужен для управления по SSH, 80 и 443 — для сертификата и сайта. Порт PostgreSQL 5432 открывать в интернет не надо.

До терминала

Два действия выполняются в кабинетах провайдеров.

Сначала создайте VPS. Затем откройте управление DNS там, где обслуживается ваш домен. Команды в терминале не могут выполнить эти два действия, зависящие от ваших аккаунтов.

1. Создайте VPS

Выберите Ubuntu 24.04 LTS, добавьте SSH-ключ или получите временный пароль и скопируйте публичный IPv4. Регион и размер диска должны подходить вашим пользователям и объёму файлов.

2. Направьте домен на сервер

Создайте A-запись, например cloud.example.com, со значением публичного IPv4 сервера. Обновление DNS может занять время. Пока имя не ведёт на этот VPS, Caddy не сможет получить HTTPS-сертификат.

3. Подключитесь по SSH

Откройте Terminal в macOS/Linux или Windows Terminal в Windows и выполните ssh <пользователь>@<ip-сервера>. Подтверждайте fingerprint только если IP совпадает с только что созданным сервером.

Как понять, что вы подключились

В терминале появилась строка ввода удалённого Ubuntu-сервера. Начиная отсюда все команды выполняются на нём, а не на вашем личном компьютере.

docker-compose.yml

Один файл описывает весь публичный стек.

PostgreSQL хранит базу в именованном volume postgres_data. Cotton хранит зашифрованные чанки и sentinel ключа в /data/cotton. Только Caddy доступен из интернета, а его сертификаты лежат в постоянных volumes.

docker-compose.yml
name: cotton

services:
  postgres:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_DB: cotton
      POSTGRES_USER: cotton
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
    volumes:
      - postgres_data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U cotton -d cotton"]
      interval: 5s
      timeout: 5s
      retries: 20

  cotton:
    image: bvdcode/cotton:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    expose:
      - "8080"
    volumes:
      - /data/cotton:/app/files
    environment:
      COTTON_PG_HOST: postgres
      COTTON_PG_PORT: "5432"
      COTTON_PG_DATABASE: cotton
      COTTON_PG_USERNAME: cotton
      COTTON_PG_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
    security_opt:
      - no-new-privileges:true

  caddy:
    image: caddy:2
    restart: unless-stopped
    depends_on:
      - cotton
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    environment:
      COTTON_DOMAIN: ${COTTON_DOMAIN:?Set COTTON_DOMAIN in .env}
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

volumes:
  postgres_data:
  caddy_data:
  caddy_config:
Caddyfile

Одна строка связывает HTTPS с Cotton.

Caddy читает домен из .env, получает доверенный TLS-сертификат, автоматически продлевает его и передаёт трафик контейнеру Cotton в приватной сети Docker.

Caddyfile
{$COTTON_DOMAIN} {
  reverse_proxy cotton:8080
}
Файл .env

За пределами Compose остаются только два значения.

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

.env
POSTGRES_PASSWORD=<создаётся автоматически>
COTTON_DOMAIN=cloud.example.com
01

1. Установите Docker

Эти команды ставят Docker Engine и Compose из репозиториев Ubuntu, запускают Docker сейчас и включают его после перезагрузки.

Две последние команды выводят версии Docker и Compose. Если хотя бы одна пишет command not found, остановитесь и исправьте установку до следующего шага.
Терминал Ubuntu
sudo apt update
sudo apt install -y docker.io docker-compose-v2 curl nano openssl ufw
sudo systemctl enable --now docker
sudo docker --version
sudo docker compose version
02

2. Создайте постоянные папки и конфигурацию

Команды создают /opt/cotton для конфигурации и /data/cotton для файлов, скачивают два показанных выше файла, записывают случайный пароль базы прямо в .env и открывают домен для редактирования.

В nano замените cloud.example.com на свой домен, нажмите Ctrl+O, Enter и Ctrl+X. Не добавляйте https:// и не ставьте пробелы вокруг =.
Терминал Ubuntu
sudo install -d -m 0750 /opt/cotton /data/cotton
cd /opt/cotton
sudo curl -fsSLo compose.yml https://cottoncloud.dev/install/docker-compose.yml
sudo curl -fsSLo Caddyfile https://cottoncloud.dev/install/Caddyfile
DB_PASSWORD="$(openssl rand -hex 24)"
printf 'POSTGRES_PASSWORD=%s\nCOTTON_DOMAIN=cloud.example.com\n' "$DB_PASSWORD" | sudo tee .env >/dev/null
sudo chmod 600 .env
sudo nano .env
03

3. Откройте только необходимые веб-порты

Сначала оставляем разрешённым SSH, чтобы не отрезать себе доступ. Если у VPS-провайдера есть отдельный облачный firewall, там тоже разрешите TCP 80 и 443.

ufw status показывает разрешённые OpenSSH, 80/tcp и 443/tcp. PostgreSQL 5432 и Cotton 8080 остаются приватными.
Терминал Ubuntu
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
04

4. Проверьте конфигурацию и запустите всё

Compose сначала проверяет файл, затем скачивает образы, запускает три сервиса и показывает их состояние.

postgres становится healthy, cotton и caddy работают. Первая загрузка образов может занять несколько минут. Caddy получает HTTPS после обновления DNS.
Терминал Ubuntu
cd /opt/cotton
sudo docker compose config --quiet
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
05

5. Получите одноразовый bootstrap-токен

Новый Cotton запускается заблокированным, потому что мастер-ключ намеренно не хранится в Docker. В логе сервера появляется короткоживущий токен для первой разблокировки.

Скопируйте только bootstrap-токен. Если он истёк, выполните sudo docker compose restart cotton и прочитайте новый токен.
Терминал Ubuntu
sudo docker compose logs cotton | grep -i "bootstrap token"
Первый запуск

Закончите настройку в браузере без догадок.

Откройте https://cloud.example.com/unlock со своим настоящим доменом. Страница разблокировки появляется раньше обычного приложения, потому что без мастер-ключа Cotton не может читать зашифрованное состояние.

1. Создайте и сохраните мастер-ключ

Нажмите «Сгенерировать», скопируйте 32-символьный ключ в менеджер паролей или офлайн-запись, введите bootstrap-токен и разблокируйте Cotton. Потеря ключа может сделать зашифрованные данные невосстановимыми.

2. Создайте первого администратора

После запуска форма входа сообщит, что пользователей пока нет. Указанные email и пароль создадут первого администратора. Используйте уникальный пароль.

3. Пройдите мастер настройки

Для этого базового сценария выберите локальное хранилище файлов. Ответьте на вопросы об использовании, приватности, email и часовом поясе: интерфейс объясняет варианты, а большинство решений можно изменить позже.

4. Проверьте публичный адрес

В качестве public base URL укажите тот же https:// домен, который будут открывать пользователи. От него зависят ссылки, passkeys, восстановление пароля и OIDC callback.

5. Доверяйте только своему proxy

В настройке trusted proxy запустите проверку наблюдаемого proxy и сохраните предложенную границу Docker bridge. Не разрешайте подмену заголовков с любого адреса в интернете.

После установки

Сделайте это до того, как довериться.

Открывшаяся логин-страница — ещё не финиш.

Включите 2FA

Включите passkeys или TOTP для администратора до того, как инстанс станет доступен извне.

Прогоните проверку безопасности

Админ-проверка подсветит публичную регистрацию, отсутствие 2FA, writable rootfs, проброс Docker socket и не только.

Проверьте сохранность

Перезапустите стек, снова разблокируйте Cotton и убедитесь, что администратор и тестовый файл остались на месте, прежде чем загружать важные данные.

Знайте путь обновления

Проверьте, как вы тянете новый образ и перезапускаетесь без потери базы и хранилища чанков.

Эксплуатация

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

Установке можно доверять, только если вы умеете её обновить и вынести данные для восстановления за пределы сервера. Копия на том же VPS не защищает от потери этого VPS.

Обновить контейнеры

Сначала прочитайте примечания к релизу Cotton. Команды скачивают актуальные образы и пересоздают сервисы, сохраняя именованные volumes и /data/cotton.

Терминал Ubuntu
cd /opt/cotton
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps

Создать дамп PostgreSQL

Команда пишет датированный дамп базы в /var/backups/cotton. Скопируйте этот дамп, /data/cotton, мастер-ключ и /opt/cotton в отдельное хранилище как единый комплект восстановления.

Терминал Ubuntu
sudo install -d -m 0700 /var/backups/cotton
sudo sh -c 'docker compose -f /opt/cotton/compose.yml exec -T postgres pg_dump -U cotton -d cotton -Fc > /var/backups/cotton/postgres-$(date +%F).dump'
Если не открывается

Проверяйте по одному слою.

Не удаляйте volumes и не создавайте новый мастер-ключ ради исчезновения ошибки. Начинайте с первого неработающего звена на схеме выше.

Домен не ведёт на сервер

Проверьте, что A-запись содержит публичный IPv4 вашего VPS. Пока DNS не обновился, Caddy не сможет получить публичный сертификат.

Браузер не подключается

Сначала проверьте firewall провайдера, затем sudo ufw status и sudo docker compose ps. Порты 80 и 443 должны доходить до Caddy.

Caddy работает, но показывает 502

Cotton ещё не готов. Откройте sudo docker compose logs --tail=200 cotton и исправьте первую ошибку запуска — часто это пароль базы или права на хранилище.

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

Это ожидаемо в рекомендуемом режиме разблокировки через браузер. Используйте тот же сохранённый мастер-ключ. Никогда не создавайте новый ключ для существующих зашифрованных данных.

Вопросы

Прямые ответы

Нужно ли понимать Docker, чтобы установить Cotton Cloud?

Не нужно быть Docker-специалистом, но надо понимать три вещи: контейнер запускает приложение, volumes и папки хранят данные после перезапуска, а удаление не того volume может удалить настоящую базу или файлы.

Можно поставить Cotton Cloud на домашний сервер?

Да. Домашний сервер, mini PC или NAS-подобная машина подходят, если они постоянно работают, имеют достаточно диска и входят в нормальную схему бэкапов. Для доступа из интернета всё равно нужны HTTPS и reverse proxy.

Нужен ли домен для установки?

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

Что такое PostgreSQL и зачем он Cotton?

PostgreSQL — это база данных. Cotton хранит там пользователей, дерево папок, записи о файлах, шары, настройки и служебное состояние. Сами большие байты файлов хранятся отдельно как чанки.

Где физически лежат файлы?

Cotton хранит содержимое файлов как чанки в выбранном backend: в постоянной папке на сервере или в S3-совместимом хранилище. Поэтому важно бэкапить и базу, и хранилище чанков.

Чем Caddy отличается от Traefik?

Оба работают как reverse proxy: завершают HTTPS и передают запросы Cotton. Caddy проще для первой установки. Traefik удобен, если существующий Docker-хост уже маршрутизирует много сервисов через labels и общие middleware.

На странице есть рабочие команды установки?

Да. Здесь есть один воспроизводимый путь для VPS с Ubuntu 24.04, скачиваемые Compose- и Caddy-файлы, настройка DNS и firewall, первый запуск в браузере, обновление, команда бэкапа PostgreSQL и диагностика частых проблем.