diff --git a/README.md b/README.md index bcaeccb..21b2b00 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ custom Dockerfiles in order to use a program. Some of the upcoming changes include: * Pulling supervisor from the containers. - * Radial will strictly uphold the one process per container principal as it + * Radial will strictly uphold the one process per container principle as it is much easier now to send signals, enter container processes, and link containers to each other. There is less and less evidence in my experience to warrent having multiple processes in a container ever. @@ -58,7 +58,7 @@ processes in a server cluster. ## What Can I Do With It? -Radial is a container topology strategy that is is outlined in this +Radial is a container topology strategy that is outlined in this documentation and is implemented in the suite of accompanying Docker [images](https://index.docker.io/u/radial/) and Dockerfiles that this project supplies. Since Radial deals entirely with how you spread your application stack @@ -66,7 +66,7 @@ across containers, it is intended to be compatible with all orchestration, PAAS, and cluster management tools without requiring or locking you into any single one of them. If you like to use these images manually, they should be able to scale up with you into complex cluster use. Hopefully, there are some good ideas -are in here for you to use or replicate. Better still, hopefully these images +in here for you to use or replicate. Better still, hopefully these images themselves will serve you well in all your use. ## What's The Strategy? @@ -84,7 +84,7 @@ and combine configuration, and Supervisor to manage our all our processes and glue it all together. Radial makes configuration a first-class citizen by stripping it out of the -application container and putting it in it's own container (named the "hub") +application container and putting it in its own container (named the "hub") which is later mounted into the application container (the "spoke"). This allows interchangeable and modular application containers for many use cases. diff --git a/concepts/factors.md b/concepts/factors.md index 16849ec..641e739 100644 --- a/concepts/factors.md +++ b/concepts/factors.md @@ -9,7 +9,7 @@ how Radial helps to fulfil certain 12-factor principles using Docker features. Docker images make this a breeze. Dockerfiles reproduce a build on any machine and sharing them is straightforward across machines. Where Radial adds to this -principal, is that it specifies a container solely for the application itself, +principle, is that it specifies a container solely for the application itself, separate from any configuration or environment information to make this more modular. This is the spoke container. @@ -49,7 +49,7 @@ separate from the application in the spoke container, one can easily use the same Docker image for any situation. No need to make an entirely separate image just because you want to change configuration settings. This isn't specific to this 12-factor principle, but this is especially useful when dealing with -database services, which usually a little more complex to setup. +database services, which usually a little more complex to set up. ## Build-Release-Run @@ -63,7 +63,7 @@ run`. The component of this principle that Radial helps with is the "release" stage; the combining of application with configuration. Because configuration and application code are represented by their own containers, all it takes is a -simple `--volumes-from` commands to link up a spoke container to it's +simple `--volumes-from` commands to link up a spoke container to its configuration in the hub. This combination can be very quick to implement because we don't require a build step just to change configuration. Already have a working configuration that you want to test with a new version of the binary? @@ -73,7 +73,7 @@ easily be pieced back together in case of rollback. ## Concurrency -While concurrency is more about designing a stateless app then it is about how +While concurrency is more about designing a stateless app than it is about how you organize your containers, I feel that Radial's modular design helps encourage this. Because configuration is stored in the hub container, and because volume sharing is done predictably (hub does `--volumes-from` axles, @@ -87,7 +87,7 @@ run multiple identical instances of already existing spoke containers. >Maximize robustness with fast startup and graceful shutdown Radial uses small and modular images for quick startup, -[Supervisord][supversior] for in container process management of one or more +[Supervisord][supervisor] for in container process management of one or more running processes within the container itself, and carefully designed entrypoint scripts to facilitate proper transfer of UNIX signals from the docker daemon and enforce proper behavior of container start, restart, and shutdown procedures. @@ -120,8 +120,8 @@ folders are created that allow for any number of spokes to write logs here without name collisions. The idea is simple, if we can make all the logs available in a predictable location, we can use whatever logging program we want later to turn these log files into a stream. The log harvesting itself is a -feature for it's own spoke container, and Radial doesn't make that decision for -you by baking in the log management into it's containers. +feature for its own spoke container, and Radial doesn't make that decision for +you by baking in the log management into its containers. ## Admin Processes @@ -131,7 +131,7 @@ Radial spoke containers allow for a standard daemon mode as well as a custom entrypoint-like command mode that allows one to specify an alternate behavior for that spoke container. This feature allows one to use the same spoke container to run a database (say postgresql) and manage it directly using -it's management program such as `psql`. This keeps the environment between the +its management program such as `psql`. This keeps the environment between the admin process and the app identical. To further simplify this task, Radial organizes all Supervisord unix sockets as diff --git a/concepts/topology.md b/concepts/topology.md index 9d0e3a5..40b9760 100644 --- a/concepts/topology.md +++ b/concepts/topology.md @@ -5,14 +5,14 @@ mature, manual lifecycle tasks of a cluster of containers was a bit of a mess. I wanted to streamline my understanding of application stack components and fit them to Docker features intuitively and systematically. Even now with tools like [Fig][fig], [Kubernetes][kube], and others, I'm finding these topology -principals very easy to transfer no matter the orchestration tool. +principles very easy to transfer no matter the orchestration tool. One challenge I frequently came across early on was related to inconsistency in the Docker Index regarding how each repository's config/data/log logic was carried out in each of the containers. The stated goal of the Docker Index is portability and sharing, and while the sharing part is built-in, the portability part was lacking to me. There were very few images I could literally `docker -pull` and feel confident that it was setup the way I wanted and the image would +pull` and feel confident that it was set up the way I wanted and the image would behave in a predictable manner. I found myself reconstructing the image almost every single time I wanted to use someone else's image due to my specific configuration needs. Unless individuals used strategies similar to those used in @@ -22,7 +22,7 @@ a bit unfulfilled to me. Thus, for Radial, I've used the imagery of a wheel to help conceptually keep things simple. Just like a real wheel, the main parts of a Radial "wheel" are specialized containers each labeled an "axle", a "hub", and a "spoke" container -that each serves a specific purposes in our topology. Typifying containers this +that each serves a specific purpose in our topology. Typifying containers this way allows us to manage our configuration files, our data/code, and our logs in an easy to remember way. With this axle-hub-spoke strategy, we have a predictable method for the ways that: @@ -53,7 +53,7 @@ persistent containers and services. Specifically, axle containers: log storage. Another is a data set that could be created by one container, collated by other, and displayed/hosted by a third on a website. * can include bind-mount volumes unique to specific hosts. An example of this - would be a music/video library that needs to be available normally to to some + would be a music/video library that needs to be available normally to some desktop workstation as well as served/worked managed through some process in the cluster. @@ -62,7 +62,7 @@ persistent containers and services. Specifically, axle containers: Hub containers are a type of volume container with three purposes: * Managing, storing, and versioning configuration and static files -* Creating/storing/persisting all new volumes needed for it's respective spoke +* Creating/storing/persisting all new volumes needed for its respective spoke container (application or running process) in a typical [volume container](http://crosbymichael.com/advanced-docker-volumes.html) fashion. @@ -90,7 +90,7 @@ always assume that: directory) is in `/data` * and that the location of the logs will be in `/log` -All a spoke container needs to do is be run with `--volumes-from` it's +All a spoke container needs to do is be run with `--volumes-from` its respective hub container and all of the above will be accessible to it. A spoke containers purpose is to manage, store, version, and run the app/code/process. It should: @@ -106,7 +106,7 @@ It should: configuration and hosting sockets between the web server, database, and web app spoke containers) * Should blissfully assume the standardized locations for configuration, for - data, and for logs via it's use of `--volumes-from` the hub container. + data, and for logs via its use of `--volumes-from` the hub container. Designing spoke containers this way encourages safer application containers because it doesn't attempt to make any user-friendly/configuration/security @@ -115,8 +115,8 @@ trade-offs. ## Wheels With the above responsibilities delegated amongst the three types of containers, -our application stack can be fully modularized. All-together, an instance of any +our application stack can be fully modularized. Altogether, an instance of any combination of axles, a single hub, and any number of spoke containers can be -referred to as a "wheel" and [packaged all-together](/design/wheels.md) as such. At -the moment, wheels designed to be an atomic unit that is located on a single +referred to as a "wheel" and [packaged altogether](/design/wheels.md) as such. At +the moment, wheels are designed to be an atomic unit that is located on a single host. diff --git a/design/filesystem.md b/design/filesystem.md index cedbf01..9c9186b 100644 --- a/design/filesystem.md +++ b/design/filesystem.md @@ -15,12 +15,12 @@ additional items. build time. * All static data that is persisted in typical [volume container](http://crosbymichael.com/advanced-docker-volumes.html) fashion - should find it's way to a sub-directory of `/data`. This directory is also a + should find its way to a sub-directory of `/data`. This directory is also a catch-all for caching and other runtime data that could typically be thrown somewhere in a users `/home` directory. Effectively, this directory is a combination of `/mnt`, `/opt`, `/home`, and `/var`. * All logs are written to `/log` in a sub-folder that is named after the - container ID. Since `/log` is typically it's own axle container, this + container ID. Since `/log` is typically its own axle container, this directory could potentially collect the logs of many wheels across a single host, or even across an entire small cluster of hosts. Thus, the naming of each folder is the same as the spoke containers short ID to prevent @@ -43,7 +43,7 @@ In more detail: paths are not standardized from the onset. * It's pretty standard for programs to support a custom configuration path at runtime so we leverage this common option to our advantage and always point - our binaries configuration to it's own location in `/config`. + our binary's configuration to its own location in `/config`. ## Why `/data`? @@ -52,7 +52,7 @@ different default paths for their data directories, and many of those same services using different locations even between operating system installations, we want to know that there is a 100% guaranteed match and consistency between our persistent volume storage hub container and our application spoke container. -We want piece of mind that as long as we specify either at run time or in our +We want peace of mind that as long as we specify either at run time or in our configuration that the data directory resides at `/data` we are good to go with no questions asked. diff --git a/design/images.md b/design/images.md index bad183c..0e99175 100644 --- a/design/images.md +++ b/design/images.md @@ -61,7 +61,7 @@ Source Dockerfiles can be found [here](https://github.com/radial/core-distro) The [Axle-Base image](https://index.docker.io/u/radial/axle-base/) is just a wrapper for the base Busyboxplus image but renamed to keep the naming scheme -consistent. It's sole purpose is for housing shared volumes. There should never +consistent. Its sole purpose is for housing shared volumes. There should never be a need to enter or modify this container directly once run, so it pretty much does nothing. @@ -70,7 +70,7 @@ Dockerfile source available [here](https://github.com/radial/imagebase-axle) ## Hub-Base The [hub-base image](https://index.docker.io/u/radial/hub-base/) uses the git -flavor of Busyboxplus as it's OS core. This is meant to allow it to combine both +flavor of Busyboxplus as its OS core. This is meant to allow it to combine both a [skeleton configuration](https://github.com/radial/config-supervisor) of [Supervisor](/radial/supervisor) as well as any additional configuration you need for your application. Both these configurations can be acquired statically @@ -87,17 +87,17 @@ The hub-base image is also responsible for modifying the file ownership and permissions of these configuration files one combined with git. This is also done using environment variables. -Further details on how to use this image can be found in [it's +Further details on how to use this image can be found in [its repository](https://github.com/radial/imagebase-hub). ## Spoke-Base Finally, we have the [spoke-base image][spoke]. It is based on the [core-distro images](https://github.com/radial/core-distro) and adds Supervisor to it for use -in your final Spoke container running your application. Much of it's automation -is abstracted away in the default Supervisor configuration and it the Spoke's +in your final Spoke container running your application. Much of its automation +is abstracted away in the default Supervisor configuration and the Spoke's standard entrypoint script. This allows your Dockerfiles to remain very simple -when you use this image as a base. Check out [it's repository][spoke] for more +when you use this image as a base. Check out [its repository][spoke] for more details. [spoke]:https://github.com/radial/imagebase-spoke diff --git a/design/supervisor.md b/design/supervisor.md index 8a47faa..8d3dc8f 100644 --- a/design/supervisor.md +++ b/design/supervisor.md @@ -40,7 +40,7 @@ Hub container. ## Subprocess init Files -It is a Docker best-practice is to keep the number of processes in a container +It is a Docker best practice to keep the number of processes in a container to a minimum. However, multiple processes are easily supported. By default, each spoke starts up a group identified by the `$SPOKE_NAME` variable in the spoke Dockerfile. You can have any number of subprocesses configurations split amongst @@ -54,7 +54,7 @@ wheel's configuration for an example. spokes attached to your hub container. All the Supervisor subprocess configuration files will be detected by all the other Supervisor daemons in every other spoke. So to keep from starting every process automatically in every -spoke, we instead resort to having each spoke manually launch it's own +spoke, we instead resort to having each spoke manually launch its own respective subprocess. Again, this is done via a properly configured subprocess group and use of `$SPOKE_NAME`. @@ -64,9 +64,9 @@ By default, the Spoke container, when run, will create a folder in `/log` named as the containers ID. It gets it from the '$HOSTNAME' variable that is set in the docker container by default. Luckily, Supervisor has access to this variable as well, so the [Supervisor skeleton][super_skel] by default will dump all the -logs into each spokes unique folder. This is what allows us to use the same axle +logs into each spoke's unique folder. This is what allows us to use the same axle container to store the logs from all our spoke containers without the worry of -name collisions. We then have only one place to look for viewing and backup our +name collisions. We then have only one place to look for viewing and backing up our logs. [super_skel]: https://github.com/radial/config-supervisor diff --git a/design/wheels.md b/design/wheels.md index 4faf565..574daad 100644 --- a/design/wheels.md +++ b/design/wheels.md @@ -45,14 +45,14 @@ break the 'hub-base' and 'spoke-base' images. Application configuration sits in ## Configuration Branch -Your application has a repository for it's code. Your deployment code and +Your application has a repository for its code. Your deployment code and configuration however, as it pertains to using Radial, is stored in the Wheel repository. The 'hub-base' image has the ability to `ADD` your configuration (whatever files you put in your `hub/config` and `hub/config/supervisor/conf.d` folders) as well as pull it from a repository. If -pulling from a repository is your method of choice, it is suggested that your +pulling from a repository is your method of choice, it is suggested that you make a separate branch in your Wheel repository with just the contents of your -`hub/config` folder and all it's subfolders and files. The 'hub-base' image +`hub/config` folder and all its subfolders and files. The 'hub-base' image contains logic to pull the 'config' branch of your Wheel repository and merge it with the [skeleton configuration][config-supervisor] used by Supervisor. @@ -88,7 +88,7 @@ They demonstrate the two ways that you can produce images. ### Axles -Axle containers are volume containers. So they're use can vary depending on +Axle containers are volume containers. So their use can vary depending on need. Typically, volume containers are dynamic, meant to store the data of some other container running a database perhaps. They also could potentially be used statically and house some type of static data set, source code, or media. @@ -107,7 +107,7 @@ environment variables. In order of most "static" to most "ephemeral", you could: if you don't have access to the actual configuration files, and they happen to be stored already in a wheel repository "config" branch, you can specify these `$WHEEL_REPO` repositories in a `/hub/build-env` file that gets - sourced on `docker build` therby cloning the configuration into the hub + sourced on `docker build` thereby cloning the configuration into the hub container and storing it statically the same. 3. For a quicker and more dynamic mode, you can simply run the `radial/hub-base` image without build, but specify `$WHEEL_REPO` diff --git a/instructions/axle-containers.md b/instructions/axle-containers.md index f9922f4..ca2519d 100644 --- a/instructions/axle-containers.md +++ b/instructions/axle-containers.md @@ -5,7 +5,7 @@ bind-mounted volumes. This can be host-specific persistent data, or any other type of [volume container](http://crosbymichael.com/advanced-docker-volumes.html). By default, Radial uses such a container to store the Supervisor log output of -each spoke container. Rather then make a decision on which log management one +each spoke container. Rather than make a decision on which log management one should use, they are instead simply collated into a single location. It's the job of some other spoke container to harvest/serve/analyze these logs later if one so chooses. diff --git a/instructions/hub-containers.md b/instructions/hub-containers.md index 9d1b5f7..25a8415 100644 --- a/instructions/hub-containers.md +++ b/instructions/hub-containers.md @@ -12,10 +12,10 @@ The big idea with 12-factor and configuration is that it is: 4. and transported via environment variables The Radial topology addresses each point accordingly: - 1. Configuration has it's own container (the hub). - 2. We use git to manage various version of configuration and can access it + 1. Configuration has its own container (the hub). + 2. We use git to manage various versions of configuration and can access it remotely or directly using a wheel repository. - 3. Wheels are modular components and various version of configuration can be + 3. Wheels are modular components and various versions of configuration can be easily combined with spoke containers depending on need. 4. Environment variables are used for everything.