trellis
v0.0.7
Tulis Dockerfiles dan pipeline CI di TypeScript.
Teralis adalah alat CI/CD portabel. Dengan Trellis, Anda dapat menentukan Dockerfiles dan pipeline CI/CD di TypeScript, dan menjalankannya di mana saja (secara lokal atau pada platform yang dihosting).
Pertama, instal Deno dengan brew install deno (atau yang sebanding).
Kedua, instal Trellis CLI dengan:
deno install
--allow-run=docker
--allow-net
--allow-write
--allow-env
--allow-read
https://deno.land/x/[email protected]/cli.ts Jalankan trellis --help untuk memverifikasi instalasi Anda:
>>> 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 Ekspor Image apa pun untuk mengaktifkan pembuatan Dockerfile dan pembuatan gambar dengan Trellis.
Misalnya, untuk mendefinisikan image Ubuntu dengan beberapa utilitas berguna yang diinstal, Anda dapat menulis file mod.ts berikut:
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" ,
] ) ; Menjalankan trellis ls mod.ts mencantumkan Gambar yang dapat dibangun:
>>> trellis ls mod.ts
Images:
- buildStage (trellis build --target buildStage) Kita dapat melihat pratinjau Dockerfile yang dihasilkan dengan 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 Kita dapat membangun gambar dengan 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/db112e211de238c035a9fd3bbcbd5c417aafc5ee96a8c24d99d4caf81a759903Ekspor fungsi apa pun dari modul TypeScript untuk mengaktifkan eksekusi tugas dengan Trellis.
Misalnya, untuk menentukan alur CI guna memverifikasi bahwa utilitas baris perintah kami berhasil diinstal, Anda dapat menulis file tasks.ts berikut:
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 ) ,
] ) ;
} Menjalankan trellis ls tasks.ts mencantumkan Tugas yang dapat dieksekusi:
>>> trellis ls tasks.ts
Tasks:
- default (trellis run tasks.ts) Kita dapat menjalankan tugas secara lokal dengan 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 Teralis dapat dikonfigurasi melalui file trellis.config.ts , yang semantik dasarnya dimodelkan setelah Vite.
trellis.config.ts harus berisi satu ekspor default yang terdiri dari pemanggilan defineConfig , seperti ini:
import { defineConfig } from "https://deno.land/x/[email protected]/mod.ts" ;
export default defineConfig ( {
engine : "docker" ,
} ) ; Trellis akan menggunakan trellis.config.ts terdekat, mencari terlebih dahulu di direktori kerja saat ini, dan kemudian di setiap direktori induk berikutnya.
Trellis kompatibel dengan depot.dev, yang dapat digunakan untuk mengaktifkan build yang dipercepat cloud tanpa konfigurasi. Jalankan melalui instalasi Depot ( brew install depot/tap/depot atau serupa, diikuti dengan depot login ), lalu tentukan trellis.config.ts seperti:
import { defineConfig } from "https://deno.land/x/[email protected]/mod.ts" ;
export default defineConfig ( {
engine : {
type : "depot" ,
project : "${YOUR_PROJECT_ID}" ,
} ,
} ) ;Dari sana, semua pembangunan Teralis akan dijalankan melalui Depot.
Trellis berjalan di Deno, menjadikannya instalasi satu langkah di 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 termotivasi oleh pengamatan berikut, yang diambil dari pengalaman memelihara sistem CI/CD dalam container yang besar.
Dockerfile sulit dipelihara . Seiring waktu, sistem besar cenderung mengumpulkan koleksi Dockerfile dengan subbagian serupa, tetapi tidak ada abstraksi bersama.
Dockerfiles yang efisien sulit untuk ditulis . Menulis Dockerfile yang dapat di-cache secara maksimal, dengan jejak minimal, memerlukan keahlian yang signifikan. Misalnya, untuk apt-get install , dokumentasi Docker merekomendasikan hal berikut:
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/ *Perulangan CI/CD terlalu lambat . Alur kerja umum untuk menulis pipeline GitHub Actions baru, Jenkinsfile, dll., adalah melakukan commit, push, menunggu sistem mengakui perubahan Anda, lalu menunggu tugas Anda gagal — puluhan, atau bahkan ratusan kali berturut-turut. Dengan solusi CI yang ada, Anda menulis kode untuk dijalankan pada sistem asing, di luar kendali Anda, tanpa alur kerja pengembangan kelas satu.
Sistem CI/CD menciptakan lock-in yang signifikan . Memindahkan file Jenkinsfiles atau YAML Anda ke GitHub Actions, atau sebaliknya, memerlukan penanganan dengan abstraksi khusus platform.
Teralis memecahkan masalah ini melalui beberapa keputusan desain yang signifikan.
Pertama: Dengan Trellis, Anda menentukan Dockerfiles dan pipeline CI/CD di TypeScript. Ini memberi Anda kekuatan bahasa pemrograman "lengkap" sambil tetap mempertahankan API deklaratif. Dengan TypeScript, kami mendapatkan manfaat berikut:
apt-get install yang rumit dengan tangan.deno.land . Kedua: Teralis membuat eksekusi lokal menjadi primitif kelas satu. CI/CD seharusnya tidak terasa seperti sistem yang sepenuhnya terpisah; seharusnya terasa seperti menjalankan kode. Teralis dibangun di atas Deno dan sangat portabel. Anda dapat menjalankan trellis build secara lokal seperti yang Anda lakukan di GitHub Actions atau di tempat lain. Dengan cara ini, Trellis mengambil inspirasi dari alat seperti Earthly dan Dagger.
Trellis memiliki beberapa tujuan aspirasional yang belum terwujud:
Teralis adalah perpustakaan dan antarmuka baris perintah. Dengan Trellis, Anda mengekspor definisi Image dan fungsi yang dapat dijalankan (disebut "Tugas") dari modul TypeScript Anda, lalu menjalankannya melalui CLI trellis .
trellis previewHasilkan Dockerfile yang ditentukan dalam modul 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 buildBuat Gambar yang ditentukan dalam modul 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 lsDaftar semua Gambar dan Tugas yang tersedia dalam modul TypeScript.
Usage: trellis ls [options] [file]
List all Images and Tasks available in a TypeScript module
Options:
-h, --help display help for commandtrellis runJalankan Tugas yang ditentukan dalam modul 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
Direktori ./examples menunjukkan berbagai kasus penggunaan untuk Trellis. Trellis fleksibel dan hanya dapat digunakan untuk menghasilkan Dockerfiles untuk sistem lain, atau untuk mendefinisikan keseluruhan pipeline CI/CD.
rocket : Server web Rust di atas kerangka Rocket. Mendemonstrasikan pembangunan dan penerapan multi-tahap melalui Fly.io dengan memanfaatkan trellis preview .ruff : Alat baris perintah Rust. Menunjukkan build dan pemeriksaan CI yang efisien.runc : Wadah pengembangan Linux. Mendemonstrasikan pembuatan artefak dengan Trellis dan menyalinnya kembali ke mesin host.turborepo : Contoh Docker milik Turborepo, dimodifikasi untuk menghasilkan Dockerfiles dengan Trellis.typescript : Monorepo TypeScript. Menunjukkan build yang efisien dan pemeriksaan CI, serta mengkonsolidasikan konstanta (seperti daftar ruang kerja TypeScript).wasm : A "Halo, dunia!" Biner karat yang dikompilasi ke Wasm dan diuji di Wasmtime. Teralis dibangun di atas Deno, yang didistribusikan sebagai biner tunggal yang dapat dieksekusi tanpa ketergantungan eksternal. Menggunakan Deno berarti menginstal Trellis di mana saja ) semudah deno install ... — tidak ada package.json , tidak ada npm install , dan tidak ada langkah transpilasi TypeScript.
Mirip dengan Nixpacks, Trellis menghasilkan Dockerfiles. Hal ini menyederhanakan implementasi Trellis, namun juga memungkinkan pengguna memanfaatkan Trellis untuk pembuatan Dockerfile saja, bukan sebagai solusi CI/CD yang lengkap.
trellis build dan trellis run bergantung pada Docker dan berasumsi bahwa daemon Docker dapat diakses secara lokal.
MIT
