Skip to content

Envisaged - Effortless Gource Visualizations with Docker

License

Notifications You must be signed in to change notification settings

utensils/Envisaged

Repository files navigation

Envisaged - Dockerized Gource Visualizations

CircleCI Docker Automated build Docker Pulls Docker Stars

Built on top of utensils/opengl:stable (Alpine 3.12). No GPU is required, this will run on any machine, such as a standard EC2 instance or any other VPS.

About

Painless data visualizations from git history showing a repositories development progression over time.
This container combines the awesome Gource program with the power of FFmpeg and the h.264 codec to bring you high resolution (up to 4k at 60fps) video visualizations.

This container is 100% headless, it does this by leveraging Xvfb combined with the Mesa 3d Gallium llvmpipe Driver. Unlike other docker containers with Gource, this container does not eat up 100's of gigabtyes of disk space, nor does it require an actual GPU to run. The process runs the Gource simulation concurrently with the FFmpeg encoding process using a set of named pipes. There is a slight trade off in performance, but this makes it very easy to run in any environment such as AWS without the need to provision large amounts of storage, or run any cleanup.

Envisaged uses "template" scripts to generate specific looks, such as the one included in this container which is simply called border which places a frame around the Gource visualization and isolates the date and key on the outside of this border. If you would like to run the container with normal Gource output, simply pass -e TEMPLATE=none and it will use the no_template.sh script.

This container is configurable through environment variables listed below. The generated video is delivered via HTTP.

Example videos

GitHub Repo YouTube Video
Elixir School Elixir School Visualization
Kubernetes Kubernetes Visualization
Elixir Lang Elixir Lang Visualization

Usage Examples

Run with the default settings which will create a visualization of the Docker GitHub repository.
Notice we are exposing port 80, the final video will be served at http://localhost:8080/

The following example will run a visualization on the Kubernetes GitHub repository and include the Kubernetes logo in the video.

docker run --rm -p 8080:80 --name envisaged \
       -e GIT_URL=https://github.com/kubernetes/kubernetes.git \
       -e LOGO_URL=https://raw.githubusercontent.com/kubernetes/kubernetes/master/logo/logo.png \
       -e GOURCE_TITLE="Kubernetes Development" \
       utensils/envisaged

Running a visualization against a local git repo.

docker run --rm -p 8080:80 --name envisaged \
       -v /path/to/your/repo:/visualization/git_repo:ro \
       -e GOURCE_TITLE="Your Project Development" \
       utensils/envisaged

You can also combine multiple repositories into a single rendering by mounting a directory of repository directories onto /visualization/git_repos (the plural of visualization/git_repo).

docker run --rm -p 8080:80 --name envisaged \
       -v /path/to/your/repos:/visualization/git_repos:ro \
       -e GOURCE_TITLE="Your Project Development" \
       utensils/envisaged

Optionally, you can have gource render avatars of the authors by mounting a volume with images of the authors.

docker run --rm -p 8080:80 --name envisaged \
       -v /path/to/your/repo:/visualization/git_repo:ro \
       -v /path/to/your/avatars:/visualization/avatars:ro \
       -e GOURCE_TITLE="Your Project Development" \
       utensils/envisaged

The avatars in that directory must have filenames that match the author id, e.g. utensils.gif, etc.

Now open your browser to http://localhost:8080/ and once the video is completed you will see the link with the video size.

Environment Variables

Variable Default Value Description
GIT_URL <docker repo on GH> URL of git repository to be cloned and analyzed for visualization.
LOGO_URL <docker logo> URL of logo to be overlayed in lower right hand corner of video.
H264_PRESET medium h.264 encoding preset. refer to FFmpeg's wiki.
H264_CRF 23 The Constant Rate Factor (CRF) is the default quality for h.264 encoding. refer to FFmpeg's wiki.
H264_LEVEL 5.1 h.264 encoding level. Refer to FFmpeg's wiki.
VIDEO_RESOLUTION 1080p Output video resolution, options are 2160p, 1440p, 1080p, 720p
GOURCE_FPS 60 Output video frame rate
TEMPLATE border This is the template script that will be run. Options are border, and none.
GOURCE_TITLE Software Development Title to be displayed in the lower left hand corner of video.
OVERLAY_FONT_COLOR 0f5ca8 Font color to be used on the overlay (Date only).
GOURCE_CAMERA_MODE overview Camera mode (overview, track).
GOURCE_SECONDS_PER_DAY 0.1 Speed of simulation in seconds per day.
GOURCE_TIME_SCALE 1.5 Change simulation time scale.
GOURCE_USER_SCALE 1.5 Change scale of user avatars.
GOURCE_AUTO_SKIP_SECONDS 0.5 Skip to next entry if nothing happens for a number of seconds.
GOURCE_BACKGROUND_COLOR 000000 Background color in hex.
GOURCE_TEXT_COLOR FFFFFF Not Implemented.
GOURCE_HIDE_ITEMS usernames,mouse,date,filenames Hide one or more display elements
GOURCE_FONT_SIZE 48 Not Implemented.
GOURCE_DIR_DEPTH 3 Draw names of directories down to a specific depth in the tree.
GOURCE_FILENAME_TIME 2 Duration to keep filenames on screen (>= 2.0).
GOURCE_MAX_USER_SPEED 500 Max speed users can travel per second.
INVERT_COLORS false Inverts the colors on the visualization.