skip to navigation
skip to content

Not Logged In

docker-forklift 0.2

Utility for running a container

Latest Version: 0.2.43

Forklift - when you need to handle just one container
=====================================================

Utilities to develop a containerised application.

The standard containers at InfoXchange require a number of environment
variables to run properly. With Forklift, they can be inferred automatically
and/or specified in the codebase.

Furthermore, it is often necessary to experiment within a running container.
Forklift includes a special 'sshd' mode to start the SSH daemon instead of the
original command, so that one can run arbitary commands inside.

Installation
------------

sudo pip install .

Or in a virtualenv:

pip install .

Warning: Forklift requires Python 3, and you should use the corresponding `pip`
to install, for example, `pip-3.2` on Debian and `pip3` on Ubuntu
(`sudo apt-get install python3-pip`). If unsure, check that `pip --version`
reports being `python 3`.

Running Forklift
----------------

The basic invocation is:

forklift APPLICATION ARGUMENT...

What happens is:

* The configuration files are being searched for a list of services to provide
to the command.
* For all of those services, an available provider is searched for.
* The found services, along with any additional configured environment, are
passed to the command as environment variables.

For example, if the project specifies:

services:
- postgresql

Forklift will check if the PostgreSQL server is running on the local machine,
and pass the database URL to the application.

Docker
------

Forklift can run commands directly or Docker containers. By default, if the
application given is an existing file (e.g. `./manage.py`), it is run directly.
Otherwise it is assumed to be a Docker image to create a container from.
The environment is passed to the application in either case.

To override the choice, set `driver` parameter to either `docker` or `direct`.

Docker driver has specific parameters:

* `rm`: Automatically remove containers after they've stopped.
* `privileged`: Run containers in privileged mode.
* `interactive`: Run containers in interactive mode (`-i -t`).
* `storage`: Run the container with `/storage` mounted as a volume under the
specified path.
* `mount-root`: Bind mount the root directory of the container filesystem to
the specified path.

### SSH daemon mode

Forklift can set up an SSH server inside the container, passing in all the
environment and adding the user public key. To use this mode, pass `sshd` as
the command (e.g. `forklift ubuntu sshd`).

The following additional options apply in SSH daemon mode:

* `user` - the user to set up for SSH in the container, defaults to `app`.
* `identity` - the public key file to authorise logging in as. Can be specified
as the full path or as a file in `~/.ssh`.
* `host-uid` - for ease to use with `mount-root`, the UID of the user inside
the container is changed to the one of the host user; override if needed.

When running in SSH daemon mode, Forklift starts the container in the
background and prints a command to SSH to it. It is up to the user to stop
the container when no longer needed.

Services and environment
------------------------

The following environment is always available to the running application:

* `ENVIRONMENT`: `dev_local`
* `DEVNAME`: the current user name
* `SITE_DOMAIN` and `SITE_PROTOCOL`: The URL where the application will be
accessible to the outside world if it listens on port 8000 locally.
* Any environment variables from configured services.
* All variables under `environment` (e.g. `environment.FOO` will be passed in
as `FOO`).

The services to provide to the application are taken from the `services` array
in the configuration file. The following services are known to Forklift:

### PostgreSQL

Provides access to the database. The environment variable, `DB_DEFAULT_URL`,
contains a [Database URL][dj-database-url] for the application to use.

By default, Forklift checks if there is a PostgreSQL server running on the
machine, and if yes, provides the application with its details, taking the
current directory name for the database name.

The following parameters can be overridden: `host`, `port`, `user`, `password`,
`name`.

### Elasticsearch

Provides an URL to access Elasticsearch at as environment variables
`ELASTICSEARCH_URLS` (the `|`-separated list of URLs to try at round robin)
and `ELASTICSEARCH_INDEX_NAME` (the index to use).

By default, the localhost is checked for a running instance of Elasticsearch
and if successful, the current directory name is provided to use as the index.

The following parameters can be overridden: `urls`, `index_name`.

### HTTP Proxy

Provides an HTTP proxy as an URL in `HTTP_PROXY`.

The following parameters can be overridden: `host`, `port`.

### Email (SMTP)

Provides an MTA for the application to connect to.

Defaults to `localhost` port 25.

The following parameters can be overridden: `host`, `port`.

### Logging (syslog)

Provides a syslog instance to log events to.

If not overridden, Forklift will start a daemon to print out all messages to
standard output and provide its address to the application.

The following parameters can be specified: `host`, `port`, `proto` (`tcp` or
`udp`).

Configuration
-------------

Forklift has a hierarchy of configuration options. For example, `services`
parameter is an array of services the application need, `environment` is a
dictionary of extra environment variables to provide, `postgresql` overrides
options for PostgreSQL service, etc.

Every parameter value is searched, in order, in the following locations:

* Command line, e.g. `--driver direct` or `--postgres.port 5433` (note the
nested parameter syntax).
* User configuration file in `forklift/PROJECT.yaml`, where `PROJECT` is the
base name of the current directory, inside the
[XDG configuration directory][xdg] (usually `$HOME/.config`).
* Project configuration file - `forklift.yaml` in the current directory.

This allows granular overriding of the (hopefully useful) Forklift defaults.
For example, if the local database requires a password, it can be stored
in a local configuration file, e.g. `$HOME/.config/forklift/myapp.yaml`:

postgres:
password: l@m3password

[dj-database-url]: https://github.com/kennethreitz/dj-database-url
[xdg]: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html  
File Type Py Version Uploaded on Size
docker-forklift-0.2.tar.gz (md5) Source 2014-03-25 12KB
  • Downloads (All Versions):
  • 78 downloads in the last day
  • 1018 downloads in the last week
  • 3390 downloads in the last month