Name: stack
Owner: Harvard Medical School - Department of Biomedical Informatics
Description: null
Created: 2018-01-30 13:52:46.0
Updated: 2018-02-04 15:04:36.0
Pushed: 2018-02-04 15:04:14.0
Homepage: null
Size: 10314
Language: Python
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
This is a program to provide some convenience wrappers around common tasks when developing with a Dockerized stack of micro-services. The program aims to simplify some of the management of a local stack and make it easier to develop on an entire stack whilst running and testing it.
The application depends on configurations defined in the base stack.yml
file for the applications that will be built.
repository
: This should specify the URL to the app's git repository.branch
: The particular branch to checkout when cloning the repo.Create your Python virtualenv and install requirements:
pip install -r requirements.txt
First step is to place any needed overrides in the overrides/{APP}
directory. These files are what will be used to build the image that
will be run in the stack. Typically they closely mirror the files
the app uses in its production environment, but with small tweaks to
run locally and to interface with other local apps. This directory
must contain a Dockerfile
if the app is to run off a built image.
The next step is to clone all needed repositories into the apps
directory.
stack
includes some convenience commands for managing the subtree
repositories. Do this with one command by running stack init
.
See below for further details on repository management.
The third step is to make sure the docker-compose.yml
file is fully
and accurately filled out to include the apps and their configurations.
This includes any volumes needed to mount the app's source within the
container. This allows for file changes to update the services
automatically so changes can be tested immediately. Verify current setup
by running stack check
.
Lastly, update the hook scripts with any extra bits of code needed to run the stack. Whether you need to collect npm dependencies after cloning a repo or you need a database to be cleared when cleaning an app, this is where custom functionality should live.
To check stack configurations and to ensure volume paths are correct, required images exist, etc:
stack check [<app>]
Not passing an app will iterate through all services specified in the
docker-compose.yml
file and check all configurations.
Run the initialize command to clone all needed repositories to their respective branches:
stack init
To get the stack going, run the following command (pass -d
to daemonize
the process):
stack up [-d]
If a container needs to be rebuilt for some reason (updated requirements, etc),
run the following command (app is the key of the service in your docker-compose.yml
):
stack reup <app> [--clean]
You could instead shell into the needed container and run the requirements update command there:
stack shell <app> [-sh]
Stack defaults to trying to open a bash shell, but you can default to sh if bash is not available.
You can also check logs on a container with a couple constraints to more easily find the relevant logs:
stack logs <app> [--minutes=n] [--lines=n] [-f]
You can specify how many minutes in the past to start the log retrieval
or the number of lines to get. You can also pass the -f
flag to follow
the logs as the container runs.
This will stop and remove the container, and then start it up again. The clean flag will purge the existing container image and rebuild before running again.
To bring the stack down, run the following:
stack down
This merely wraps docker-compose down --volumes
and brings the stack down
and removes any left-over data volumes.
Stack apps are included as git subtrees. Commands were added to Stack to wrap and simplify the commands needed to work with these repositories.
Before cloning, make sure the app exists in the docker-compose.yml
file
and has the required configurations, namely the repository URL. The current
docker-compose.yml
file illustrates how to do this with the current set
of apps.
Git subtree commands will not run with pending changes in the working directory. Commit all changes before running subtree commands.
To clone an existing repo into the apps
directory:
stack clone <app> <branch>
This will clone the repo as a subtree in the apps
directory
(default: {PROJECT_ROOT}/apps). If the app is already present in the
apps
directory, that copy will be removed and the specified branch
will be cloned in its place.
To pull remote changes into the local branch, use the pull
command:
stack pull <app> <branch> [--squash]
All commits pulled are added to the stack repository so squashing the incoming commits keeps history tidy.
To create a new branch for a specified app:
stack checkout <app> -b <branch>
This splits the subtree into the new specified branch. Commit changes as usual for the entire stack repository. Once an update is ready to push, run the push command as usual:
stack push <app> <branch> [--squash]
This will collect commits relevant to the particular subtree and push those
to origin for the new branch. The --squash
command will collapse those
commits into a single commit.
To get back to the base branch, checkout the branch as usual:
stack checkout <app> <branch>
This removes the subtree entirely, and clones the specified branch in its place.