-
Notifications
You must be signed in to change notification settings - Fork 6
starting copkg services
This document describes how to start copkg services -- it does not describe the agent that starts them.
We assume that the target environment for copkg is EC2 instances and developer workstations. In the former case the primary role of copkg is to make rapid deployment possible. In the second case the primary role of copkg is to make it possible to install and run significant parts of our architecture on developer machines. Both will contribute both towards iteration speed and our ability to deploy rapidly in a datacenter.
We assume that on EC2 nodes we have a standardized location for where software is installed and where runtime directories are created. These are separate locations.
For argument's sake we will imagine that the software install path is
/comoyo/software and the runtime prefix is /comoyo/runtime in our
EC2 nodes.
(On workstations one would want to give the user more control so the package manager can be configured to put packages where the user wants them)
This document won't go into detail about how packages are installed,
but this is done by the Package Manager library. This library can,
given a package coordinate of the form group:id:version, download,
extract and atomically install and uninstall software packages. There
is also a command line utility that is intended to be used for manual
or scripted install of packages.
https://github.com/borud/copkg/blob/master/src/main/java/org/cloudname/copkg/Manager.java https://github.com/borud/copkg/blob/master/src/main/java/org/cloudname/copkg/Main.java
Given a package coordinate com.comoyo:id-cassandra:2.1.1 this
package would then be installed in
/comoyo/software/com/comoyo/id-cassandra/2.1.1. Meaning that the
script for starting this service would be
/comoyo/software/com/comoyo/id-cassandra/2.1.1/script.d/start.py.
Before the start.py script is called a runtime directory must have
been made for the service and the runtime directory has to be
writeable for the service. The runtime directory must be a command
line option to the start.py script and a useful convention would be
to use the service coordinate to construct the runtime directory.
This is convenient because it gives us a trivial way to
programmatically find the runtime dir of a given service coordinate
and because there can only be one instance of a given coordinate at
any given time. Example:
1.idee.prod.trd => /comoyo/runtime/1.idee.prod.trd
The runtime directory will have the following subdirectories:
This is where all the log files should go regardless of logging format. It is advisable that at some point we specify some constraints for how things are named so that it is possible to clean up the log directory.
Any configuration files that the instance of the service needs. (Note that this is different from static config that we might want to distribute with the software package).
If the process produces output on stdout and stederr it might be an idea to have a separate directory for this. In particular if the output is so copious it mandates that we pipe the output through a log rotation program.
This is where the data files for the service will reside. For instance for a database, this is where the database files would reside.
Various runtime data needed to manage the service. For instance PID
files, lock files, UNIX domain sockets etc. When a service is started
the script starting it will have to make sure that the PID of the
service is recorded in run/start.pid.
When possible we should try to stick to the above directories for placing logs, config, data etc. If things are in fixed places we will be better equipped to create tools that can be leveraged across packages. If you must add directories try to figure out if it would make sense to amend this document.
Other than that, it is no disaster to add extra directories, but it is nice when we can build tools that deal with them incrementally.
There are three types of configuration:
This is static configuration that can reside in the software package
directory -- configuration that will not vary between instances of the
same service. This will typically reside in the etc directory of
the installed copkg. (For Apache the mime.types file would be an
example of that).
This is configuration files that are in the etc directory of the
runtime. We have not yet determined how instance config would end up
here, but there are some obvious choices.
It is preferable to get as much config on the command line as possible. This makes it easier to script and automate setup of services. MongoDB is a good example of a well-behaved binary that can easily be configured on the command line.
Starting a service is done by running the start.py script with the
appropriate command line options. One of the options is non-optional:
--runtime-dir. Note that in the example below we make use of the
service coordinate to give the runtime directory a predictable name.
This is intended to be a convention that is not enforced by the
start.py script, but which we might want to enforce strictly in the
component that is responsible for running this script.
Example:
/comoyo/software/com/comoyo/id-cassandra/2.1.1/script.d/start.py \
--runtime-dir=/comoyo/runtime/1.idee.prod.trd \
--coordinate=1.idee.prod.trd \
--some-param-1=foo \
--some-param-2=bar
- Parse command line options and ensure that they make sense.
- Make sure the needed directories exist in the runtime directory.
- If applicable, determine the runtime platform and pick the appropriate binary
- Construct command line and execute it.
Once the service has been started the script exits. We should not attempt to do process management by waiting for the service to exit.
Stopping a service is done by running stop.py with at least the
required argument --runtime-dir. Given the --runtime-dir the
stop.py script can find whatever data it needs to shut down the
process. For instance by kill'ing the PID(s) found in the pid file.
Cleaning up after a service need not be more complicated than removing the runtime directory and its subdirectories. We might want to introduce tools later to ensure we can secure logs or any valuable data from ephemeral disks if needed. (People tend to get confused when I talk about this so please ignore this for now).