trellis
v0.0.7
Écrivez des Dockerfiles et des pipelines CI en TypeScript.
Trellis est un outil CI/CD portable. Avec Trellis, vous pouvez définir vos pipelines Dockerfiles et CI/CD dans TypeScript et les exécuter n'importe où (localement ou sur une plateforme hébergée).
Tout d’abord, installez Deno avec brew install deno (ou comparable).
Deuxièmement, installez la CLI Trellis avec :
deno install
--allow-run=docker
--allow-net
--allow-write
--allow-env
--allow-read
https://deno.land/x/[email protected]/cli.ts Exécutez trellis --help pour vérifier votre installation :
>>> 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 Exportez n’importe quelle Image pour activer la génération de Dockerfile et la création d’images avec Trellis.
Par exemple, pour définir une image Ubuntu avec quelques utilitaires utiles installés, vous pouvez écrire le fichier mod.ts suivant :
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" ,
] ) ; L'exécution trellis ls mod.ts répertorie les images constructibles :
>>> trellis ls mod.ts
Images:
- buildStage (trellis build --target buildStage) Nous pouvons prévisualiser le Dockerfile généré avec 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 Nous pouvons construire l'image avec 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/db112e211de238c035a9fd3bbcbd5c417aafc5ee96a8c24d99d4caf81a759903Exportez n'importe quelle fonction d'un module TypeScript pour activer l'exécution de tâches avec Trellis.
Par exemple, pour définir un pipeline CI afin de vérifier que nos utilitaires de ligne de commande ont été installés avec succès, vous pouvez écrire le fichier tasks.ts suivant :
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 ) ,
] ) ;
} L'exécution trellis ls tasks.ts répertorie les tâches exécutables :
>>> trellis ls tasks.ts
Tasks:
- default (trellis run tasks.ts) Nous pouvons exécuter la tâche localement avec 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 peut être configuré via un fichier trellis.config.ts , dont la sémantique de base est calquée sur Vite.
Le trellis.config.ts doit contenir une seule exportation par défaut consistant en un invocation defineConfig , comme ceci :
import { defineConfig } from "https://deno.land/x/[email protected]/mod.ts" ;
export default defineConfig ( {
engine : "docker" ,
} ) ; Trellis utilisera le trellis.config.ts le plus proche, en recherchant d'abord dans le répertoire de travail actuel, puis dans chaque répertoire parent suivant.
Trellis est compatible avec depot.dev, qui peut être utilisé pour activer des builds accélérés par le cloud sans configuration. Exécutez l'installation du dépôt ( brew install depot/tap/depot ou similaire, suivi de depot login ), puis définissez un trellis.config.ts comme ceci :
import { defineConfig } from "https://deno.land/x/[email protected]/mod.ts" ;
export default defineConfig ( {
engine : {
type : "depot" ,
project : "${YOUR_PROJECT_ID}" ,
} ,
} ) ;À partir de là, toutes les versions de Trellis passeront par Depot.
Trellis fonctionne sur Deno, ce qui en fait une installation en une seule étape sur 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 est motivé par les observations suivantes, tirées de l'expérience de la maintenance de grands systèmes CI/CD conteneurisés.
Les fichiers Docker sont difficiles à maintenir . Au fil du temps, les grands systèmes ont tendance à accumuler des collections de fichiers Docker avec des sous-sections similaires, mais sans abstractions partagées.
Les Dockerfiles efficaces sont difficiles à écrire . L'écriture d'un Dockerfile pouvant être mis en cache au maximum, avec un encombrement minimal, nécessite une expertise significative. Par exemple, pour apt-get install , la documentation Docker recommande ce qui suit :
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/ *La boucle itérative CI/CD est trop lente . Le flux de travail courant pour écrire un nouveau pipeline d'actions GitHub, un fichier Jenkins, etc. consiste à valider, pousser, attendre que le système reconnaisse votre modification, puis attendre que votre tâche échoue - des dizaines, voire des centaines de fois de suite. Avec les solutions CI existantes, vous écrivez du code pour l'exécuter sur un système inconnu, hors de votre contrôle, sans un workflow de développement de premier ordre.
Les systèmes CI/CD créent un verrouillage important . Le portage de vos fichiers Jenkins ou YAML vers GitHub Actions, ou vice versa, nécessite de gérer des abstractions spécifiques à la plate-forme.
Trellis résout ces problèmes grâce à quelques décisions de conception importantes.
Premièrement : avec Trellis, vous définissez vos pipelines Dockerfiles et CI/CD dans TypeScript. Cela vous donne la puissance d'un langage de programmation « complet » tout en conservant une API déclarative. Avec TypeScript, nous bénéficions des avantages suivants :
apt-get install .deno.land . Deuxièmement : Trellis fait de l'exécution locale une primitive de première classe. CI/CD ne devrait pas ressembler à un système entièrement distinct ; cela devrait ressembler à exécuter du code. Trellis est construit sur Deno et hautement portable. Vous pouvez exécuter trellis build localement comme vous le feriez sur GitHub Actions ou ailleurs. De cette façon, Trellis s'inspire d'outils comme Earthly et Dagger.
Trellis a quelques objectifs ambitieux qui ne sont pas encore réalisés :
Trellis est à la fois une bibliothèque et une interface de ligne de commande. Avec Trellis, vous exportez des définitions Image et des fonctions exécutables (appelées « Tâches ») à partir de vos modules TypeScript, puis vous les exécutez via la CLI trellis .
trellis previewGénérez un Dockerfile défini dans un module 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 buildCréez une image définie dans un module 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 lsRépertoriez toutes les images et tâches disponibles dans un module TypeScript.
Usage: trellis ls [options] [file]
List all Images and Tasks available in a TypeScript module
Options:
-h, --help display help for commandtrellis runExécutez une tâche définie dans un module 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
Le répertoire ./examples présente une variété de cas d'utilisation pour Trellis. Trellis est flexible et peut être utilisé uniquement pour générer des fichiers Docker pour d'autres systèmes ou pour définir des pipelines CI/CD entiers.
rocket : Un serveur Web Rust au sommet du framework Rocket. Démontre les constructions et le déploiement en plusieurs étapes via Fly.io en tirant parti trellis preview .ruff : Un outil de ligne de commande Rust. Démontre des builds et des vérifications CI efficaces.runc : Un conteneur de développement Linux. Montre la génération d’artefacts avec Trellis et leur copie sur la machine hôte.turborepo : propre exemple Docker de Turborepo, modifié pour générer des Dockerfiles avec Trellis.typescript : Un monorepo TypeScript. Démontre des builds et des vérifications CI efficaces, ainsi que des constantes de consolidation (comme la liste des espaces de travail TypeScript).wasm : Un "Bonjour tout le monde !" Binaire Rust compilé sur Wasm et testé sur Wasmtime. Trellis est construit sur Deno, qui est distribué sous la forme d'un seul exécutable binaire sans dépendances externes. Utiliser Deno signifie qu'installer Trellis n'importe où ) est aussi simple que deno install ... — il n'y a pas package.json , pas npm install et pas d'étape de transpilation TypeScript.
Semblable à Nixpacks, Trellis génère des Dockerfiles. Cela simplifie la mise en œuvre de Trellis, mais permet également aux utilisateurs d'exploiter Trellis pour la génération de fichiers Docker uniquement, plutôt que comme une solution CI/CD complète.
trellis build et trellis run dépendent de Docker et supposent que le démon Docker est accessible localement.
MIT
