diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..6607e90 --- /dev/null +++ b/README.txt @@ -0,0 +1,140 @@ + + _____ _____ + ___|\ \ ___|\ \ + / /\ \ | |\ \ + | | | || | | | + | | |____|| | | | + | | ____ | | | | + | | | || | | | + |\ ___\/ /||____|/____/| + | | /____/ || / | | + \|___| | /|____|____|/ + \( |____|/ \( )/ + ' )/ ' ' + ' + .__ .___ .__ .__ + ____ ___.__. ____ | |__ ____ __| _/ ____ | | |__| ____ + _/ ___\ < | |_/ ___\ | | \ _/ __ \ / __ | _/ __ \ | | | |_/ ___\ + \ \___ \___ |\ \___ | 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 <http://unlicense.org/>. |