octobus/heptapod-dev repository overview

⁠Heptapod official development image

This image is intended as the main working tool for developers, makin life easier for them, without interfering with the main Heptapod image⁠.

It is built from the heptapod_docker_dev⁠ directory, which comes with build and launch utilities also listed here.

⁠Differences with the main image

Note: care must be taken not to introduce functional divergences that would impact testing, and hence mask bugs that developers could introduce.

• all Heptapod components (Rails application, hg-git etc.) are at the head of their main branch at the time of build.
• more utilities are included by default (e.g., less)
• a subset of Mercurial configuration (evolve, topics) is available outside of served repositories or easy handling of the running code.
• Heptapod code is pulled from dev.heptapod.net

⁠How to build for a specific topic

• make sure the topic has been pushed (see "How to update in place" below if you don't want to).
• make sure you have an [Omnibus Heptapod] (https://dev.heptapod.net/heptapod/omnibus⁠), and that it is updated to the heptapod branch.
• from your Omnibus Heptapod clone, edit heptapod_docker_dev/heptapod_revisions.json (contains instructions)
• see "Building and Running" below

⁠Recommended developer setup

At the time of this writing, using the present image is the only way to work on Heptapod in practice.

⁠Mercurial configuration

• install Mercurial and hg-evolve⁠
• activate the topic and evolve extensions with the following HGRC snippet:

[extensions]
evolve =
topic =

⁠Mercurial workflow

Heptapod follows the default Heptapod workflow, see the FAQ⁠ and the related Octobus blog post⁠

⁠Heptapod components

Like GitLab, Heptapod is made of several components, which fall in several categories:

• identical to GitLab CE: these are only available in the Docker image, actually taken from the gitlab-ce parent image. Example at the time of this writing: gitlab-shell.
• Forked from GitLab CE, e.g, Ruby on Rails application⁠. All of these have an heptapod branch while the default branch is used to track upstream GitLab changes.
• Specific to heptapod: hg-git.

You can get an up to date list of forked and specific components, and URLs to clone them by reading the heptapod_revisions.json⁠ file.

⁠Source repositories

• make a common directory for all your working sources, e.g., ~/heptapod
• clone proper branch of Heptapod Omnibus: hg clone -b heptapod https://mirror.octobus.net/heptapod/omnibus ~/heptapod/omnibus
• clone Heptapod Ruby on Rails application: hg clone -b heptapod https://mirror.octobus.net/heptapod/heptapod ~/heptapod/heptapod-rails

Having all the sources in a single directory makes it easy to expose them inside the Docker container (see "Building and Running").

⁠Building and Running

The Omnibus Heptapod repository has a build-launch script meant for this in its heptapod_docker_dev subdirectory.

It will automatically build the development image, setup appropriate bind mounts for Docker volumes and your sources. If its defaults don't suit you, it is fully inspectable and configurable.

All examples below are from the Omnibus clone (see "Source repositories" above)

⁠Inspect default behaviour and available options

heptapod_docker_dev/build-launch --simulate
heptapod_docker_dev/build-launch --help

⁠Build the development image only, and run Heptapod

Assuming the volumes configuration suits you:

heptapod_docker_dev/build-launch

This will mount the parent directory of your Omnibus clone at /home/heptapod in the container (see "Recommended developer setup" above).

The container is setup by default for our automated functional tests⁠.

⁠Run the main Heptapod image, without rebuilding anything

This is handy for pre-release tests:

heptapod_docker_dev/build-launch --image-tag octobus/heptapod --no-build

⁠Build all images and push to Docker Hub

This is how Heptapod project maintainers do it:

heptapod_docker_dev/build-launch --build-base-image --no-run --push

⁠How to update in place

This assumes that we use the recommended developer setup, and the build-launch default options.

This means in particular that the container name is heptapod and that our working clone of the Rails application⁠ is available from /home/heptapod/heptapod-rails in the container.

⁠Updating to a local topic

my-workstation-~ $ docker exec -it heptapod /bin/bash
# cd /opt/gitlab/embedded/service/gitlab-rails
# hg pull /home/heptapod/heptapod-rails
# hg up REVISION
# gitlab-ctl restart

⁠Applying uncommitted changes

This example assumes you have no prior local changes in the container, and applies all changes from your work station source repository.

my-workstation-~ $ docker exec -it heptapod /bin/bash
# cd /opt/gitlab/embedded/service/gitlab-rails
# hg -R /home/heptapod/heptapod-rails diff | patch -p1
# gitlab-ctl restart