conductor.md (3690B)
1 # conductor 2 3 A small CI server. Accepts triggers, schedules jobs, serves the worker 4 API and renders the interface. One service, one image. 5 6 Source and issues: https://github.com/finwo/conductor 7 8 ## Tags 9 10 | Tag | What it is | 11 | ---------------- | ------------------------------------------ | 12 | `latest` | the most recent release | 13 | `0.4.0` | an exact version | 14 | `0.4` | the latest patch of that minor series | 15 | `<commit>` | an exact build from main, twelve hex chars | 16 17 Built for `linux/amd64`, `linux/arm64` and `linux/riscv64`. 18 19 **Upgrade the conductor and its workers together.** In 0.3.0 a job became 20 one run of a pipeline and a task became the unit a worker runs. Workers 21 claim from `/api/v1/tasks/claim`, so a 0.2.x worker will not run anything 22 for a 0.3 or newer conductor. 23 24 ## Quick start 25 26 ```sh 27 docker run -d \ 28 --name conductor \ 29 -p 8080:8080 \ 30 -v conductor-data:/data \ 31 -e CONDUCTOR_PUBLIC_URL=http://localhost:8080 \ 32 finwo/conductor 33 ``` 34 35 The administrator password is printed once in the log on first start. 36 Set `CONDUCTOR_ADMIN_PASSWORD` to choose it instead. 37 38 Tasks need a worker, which is a separate image: see 39 [finwo/conductor-worker](https://hub.docker.com/r/finwo/conductor-worker). 40 A compose file running both is in the repository under `deploy/`. 41 42 ## State 43 44 Everything lives in `/data`, so mount a volume there: 45 46 ``` 47 /data/conductor.db sqlite, unless a database url is configured 48 /data/mirrors one bare git mirror per project 49 /data/logs the live log spool 50 /data/storage artifacts and archived logs, unless S3 is configured 51 ``` 52 53 ## Configuration 54 55 Every setting has a default and can come from the environment, so no 56 configuration file is needed. Worth setting in production: 57 58 | Variable | Why | 59 | -------------------------- | ------------------------------------------------ | 60 | `CONDUCTOR_PUBLIC_URL` | Workers get absolute callback URLs built from it. | 61 | `CONDUCTOR_SESSION_SECRET` | Otherwise sessions end at every restart. | 62 | `CONDUCTOR_SECRET_KEY` | Otherwise stored secrets are kept in the clear. | 63 | `CONDUCTOR_ADMIN_PASSWORD` | Otherwise one is generated and logged once. | 64 65 Generate the two secrets with `openssl rand -hex 32`. 66 67 Postgres or MySQL instead of sqlite: 68 69 ```sh 70 -e CONDUCTOR_DATABASE_URL=postgres://conductor:secret@postgres:5432/conductor 71 ``` 72 73 S3 compatible storage instead of the volume: 74 75 ```sh 76 -e CONDUCTOR_S3_ENDPOINT=http://minio:9000 \ 77 -e CONDUCTOR_S3_BUCKET=conductor \ 78 -e CONDUCTOR_S3_ACCESS_KEY_ID=... \ 79 -e CONDUCTOR_S3_SECRET_ACCESS_KEY=... 80 ``` 81 82 Artifacts and finished logs then go to the bucket, and downloads are 83 handed over with a presigned redirect rather than proxied. 84 85 ## Retention 86 87 Build output is deleted on a schedule, or a busy server fills its disk 88 with logs nobody will read. The defaults keep artifacts for 30 days or 89 the last 10 jobs, and logs for 14 days, and a project may override any of 90 it. Upgrading an installation that has been running for a while will 91 delete a lot on the first sweep, so set these before starting if that 92 matters: 93 94 ```sh 95 -e CONDUCTOR_RETENTION_ARTIFACT_DAYS=0 \ 96 -e CONDUCTOR_RETENTION_LOG_DAYS=0 97 ``` 98 99 Zero means keep forever. 100 101 ## Documentation 102 103 - [Deployment](https://github.com/finwo/conductor/blob/main/docs/deployment.md) 104 - [Pipelines](https://github.com/finwo/conductor/blob/main/docs/pipeline.md) 105 - [Workers](https://github.com/finwo/conductor/blob/main/docs/worker.md) 106 - [HTTP API](https://github.com/finwo/conductor/blob/main/docs/api.md)