Ixian-Docker¶

Ixian-Docker is a tool that manages docker builds and provides development tooling for interacting with your docker app. Prebuilt modules are included to construct an application stack quickly. Ixian’s goal is to build applications with sane defaults, but not stand in your way if you’d like to configure or extend it to better suit your needs.

There are several things Ixian-docker will help you with:

Building a heirarchy of docker images.
Pluggable platform features like Python, NodeJS, Django, and more.
Provides a command line interface to your application running within a local container.

Installation¶

pip install ixian_docker

Setup¶

1. Create `ixian.py`¶

Ixian apps must be initialize in ixian.py. Here is a basic setup for a django app.

# ixian.py
from ixian.config import CONFIG
from ixian.module import load_module

def init():
    # Load ixian core + docker core.
    CONFIG.PROJECT_NAME = 'my_project'
    load_module('ixian.modules.core')
    load_module('ixian_docker.modules.docker')

    # Minimal setup for Django backend + Webpack compiled front end
    load_module('ixian_docker.modules.python')
    load_module('ixian_docker.modules.django')
    load_module('ixian_docker.modules.npm')
    load_module('ixian_docker.modules.webpack')

2. Configure Docker Registries¶

Configure docker registries for pulling and pushing images.

# Specify the registry for your images. The image's name will be generated
# from this url and path.
#
#   e.g. my.registries.domain.name.com/my_project
#
CONFIG.DOCKER.REGISTRY = 'my.registry.domain.name.com'
CONFIG.DOCKER.REGISTRY_PATH = 'my_project'
CONFIG.DOCKER.REGISTRIES = {
    'my.registry.domain.name.com': {
        'client': DockerClient,

        # addtional options may be passed in
        'options': {
            'username': "my_registry_user"
            'password': "my_registry_password"
        }
    }
}

See the section on docker registries for more information.

3. Module config¶

Modules each have their own requirements for configuration. Built-in modules have sane defaults where possible. See specific module docs for details.

Usage¶

Basics¶

Ixian apps are executed using the ix runner. This is the entry point for ixian apps. The general help page lists the available tasks.

$ ix build_image

usage: ixian [--help] [--log LOG] [--force] [--force-all] [--clean]
     [--clean-all]
     ...

Run an ixian task.

positional arguments:
  remainder    arguments for task.

optional arguments:
  --help       show this help message and exit
  --log LOG    Log level (DEBUG|INFO|WARN|ERROR|NONE)
  --force      force task execution
  --force-all  force execution including task dependencies
  --clean      clean before running task
  --clean-all  clean all dependencies before running task

Type 'ix help <subcommand>' for help on a specific subcommand.

Available subcommands:

[ Build ]
  build_image                Build app image

Internal flags should be placed before the task.

ix --force build_image

Any args after the task name are passed to task’s execute method.

For example, many tasks are wrappers around other command line tools. Pass --help after the command to get that tool’s internal help.

ix pytest --help

Tasks¶

Once configured you will have access to a number of tasks for building and interacting with the app in your image. These will vary depending on what modules you’ve enabled. Here are a couple of examples.

Build a docker image.
ix build_image
Run the django test server.
ix runserver
Run automated tests.
ix test

Task checks¶

Many tasks have state checks that determine if they are already complete. This can be viewed in ixian task help. Completed dependencies are indicated by a check.

STATUS
○ build_image
    ✔ build_base_image
    ○ build_npm_image
    ○ build_webpack_image
    ○ build_python_image

If the task or any of it’s dependency are incomplete then the task and it’s incomplete dependencies will be run.

STATUS
○ build_image
    ✔ build_base_image
    ✔ build_npm_image
    ○ build_webpack_image
    ○ build_python_image

When all are complete then the task can be skipped. If checkers detect changes, such as modified config files, the checkers will indicate a build.

STATUS
✔ build_image
    ✔ build_base_image
    ✔ build_npm_image
    ✔ build_webpack_image
    ✔ build_python_image

Note

If there are no checkers then a task runs every time it is called.

Forcing tasks¶

Task checks may be bypassed with --force. Pass --force-all to bypass checks for all dependencies.

Clean build¶

Some tasks have a clean function that removes build artifacts. Pass --clean to call the clean function prior to building. Pass --clean-all to trigger clean for all dependencies. If a task doesn’t define a clean method then --clean does nothing.

Passing --clean also implies --force.

Built-in help¶

All tasks have built in help generated from task docstrings and metadata. The help page should explain how to configure and use the task. It also displays the state of tasks and any dependencies.

When in doubt, check help.

$ ix help build_image

NAME
    build_image -- Build app image

DESCRIPTION
Builds a docker image using CONFIG.DOCKER_FILE

STATUS
○ build_image
    ○ build_base_image
    ○ build_npm_image
    ○ build_webpack_image
    ○ build_python_image

What’s an Ixian?¶

Ixian is a flexible build tool that this project is built with. Ixian provides the platform to define and arrange a heirarchy of interrelated tasks into a command line app.