_____ _____ ___|\ \ ___|\ \ / /\ \ | |\ \ | | | || | | | | | |____|| | | | | | ____ | | | | | | | || | | | |\ ___\/ /||____|/____/| | | /____/ || / | | \|___| | /|____|____|/ \( |____|/ \( )/ ' )/ ' ' ' .__ .___ .__ .__ ____ ___.__. ____ | |__ ____ __| _/ ____ | | |__| ____ _/ ___\ < | |_/ ___\ | | \ _/ __ \ / __ | _/ __ \ | | | |_/ ___\ \ \___ \___ |\ \___ | Y \\ ___/ / /_/ | \ ___/ | |__| |\ \___ \___ > / ____| \___ >|___| / \___ >\____ | \___ >|____/|__| \___ > \/ \/ \/ \/ \/ \/ \/ \/ cychedelic is a service-oriented continuous deployment system, developed using the suckless philosophy, which is 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 pushed out by the developers. 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 new 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 has not 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 cychedelic system is made up of various components: - ACID (Automated Container & Image Daemon): Back-end service that monitors sources and interacts with the node's host Docker daemon. - [COMING SOON]: Web front-end for monitoring build jobs and service status. Configuration and Installation ============================== cychedelic is configured by modifying the ACID config file (acid/config.sh). The config is statically baked into the docker image. These changes should be committed and pushed to a git server which is accessible by the node to which you wish to install cychedelic. While configuring cychedelic, keep in mind that in addition to your other docker-based services, cychedelic is also designed to keep itself up-to-date as well. Therefore, future configuration changes and patches to the code may be rolled out by simply pushing them to the repository and branch you specify in your config file. 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 specify a value for --project-name if you have changed the name of "cychedelic" in your config file. cychedelic will launch in the background and begin rebuilding the configured services. The service should persist through reboots of the host. Guest Service Configuration =========================== cychedelic utilizes docker-compose as a configuration medium for guest services. Each entry in the config file corresponds to exactly one docker-compose YML config file. Services are built and executed according to the YML file found in the external git source 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 the ACID config 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 services 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. Security Considerations ======================= 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 server 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! 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 .