From 0e5ca160ed5a8cc92f56df6b07f4f1554d62a9f4 Mon Sep 17 00:00:00 2001 From: Malfurious Date: Fri, 17 Nov 2023 06:24:32 -0500 Subject: README ~~.txt~~ Signed-off-by: Malfurious --- README | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.txt | 140 ------------------------------------------------------------- 2 files changed, 140 insertions(+), 140 deletions(-) create mode 100644 README delete mode 100644 README.txt diff --git a/README b/README new file mode 100644 index 0000000..6607e90 --- /dev/null +++ b/README @@ -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 . diff --git a/README.txt b/README.txt deleted file mode 100644 index 6607e90..0000000 --- a/README.txt +++ /dev/null @@ -1,140 +0,0 @@ - - _____ _____ - ___|\ \ ___|\ \ - / /\ \ | |\ \ - | | | || | | | - | | |____|| | | | - | | ____ | | | | - | | | || | | | - |\ ___\/ /||____|/____/| - | | /____/ || / | | - \|___| | /|____|____|/ - \( |____|/ \( )/ - ' )/ ' ' - ' - .__ .___ .__ .__ - ____ ___.__. ____ | |__ ____ __| _/ ____ | | |__| ____ - _/ ___\ < | |_/ ___\ | | \ _/ __ \ / __ | _/ __ \ | | | |_/ ___\ - \ \___ \___ |\ \___ | 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 . -- cgit v1.2.3