trellis
v0.0.7
Пишите Dockerfiles и конвейеры CI на TypeScript.
Trellis — это портативный инструмент CI/CD. С помощью Trellis вы можете определить свои Dockerfiles и конвейеры CI/CD в TypeScript и запускать их где угодно (локально или на размещенной платформе).
Сначала установите Deno с помощью brew install deno (или аналогичного).
Во-вторых, установите интерфейс командной строки Trellis с помощью:
deno install
--allow-run=docker
--allow-net
--allow-write
--allow-env
--allow-read
https://deno.land/x/[email protected]/cli.ts Запустите trellis --help , чтобы проверить установку:
>>> trellis --help
Usage: trellis build mod.ts
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
ls [file] List all Images and Tasks available in a
TypeScript module
preview [options] [file] Generate a Dockerfile defined in a TypeScript
module
build [options] [file] Build an Image defined in a TypeScript module
run [options] [file] Run a Task defined in a TypeScript module
help [command] display help for command Экспортируйте любое Image , чтобы обеспечить создание файлов Dockerfile и создание изображений с помощью Trellis.
Например, чтобы определить образ Ubuntu с установленными несколькими полезными утилитами, вы можете написать следующий файл mod.ts :
import { Image } from "https://deno.land/x/[email protected]/mod.ts" ;
const UBUNTU_VERSION = "20.04" ;
export const buildStage = Image . from ( `ubuntu: ${ UBUNTU_VERSION } ` )
. workDir ( "/root" )
. aptInstall ( [
"curl" ,
"jq" ,
"git" ,
] ) ; Запустив trellis ls mod.ts вы увидите список создаваемых изображений:
>>> trellis ls mod.ts
Images:
- buildStage (trellis build --target buildStage) Мы можем просмотреть сгенерированный файл Docker с помощью trellis preview mod.ts --target buildStage :
>>> trellis preview --target buildStage
# syntax=docker/dockerfile:1.4
FROM ubuntu:20.04 AS stage-0
WORKDIR /root
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked --mount=type=cache,target=/var/lib/apt,sharing=locked apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends curl git jq Мы можем построить образ с помощью trellis build --target buildStage :
>>> trellis build --target buildStage
[+] Building 0.6s (11/11) FINISHED
= > [internal] load build definition from Dockerfile 0.0s
= > = > transferring dockerfile: 335B 0.0s
= > [internal] load .dockerignore 0.0s
= > = > transferring context: 2B 0.0s
= > resolve image config for docker.io/docker/dockerfile:1.4 0.2s
= > CACHED docker-image://docker.io/docker/dockerfile:1.4@sha256:9ba7531bd80fb0a858632727cf7a112fbf 0.0s
= > [internal] load build definition from Dockerfile 0.0s
= > [internal] load .dockerignore 0.0s
= > [internal] load metadata for docker.io/library/ubuntu:20.04 0.2s
= > [stage-0 1/3] FROM docker.io/library/ubuntu:20.04@sha256:35ab2bf57814e9ff49e365efd5a5935b6915ee 0.0s
= > CACHED [stage-0 2/3] WORKDIR /root 0.0s
= > CACHED [stage-0 3/3] RUN --mount=type=cache,target=/var/cache/apt,sharing=locked --mount=type=c 0.0s
= > exporting to image 0.0s
= > = > exporting layers 0.0s
= > = > writing image sha256:17f750ba9a4becf38ce4d584d0de4793bfd6a8139674c3b332cdcdf6525ea8d9 0.0s
= > = > naming to docker.io/trellis/db112e211de238c035a9fd3bbcbd5c417aafc5ee96a8c24d99d4caf81a759903 0.0s
√ Build: trellis/db112e211de238c035a9fd3bbcbd5c417aafc5ee96a8c24d99d4caf81a759903Экспортируйте любую функцию из модуля TypeScript, чтобы обеспечить выполнение задач с помощью Trellis.
Например, чтобы определить конвейер CI для проверки успешной установки наших утилит командной строки, вы можете написать следующий файл tasks.ts :
import { build , Image , run } from "https://deno.land/x/[email protected]/mod.ts" ;
import { buildStage } from "./mod.ts" ;
export default async function runChecks ( ) {
await build ( buildStage ) ;
const checkCurl = Image . from ( buildStage ) . run (
"curl --help" ,
) ;
const checkJq = Image . from ( buildStage ) . run (
"jq --help" ,
) ;
const checkGit = Image . from ( buildStage ) . run (
"git --help" ,
) ;
await Promise . all ( [
run ( checkCurl ) ,
run ( checkJq ) ,
run ( checkGit ) ,
] ) ;
} При запуске trellis ls tasks.ts выводится список исполняемых задач:
>>> trellis ls tasks.ts
Tasks:
- default (trellis run tasks.ts) Мы можем выполнить задачу локально с помощью trellis run tasks.ts :
>>> trellis run tasks.ts
[+] Building 1.1s (13/13) FINISHED
= > [internal] load build definition from Dockerfile 0.0s
= > = > transferring dockerfile: 335B 0.0s
= > [internal] load .dockerignore 0.0s
= > = > transferring context: 2B 0.0s
= > resolve image config for docker.io/docker/dockerfile:1.4 0.5s
= > [auth] docker/dockerfile:pull token for registry-1.docker.io 0.0s
= > CACHED docker-image://docker.io/docker/dockerfile:1.4@sha256:9ba7531bd80fb0a858632727cf7a112fbf 0.0s
= > [internal] load .dockerignore 0.0s
= > [internal] load build definition from Dockerfile 0.0s
= > [internal] load metadata for docker.io/library/ubuntu:20.04 0.3s
= > [auth] library/ubuntu:pull token for registry-1.docker.io 0.0s
= > [stage-0 1/3] FROM docker.io/library/ubuntu:20.04@sha256:35ab2bf57814e9ff49e365efd5a5935b6915ee 0.0s
= > CACHED [stage-0 2/3] WORKDIR /root 0.0s
= > CACHED [stage-0 3/3] RUN --mount=type=cache,target=/var/cache/apt,sharing=locked --mount=type=c 0.0s
= > exporting to image 0.0s
= > = > exporting layers 0.0s
= > = > writing image sha256:17f750ba9a4becf38ce4d584d0de4793bfd6a8139674c3b332cdcdf6525ea8d9 0.0s
= > = > naming to docker.io/trellis/adf8a603d1ab539848d89f68491e1b9213c1ca498f3f68d871e1b59c4c7de601 0.0s
√ Build: trellis/adf8a603d1ab539848d89f68491e1b9213c1ca498f3f68d871e1b59c4c7de601
√ Run: git --help
√ Run: jq --help
√ Run: curl --help Trellis можно настроить с помощью файла trellis.config.ts , основная семантика которого смоделирована по образцу Vite.
Файл trellis.config.ts должен содержать один экспорт по умолчанию, состоящий из вызова defineConfig , например:
import { defineConfig } from "https://deno.land/x/[email protected]/mod.ts" ;
export default defineConfig ( {
engine : "docker" ,
} ) ; Trellis будет использовать ближайший trellis.config.ts , просматривая сначала текущий рабочий каталог, а затем каждый последующий родительский каталог.
Trellis совместим с depot.dev, который можно использовать для создания облачных ускоренных сборок без необходимости настройки. Запустите установку Depot ( brew install depot/tap/depot или аналогичный, а затем depot login ), затем определите trellis.config.ts следующим образом:
import { defineConfig } from "https://deno.land/x/[email protected]/mod.ts" ;
export default defineConfig ( {
engine : {
type : "depot" ,
project : "${YOUR_PROJECT_ID}" ,
} ,
} ) ;После этого все сборки Trellis будут проходить через Depot.
Trellis работает на Deno, что делает его установку в один шаг на GitHub Actions:
name : CI
on :
push :
branches : [ main ]
pull_request :
branches : [ main ]
env :
DOCKER_BUILDKIT : 1
jobs :
build :
name : " Build "
runs-on : ubuntu-latest
steps :
- uses : actions/checkout@v3
- name : " Install Deno "
uses : denoland/setup-deno@v1
with :
deno-version : " 1.25.2 "
- name : " Install Trellis "
working-directory : ./trellis
run : deno install --allow-run=docker --allow-net --allow-write --allow-env --allow-read https://deno.land/x/[email protected]/cli.ts
- name : " Build the image "
working-directory : ./examples/typescript
run : trellis build trellis/mod.ts В основе Trellis лежат следующие наблюдения, основанные на опыте поддержки больших контейнерных систем CI/CD.
Dockerfiles сложно поддерживать . Со временем большие системы имеют тенденцию накапливать коллекции Dockerfiles со схожими подразделами, но без общих абстракций.
Эффективные Dockerfiles сложно писать . Написание Dockerfile, максимально кэшируемого и занимающего минимальное пространство, требует значительных знаний. Например, для apt-get install документация Docker рекомендует следующее:
RUN apt-get update && apt-get install -y
# Be sure to sort dependencies to maximize cacheability.
bzr
cvs
git
mercurial
subversion
# Clear the apt cache to minimize disk size.
&& rm -rf /var/lib/apt/lists/ *Итерационный цикл CI/CD слишком медленный . Обычный рабочий процесс написания нового конвейера действий GitHub, Jenkinsfile и т. д. — это зафиксировать, отправить, дождаться, пока система подтвердит ваше изменение, а затем дождаться сбоя вашей задачи — десятки или даже сотни раз подряд. Используя существующие решения CI, вы пишете код для запуска в незнакомой системе, вне вашего контроля, без первоклассного рабочего процесса разработки.
Системы CI/CD создают значительную блокировку . Портирование файлов Jenkinsfiles или YAML в GitHub Actions или наоборот требует понимания абстракций, специфичных для платформы.
Trellis решает эти проблемы посредством нескольких важных дизайнерских решений.
Во-первых: с помощью Trellis вы определяете свои Dockerfiles и конвейеры CI/CD в TypeScript. Это дает вам возможность «полноценного» языка программирования, сохраняя при этом декларативный API. Используя TypeScript, мы получаем следующие преимущества:
apt-get install .deno.land . Во-вторых: Trellis делает локальное выполнение первоклассным примитивом. CI/CD не должна ощущаться как совершенно отдельная система; это должно быть похоже на выполнение кода. Trellis создан на базе Deno и отличается высокой портативностью. Вы можете запустить trellis build локально, как и в GitHub Actions или где-либо еще. Таким образом, Trellis черпает вдохновение из таких инструментов, как Earthly и Dagger.
У Trellis есть несколько амбициозных целей, которые еще не реализованы:
Trellis — это одновременно библиотека и интерфейс командной строки. С помощью Trellis вы экспортируете определения Image и выполняемые функции (называемые «Задачи») из модулей TypeScript, а затем выполняете их через интерфейс командной строки trellis .
trellis previewСоздайте файл Dockerfile, определенный в модуле TypeScript.
Usage: trellis preview [options] [file]
Generate a Dockerfile defined in a TypeScript module
Options:
-t, --target < TARGET > Image to build within the TypeScript module
-h, --help display help for commandtrellis buildСоздайте изображение, определенное в модуле TypeScript.
Usage: trellis build [options] [file]
Build an Image defined in a TypeScript module
Options:
-t, --target < TARGET > Image to build within the TypeScript module
--push Whether to push the image to a remote registry
-h, --help display help for commandtrellis lsПеречислите все изображения и задачи, доступные в модуле TypeScript.
Usage: trellis ls [options] [file]
List all Images and Tasks available in a TypeScript module
Options:
-h, --help display help for commandtrellis runЗапустите задачу, определенную в модуле TypeScript.
Run a Task defined in a TypeScript module
Options:
-t, --target <TARGET> Task to run within the TypeScript module
-h, --help display help for command
Каталог ./examples демонстрирует различные варианты использования Trellis. Trellis является гибким и может использоваться исключительно для создания файлов Dockerfile для других систем или для определения целых конвейеров CI/CD.
rocket : веб-сервер Rust на платформе Rocket. Демонстрирует многоэтапную сборку и развертывание через Fly.io с использованием trellis preview .ruff : инструмент командной строки Rust. Демонстрирует эффективные сборки и проверки CI.runc : контейнер разработки Linux. Демонстрирует создание артефактов с помощью Trellis и копирование их обратно на хост-компьютер.turborepo : собственный пример Docker от Turborepo, модифицированный для создания файлов Dockerfile с помощью Trellis.typescript : монорепозиторий TypeScript. Демонстрирует эффективные сборки и проверки CI, а также консолидацию констант (например, список рабочих пространств TypeScript).wasm : «Привет, мир!» Бинарный файл Rust, скомпилированный в Wasm и протестированный на Wasmtime. Trellis построен на основе Deno, который распространяется как один двоичный исполняемый файл без каких-либо внешних зависимостей. Использование Deno означает, что установка Trellis в любом месте так же проста, как deno install ... — здесь нет package.json , npm install и нет этапа транспиляции TypeScript.
Подобно Nixpacks, Trellis генерирует файлы Dockerfile. Это упрощает реализацию Trellis, но также позволяет пользователям использовать Trellis только для создания файлов Dockerfile, а не как полноценное решение CI/CD.
trellis build и trellis run зависят от Docker и предполагают, что демон Docker доступен локально.
Массачусетский технологический институт
