dopos / dcape

Pусский | English

dopos/dcape

Деплой приложений с docker-compose и make

Dcape - это инструмент для развёртывания docker-приложений по технологии GitOps, который с помощью make и docker-compose, позволяет решить следующие задачи:

командами make up запускать приложения, использующие
- общий порт (например 80)
- БД
командой git push удаленно разворачивать приложения на одном или нескольких компьютерах
через АПИ или web-интерфейс управлять конфигурациями приложений
ограничивать заданной группой пользователей доступ к интерфейсам управления используемым ПО
обслуживать работу с letsencrypt сертификатами wildcard-доменов
управлять инфраструктурой docker

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

Dcape не является постоянно работающим сервисом.

Приложения

Для решения поставленных задач могут быть использованы docker-образы следующих приложений:

общий порт - traefik
- БД - postgresql
удаленно разворачивать приложения - Woodpecker CI (на каждом компьютере) и на каком-то одном - gitea (или аналог)
управлять конфигурациями - enfist
ограничивать доступ - narra, в качестве группы пользователей используется организация gitea
wildcard-домены - powerdns
управлять инфраструктурой docker - portainer

Зачем dcape?

Все эти приложения распространяются независимо от dcape и могут быть развернуты самостоятельно. При этом, в процессе деплоя может потребоваться выполнить

собственную настройку приложения (БД, первичные данные...)
настройку взаимодействия (адреса для запросов, ключи доступа...)

В максимальном варианте процесс настройки всего комплекса приложений включает задание значений для ~90 параметров. В dcape это количество уменьшено до 3х для некоторых конфигураций.

Примерную схему взаимодействий между приложениями можно посмотреть тут

Dcape позволяет упростить процесс развертывания следующим образом

многие параметры можно рассчитать на основе уже известных
для определения значений параметра можно вызвать внешнюю программу (например, KEY ?= $(shell openssl rand -hex 16; echo))
для определения значений параметра и кода можно использовать программные конструкции (например, ifneq ($(AUTH_TOKEN),))
make позволяет любой параметр переопределить в строке вызова
инструменты dcape доступны при деплое других приложений (см dcape-app-template )
исходный код dcape с учетом настроек всех 8 сервисов - это
- 10 Makefile, всего 485 строк
- 17 YAML, всего 502 строки

Документация

См. dopos.github.io/dcape

Зависимости

linux + sudo apt -y install git make sed curl jq
docker + sudo apt -y install docker-compose-plugin

Примеры использования

Запуск приложения локально

Требования:

компьютер с linux, docker и dcape
зарегистрированные (в /etc/hosts или внутреннем DNS) имена для ip компьютера (например - mysite.dev.test, www.mysite.dev.test)

Пример для статического сайта и nginx

git clone https://github.com/dopos/dcape-app-nginx-sample.git
cd dcape-app-nginx-sample
make config-if
# <edit .env>
make up

Все готово - http://mysite.dev.test/ и http://www.mysite.dev.test/ запущены.

Запуск приложения удаленно

Установка dcape

Требования:

компьютер с linux, docker и установленными зависимостями
зарегистрированный в DNS для ip этого компьютера wildcard-домен (например - *.srv1.domain.tld)

Конфигурация с локальным gitea

MY_HOST=demo.dcape.ru
MY_IP=${MY_IP:-192.168.23.10}
LE_ADMIN=admin@dcape.ru

git clone https://github.com/dopos/dcape.git
cd dcape
make install ACME=wild DNS=wild DCAPE_DOMAIN=${MY_HOST} \
  TRAEFIK_ACME_EMAIL=${LE_ADMIN} PDNS_LISTEN=${MY_IP}:53
make echo-gitea-admin-pass

Конфигурация с удаленным gitea

Дополнительные требования для регистрации приложений на удаленном gitea

$AUTH_TOKEN для gitea API

MY_HOST=${MY_HOST:-srv1.domain.tld}
LE_ADMIN=${LE_ADMIN:-admin@domain.tld}
GITEA_URL=${GITEA_URL:-https://git.domain.tld}
GITEA_ORG=${GITEA_ORG:-dcape}
GITEA_USER=${GITEA_USER:-dcapeadmin}

git clone https://github.com/dopos/dcape.git
cd dcape
make install ACME=wild DNS=wild DCAPE_DOMAIN=${MY_HOST} \
  TRAEFIK_ACME_EMAIL=${LE_ADMIN} \
  NARRA_GITEA_ORG=${GITEA_ORG} \
  CICD_ADMIN=${GITEA_USER} \
  PDNS_LISTEN=${MY_IP}:53 \
  GITEA=${GITEA_URL} \
  AUTH_TOKEN=${AUTH_TOKEN}
make echo-gitea-admin-pass

Все готово - сервер srv1.domain.tld готов к деплою приложений, интерфейсы приложений dcape доступны по адресу https://srv1.domain.tld.

Использование

Команды (targets) Makefile. Актуальный список: make[ help].

Git commands

    git-%           run git for every app. Sample: make git-status-s

Docker-compose commands

    build-compose   create docker-compose image 
    ps              show stack containers 
    up              (re)start container(s) 
    up-%            start container 
    reup-%          restart container 
    reup            restart container(s) 
    down            stop (and remove) container(s)

Database commands

    psql            exec psql inside db container 
    db-create       create database and user 
    db-drop         drop database and user 
    psql-docker     exec psql inside db container from apps. Example: make psql-docker DCAPE_STACK=yes
    psql-local      run local psql from apps. Example: make psql-local DCAPE_STACK=yes PGPORT=5433

App config storage commands

    env-get         get env tag from store, `make env-get TAG=app--config--tag` 
    env-ls          list env tags in store 
    env-set         set env tag in store, `make env-set TAG=app--config--tag`

OAuth2 setup

    oauth2-org-create create VCS org via VCS API 
    oauth2-app-create create OAuth2 app via VCS API

.env operations

    config          generate sample config 
    config-force    generate sample config and rename it to .env 
    config-if       generate sample config and rename it to .env if not exists

Other

    echo-%          print config var. Sample: make echo-gitea-admin-pass
    clean-noname    delete unused docker images w/o name (you should use portainer for this)
    clean-volume    delete docker dangling volumes (you should use portainer for this)
    help            list Makefile targets (this is default target)

Переменные

Имя	По умолчанию	Описание
DCAPE_DOMAIN	dev.test	dcape containers hostname domain
DCAPE_ROOT	$(PWD)	dcape root directory
DCAPE_TAG	dcape	container name prefix
DCAPE_ADMIN_USER	dcapeadmin	CICD_ADMIN - CICD admin user GITEA_ADMIN_NAME - Gitea admin user name
DCAPE_ADMIN_ORG	dcape	VCS OAuth app owner group * NARRA_GITEA_ORG - user group with access to auth protected resources * config oauth app owner * CICD oauth app owner
APPS	-	dcape apps calculated by install used in make only

Лицензия

The MIT License (MIT), see LICENSE.