How it works
Server Mechanic for servers and virtual machines
With Server Mechanic you author changes to your machines as scripts in your favorite language, e.g. shell scripts. Server Mechanic collects these migration scripts, executes them and records them as applied in an internal database. Next time only new migrations will be executed. In case of an error you fix the problem and start over.
Server Mechanic for Docker containers
Docker already utilizes the step by step approach with the commands in your Dockerfile. These commands are run at container image build time. So you have full access to the container's internal state. But external volumes cannot be manipulated by Dockerfile commands. Here Server Mechanic comes into play.
Server Mechanic is started on container startup, applies your migration which migrates the state in your volumes, then container startup proceeds. So you can roll out adjustments to external volumes with new container versions and containers and volumes stay in sync.
Supported Platforms
| OS | Dist. | Version | Arch. | Supported | Notes |
| Linux | Ubuntu | xenial (16.04) | i386 | Yes | |
| Linux | Ubuntu | xenial (16.04) | amd64 | Yes | |
| Linux | Ubuntu | yakkety (16.10) | i386 | Yes | |
| Linux | Ubuntu | yakkety (16.10) | amd64 | Yes | |
| Linux | Ubuntu | zesty (17.04) | i386 | Yes | |
| Linux | Ubuntu | zesty (17.04) | amd64 | Yes | |
| Linux | Ubuntu | artful (17.10) | i386 | Yes | |
| Linux | Ubuntu | artful (17.10) | amd64 | Yes | |
| Linux | Ubuntu | bionic (18.04) | i386 | Yes | |
| Linux | Ubuntu | bionic (18.04) | amd64 | Yes | |
| Linux | Debian | wheezy (7) | i386 | Yes | |
| Linux | Debian | wheezy (7) | amd64 | Yes | |
| Linux | Debian | jessie (8) | i386 | Yes | Package install broken! |
| Linux | Debian | jessie (8) | amd64 | Yes | Package install broken! |
| Linux | Debian | stretch (9) | i386 | Yes | |
| Linux | Debian | stretch (9) | amd64 | Yes | |
| Linux | Debian | sid (10) | i386 | Not yet | |
| Linux | Debian | sid (10) | amd64 | Not yet | |
| Linux | Fedora | 25 | i386 | EOL | |
| Linux | Fedora | 25 | amd64 | EOL | |
| Linux | Fedora | 26 | i386 | Yes | |
| Linux | Fedora | 26 | amd64 | Yes | |
| Linux | Fedora | 27 | i386 | Yes | |
| Linux | Fedora | 27 | amd64 | Yes | |
| Linux | Fedora | 28 | i386 | Yes | |
| Linux | Fedora | 28 | amd64 | Yes | |
| Linux | Centos | 7 | i386 | Yes | |
| Linux | Centos | 7 | amd64 | Yes | |
| Linux | SuSE | Not yet | |||
| Linux | Arch | Not yet | |||
| BSD | Not yet | ||||
| OSX | Not yet | ||||
| Solaris | Not yet | ||||
| Windows | Not yet |
Installation
The easiest way to install Server Mechanic is the installer script. No magic, the installer script
- adds a package repository to your system
- and installs the mechanic package.
Execute the install script via the following command:
curl -s https://raw.githubusercontent.com/server-mechanic/packages/master/install-mechanic.sh | sudo bash -s unstable
CLI - Sub Commands and Options
| Command | Option | Since | Example | Description |
| (all) | -v | 0.1 | Be verbose, increase logging output. | |
| migrate | 0.1 | mechanic migrate | Apply pending migrations. | |
| 0.1 | mechanic -v migrate -- /entrypoint.sh param=value | Execute follow up command if all migrations have been successfully applied. | ||
| list-migrations | 0.1 | mechanic list-migrations | List migrations with status as if recorded in internal database. | |
| --order-by=id|start_date | 0.1 | mechanic list-migrations --order-by=id | Specify order for migrations list.
If unspecified, order is by start_date. |
|
| help | 0.1 | mechanic help | Print sub commands and options. | |
| version | 0.1 | mechanic version | Print version information. |
Environment Variables
| Environment Variable | Since | Example | Description |
| MECHANIC_ROOT_DIR | 0.1 | /home/developer/test-dir | Root directory for execution. This is mainly used for integration testing. |
The Configuration - /etc/mechanic.conf
# /etc/mechanic.conf [main] log_file=/mechanic.volume/log/mechanic.log pre_migration_dirs=/var/lib/mechanic/pre-migration.d/ migration_dirs=/var/lib/mechanic/migration.d/ post_migration_dirs=/var/lib/mechanic/post-migration.d/ run_dir=/mechanic.volume/tmp/ state_dir=/mechanic.volume/state
Configuration Options
| Option | Since | Default | Example | Description |
| log_file | 0.1 | ${MECHANIC_ROOT_DIR}/var/log/mechanic.log | /var/log/mechanic.log /dev/stderr |
File mechanic writes log messages to. |
| pre_migration_dirs | 0.4 | ${MECHANIC_ROOT_DIR}/etc/mechanic/pre-migration.d/: \ ${MECHANIC_ROOT_DIR}/var/lib/mechanic/pre-migration.d |
Colon seperated list of pathes mechanic collects pre migration scripts from. | |
| migration_dirs | 0.1 | ${MECHANIC_ROOT_DIR}/etc/mechanic/migration.d/: \ ${MECHANIC_ROOT_DIR}/var/lib/mechanic/migration.d |
Colon seperated list of pathes mechanic collects the migration scripts from. | |
| post_migration_dirs | 0.4 | ${MECHANIC_ROOT_DIR}/etc/mechanic/post-migration.d/: \ ${MECHANIC_ROOT_DIR}/var/lib/mechanic/post-migration.d |
Colon seperated list of pathes mechanic collects post migration scripts from. | |
| run_dir | 0.4 | ${MECHANIC_ROOT_DIR}/var/lib/mechanic/tmp | /var/lib/mechanic/tmp /tmp |
Location for migration execution directories. When a migration failed diagnostic data can be found here. (So /tmp is a moderate choice.) |
| state_dir | 0.1 | ${MECHANIC_ROOT_DIR}/var/lib/mechanic/state | Location where Server Mechanic stores the migration state. Currently the migration state is stored in a sqlite database named inventory.db below this directory. |
Development
Server Mechanic is written in python. (Early versions where based on Go, C and C++.)
Unit tests are written with the python mock lib. (Everything testable should be tested via a unit test.)
Integration tests are currently based on a set of custom shell scripts performing the following steps to verify several scenarios (There is a real chance that we switch to docker containers in the near future - for now the setup is sufficient.):
- Setup a test scenario based on files in a temporary folder.
- Run the mechanic in this temporary folder utilizing MECHANIC_ROOT_DIR to change mechanic root.
- Then exit code, contents of the test file system, the internal state of the mechanic database are merged into an output listing.
- The output listing is compared to the expected output.
Prerequesites
Install system packages
# RedHat/ CentOS/ Fedora yum -y install python sqlite sqlite-devel make git # Debian/ Ubuntu apt-get install -y python2.7 sqlite3 sqlite3-dev make
Install python packages
pip install mock coverage
Install docker
For docker installation refer to docker installation instructions.
Build the project
This is the make target you probably will use for development.
- Precompiles the python code
- runs unit tests
- runs integration tests.
make
or
make default
Build all
- Precompiles the python code
- runs unit tests
- runs integration tests
- generates coverage report
- build installation packages.
make all