Skip to content

dopos/dcape

Repository files navigation

Pусский | English


dopos/dcape

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

GitHub Release GitHub code size in bytes GitHub license Hits

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

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

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

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

Приложения

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

  • общий порт - traefik
  • удаленно разворачивать приложения - 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} \
  DCAPE_ADMIN_ORG=${GITEA_ORG} \
  DCAPE_ADMIN_USER=${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 & gitea admin user
DCAPE_ADMIN_ORG dcape user group with access to auth protected resources
APPS - dcape apps
calculated by install
used in make only

Лицензия

The MIT License (MIT), see LICENSE.

Copyright (c) 2017-2024 Алексей Коврижкин lekovr+dopos@gmail.com