Testing with docker¶

Using the included docker-compose support¶

docker-compose lets you run cartography (and its unit and integration tests) without needing to install Python and without needing to install Neo4j.

Usage¶

Build the cartography Dockerfile. This creates a Docker image with all the Python dependencies needed by cartography and installs cartography itself to the image.
```
# Make sure you don't forget the '.' (represents current directory)
docker build -t lyft/cartography .
```
Start up the docker-compose dev environment
```
docker-compose up -d
```

Run the tests

docker-compose run cartography make test
# Alternatively replace `make test` with `make test_lint`,
# `make test_unit`, or `make test_integration`

Now when you make changes to the code, you can follow the steps above again to rebuild the container and re-run the automated tests. You can also run the full cartography sync by following the “Notes” section of this document.

Configuration¶

Configuration is possible via the .compose directory, which is git ignored. neo4j config, logs, etc is located at .compose/neo4j/...

Configuration for cartography itself should be passed in through environment variables, using the docker-compose format -e VARIABLE -e VARIABLE

AWS credentials can be bind mapped in using volumes. TODO: document correct bind mount format for docker-compose run.

Notes¶

On initial start of the compose stack, it’s necessary to change the neo4j user’s password through the neo4j UI.
Neither the docker image, nor the docker-compose file define an entrypoint, so it’s necessary to pass in the command being run. This also makes it possible to run a custom sync script, rather than only cartography.

Example¶

# Temporarily disable bash command history
set +o history
# See the cartography github configuration intel module docs
export GITHUB_KEY=BASE64ENCODEDKEY
# You need to set this after starting neo4j once, and resetting
# the default neo4j password, which is neo4j
export NEO4j_PASSWORD=...
# Reenable bash command history
set -o history
# Start cartography dependencies
docker-compose up -d
# Run cartography
docker-compose run -e GITHUB_KEY -e NEO4j_PASSWORD cartography cartography --github-config-env-var GITHUB_KEY --neo4j-uri bolt://neo4j:7687 --neo4j-password-env-var NEO4j_PASSWORD --neo4j-user neo4j