_____ _____
___|\ \ ___|\ \
/ /\ \ | |\ \
| | | || | | |
| | |____|| | | |
| | ____ | | | |
| | | || | | |
|\ ___\/ /||____|/____/|
| | /____/ || / | |
\|___| | /|____|____|/
\( |____|/ \( )/
' )/ ' '
'
.__ .___ .__ .__
____ ___.__. ____ | |__ ____ __| _/ ____ | | |__| ____
_/ ___\ < | |_/ ___\ | | \ _/ __ \ / __ | _/ __ \ | | | |_/ ___\
\ \___ \___ |\ \___ | Y \\ ___/ / /_/ | \ ___/ | |__| |\ \___
\___ > / ____| \___ >|___| / \___ >\____ | \___ >|____/|__| \___ >
\/ \/ \/ \/ \/ \/ \/ \/
cychedelic is a service-oriented continuous deployment system, developed using
the suckless philosophy, based on git and docker-compose. There are two main
functionalities which cychedelic aims to provide:
1. Continuous Deployment: Automatically build and deploy services from a git
repository as updates are made available. cychedelic will monitor any number of
git sources which are defined in its central configuration. These services are
deployed to the same node which is running cychedelic.
2. Service image maintenance: Periodically rebuild images from scratch to
incorporate changes from base images and install the latest available packages.
While cychedelic can be configured to pull all images from a registry, it is
primarily intended to act as the build infrastructure, pulling code directly
from git. Maintenance is performed to ensure that services are always running
in an up-to-date environment, even if the code hasn't been updated in a while.
During maintenance, cychedelic will also prune the system of unused containers,
images, etc., but will _never_ delete any docker volumes.
The following components make up cychedelic:
- ACID (Automated Container & Image Daemon): Back-end service that monitors
sources and interacts with the node's host docker daemon.
- DMT (Display for Monitoring log Text): Web front-end for monitoring build jobs
and service status information.
Configuration and Installation
==============================
cychedelic is configured via the following files:
docker-compose.yml (Main service deployment configuration)
acid/config.sh (ACID daemon config / managed service list)
dmt/config.sh (DMT interface config)
Configurations are statically baked into service docker images. Any changes
should be committed and pushed to a git server which is accessible by the node
you wish to install to.
While configuring cychedelic, keep in mind that in addition to your other
services, cychedelic is designed to also keep itself up-to-date as well.
Therefore, future configuration changes or code patches may be rolled out by
simply pushing them to the repository and branch you specify.
To bootstrap an initial installation of cychedelic on a docker host, clone your
configuration on the host and run:
$ docker compose up --detach --build
Note: You may also need to give a value for `--project-name` if you have changed
the name of "cychedelic" in your ACID config file.
cychedelic will launch in the background and begin rebuilding the configured
services. The service should persist through reboots of the host. You may
delete the git clone after running the initial `docker compose up` command.
Managed Services
================
cychedelic utilizes docker-compose as the configuration medium for guest
services. Each entry in $CYCHE_SERVICES (ACID config file) corresponds to one
docker-compose YAML file. Services are built and executed according to the YAML
file found in the external git repositories.
When new entries are added, the corresponding services are brought up the next
time cychedelic is restarted (which is triggered immediately by the config
change). When entries are removed, services are stopped on the next restart.
In general, any property stored in $CYCHE_SERVICES may be seamlessly changed at
any time. However, service name changes should be performed with care. A name
change is seen as the removal of the service, and addition of a new one under
its new name. This will cause the service to use different volumes and
networks, which might break previous behavior.
Especially, renaming the cychedelic entry after initial use is problematic, as
the removal of the old-named entry causes cychedelic to be stopped. At this
point, no further processing will occur without manual intervention.
Monitoring
==========
cychedelic exposes a web interface for monitoring builds and service status.
The jobs display is designed to sync with the server and remain up-to-date while
unattended. This page allows you to see build logs and results in real time, as
well as download full logs for local use. See cychedelic's "docker-compose.yml"
for some required configuration steps necessary to use the DMT web interface.
API
===
Some information available through the interactive web interface is also
queryable through an HTTP API. The following are supported endpoints.
http://YOUR_SERVER/api/status
Returns a JSON object with the following fields:
"version"
String identifying the server version / instance. Its value is
unspecified. However, a changed in the returned value indicates
a change in the server software.
"active"
Boolean which is true if any build job, deployment, or
maintenance task is ongoing. False otherwise.
"job"
Integer specifying the active job number, if any. When no job
is in progress, this value is -1.
"newest"
Integer specifying the most recent job available on the system.
"oldest"
Integer specifying the least recent job available on the
system. It can be assumed that all jobs numbered
`oldest` <= x <= `newest` are available for query.
http://YOUR_SERVER/api/job/{NUMBER}
Returns a JSON object with the following fields:
"job"
Integer specifying the job number. This is {NUMBER} if given.
Otherwise this is the number of the latest available job. All
other fields in the object pertain to this job number.
"hash"
String containing the git commit hash job was initiated from.
"reason"
String specifying the reason which caused this job to execute.
Possible values are:
"event": Usually a push event, but is used for any case
where the deployed version is out-of-date.
"maint": Forced maintenance build (even if deployed version
is up-to-date).
"remove": The service is being uninstalled from the host.
"service"
String containing the name of the service being built.
"time"
Integer specifying the timestamp the job started (UNIX epoch).
"result"
String specifying the outcome of the job. Possible values are:
"active": Job is still executing.
"fail": Job has failed and did not deploy.
"pass": Job has succeeded and is deployed.
"log"
String containing a tail of the raw job log file (log preview).
http://YOUR_SERVER/api/log/{NUMBER}
Returns as plaintext, the full job log of {NUMBER} (if given).
Otherwise, the log of the latest available job is returned.
Security Consideration: Write Access
====================================
Docker compose allows the specification of bind mount volumes from the host into
service containers. cychedelic is not a docker-in-docker solution; it manages
containers on the host as siblings to itself.
Bind mounts can be used to leak information or gain root access on the host
system! This functionality can not be globally disabled, as there are some
legitimate use-cases for mounting host files. For example, cychedelic mounts
the host's docker daemon socket (/var/run/docker.sock) in order to control its
managed containers.
For this reason, users should not allow write access to the repositories used
for cychedelic or its sources by anyone who should not possess root access on
the cychedelic host node!
It may still be safe to pull and run images built and maintained by third
parties. However, it is strongly advised to only use a trusted
docker-compose.yml file, whose access is restricted as above. Please audit your
third party code!
Security Consideration: Read Access
===================================
By default, cychedelic makes the output of `docker-compose build` available to
the public through its web interface for all automated deployments. If these
build logs contain visible secrets, they are leaked!
If this impacts you, one solution is to simply not run the web interface. This
is accomplished by removing its entry in "docker-compose.yml". Similar
information can still be obtained with SSH access by querying the docker daemon
manually.
However, a more granular approach might make more sense. For instance, you
might opt to patch-out the ability to retrive full logs, but still use the web
interface to monitor results. You could configure the log tails to be smaller
than their default size, reducing the risk of information leak while leaving
useful error messages visible. Furthermore, you could even patch-in an
authentication feature, and leave full functionality intact for authorized
users only.
Service Conflict Considerations
===============================
All services are deployed to the host running cychedelic, so any finite,
exclusive resources can not be shared between them. For example, only one
container may listen on a given network port. Plan your infrastructure
accordingly.
This limitation is especially noticable if attempting to host multiple web-based
services on your node, since only one container can bind port 80 or 443. In
this specific case, the use of a reverse HTTP proxy is recommended.
The default docker-compose.yml file provided with cychedelic is written to be
used alongside the nginxproxy/nginx-proxy service. An extra entry in the ACID
config file is required to install this service.
cychedelic is public domain software, per the UNLICENSE <http://unlicense.org/>.
