Hi all,
I wanted to introduce a small project I have been working on called gramps-workspace.
This project began while I was writing new user documentation for setting up a standard Gramps development environment. One thing led to another and I found myself building a docker container to simplify the process. I had no prior docker experience when I started, but after four weeks of development (and a lot of testing) I feel the project is at a point worth sharing.
Goals
The main goal is to lower the barrier to entry for new contributors, testers, and translators. Setting up a working Gramps build environment takes time and varies depending on your system. gramps-workspace removes that friction by packaging all of the required dependencies into a single docker image that works the same way on every machine.
A big part of my motivation was accessibility. No docker experience is required and the docs include platform specific instructions for Linux, Windows, and Mac. If you can run a terminal command and clone a git repository, you can use gramps-workspace. At the same time I wanted it to be flexible enough for experienced developers to customize their container with additional packages, mount their own dotfiles, and fit it into their existing workflow.
Testing
gramps-workspace has been tested extensively on Linux and Windows Subsystem for Linux (WSL). Mac support is available and initial testing was successful, however testing of the most recent changes is still in progress. Mac feedback is welcome.
Feedback welcome
I’d really like to hear from experienced contributors in particular:
- Is there anything about gramps-workspace that conflicts with your existing workflow?
- Are there Gramps environment variables beyond
GRAMPSHOME that should be set in the container?
- Are there any dependencies or dev tools that should be added or removed from the Dockerfile.base?
- Translators: would this fit into your workflow? Are there any translation specific requirements I should be aware of?
- How do you currently manage your media/records files during development?
- Anything missing that would make this more useful?
The project is still early and I am happy to adjust direction based on what the community actually needs. Full docs and source are on GitHub.
Thanks for reading!
Following up on the intro post with some technical details for developers who want to understand how gramps-workspace works under the hood.
Container structure
The container is centered around the /workspace directory:
- /workspace/gramps/ - your Gramps git clone mounted from the host
- /workspace/data/ - shared between the host and container, persists between sessions
- /workspace/data/.gramps-home/ - assigned to GRAMPSHOME
- /workspace/data/.gramps-cache/ - per-branch build cache
- /workspace/gramps-venv/ - Python venv, recreated on every gramps-build
Dotfiles and HOME
The container uses usermod to match the container username to your host username. Because this renames the home directory at startup, bind mounting directly into /home/devuser will break container initialization. A guard is in place to detect and prevent this.
Instead, mount dotfiles into /opt/dotfiles. The container setup script will symlink everything into the container HOME directory automatically.
Environment variables
The following Gramps environment variables are currently set in the container:
GRAMPSHOME = /workspace/data/.gramps-home
LANG, LC_ALL = set dynamically by gramps-run when a language code is passed
I would like feedback on whether the following should also be set:
- GRAMPSDIR - likely /workspace/gramps, may not be needed
- GRAMPS_RESOURCES - may be handled automatically by the editable pip install
- GRAMPSI18N - may be useful for translators or addon developers
Media and records
There is no default media path configured. Two options are available:
- Copy media files into data/ and set the path in Gramps preferences
- Mount an existing folder via compose.user.yml, for example ~/Documents/Gramps/records:/workspace/records
Feedback on how you currently manage media during development would be helpful here.
Interesting! What was the motivation for creating it?
I was motivated by own experience setting up a dev environment on a WSL distro. I was documenting the process of installing dependencies, cloning the git repos, setting up a venv, and building the source. At some point through all this I found myself wanting to experiment with a way to simplify this so that users can get up and running with Gramps source more quickly.
I split the docker image into two parts. The base image is built on github and does all the heavy lifting (installing linux, dependencies, etc). The local dev image is built ontop of the base image and adds any user customization (installing apt packs, pip packs, or language packs).
I created a gramps-run and gramps-build command line tools to improve the build process for technical and non-technical users alike. The build tool adds a per-branch cache for builds and sets up the python venv. The run tool will activate the venv (if it exists) and has options for switching the language variables. These are both optional but I hope users will find them helpful with their workflows.
Nice! Perhaps this will be inviting for Windows developers to join in!
Yes, the main benefit of Dev Containers is that they provide IDE integration, particularly for VS Code users.
Gramps-workspace provides a consistent, cross-platform development environment that is editor agnostic. Users can use their favorite editor (vs code, pycharm, vim, etc) on the host machine and build/run Gramps in the container, or do all of their work directly inside the container. It is accessible regardless of their technical background or preferred workflow. The focus is on providing a reproducible Linux development environment.
That said, I don’t want anyone to feel that gramps-workspace limits how they work. If a contributor prefers using Dev Containers, I don’t see any fundamental reason we couldn’t support that as an optional workflow. It would be another way to access the same development environment rather than a replacement for the existing setup.
Anyone had a chance to try using gramps-workspace? I’d like to hear your first impressions and any feedback to make the project more accessible and useful for developers.
@riskysnail Do you use WSL containers by any chance? They were recently rolled out and are supposed to be very lightweight. Not to mention, they don’t require Docker. I’m curious to hear feedback.
If Gramps would provide them, that would make contributors’ lives much easier. Gramps’ dependencies are quite a nuisance to deal (or decide not to) with.
Since gamps-workspace is designed to be cross-platform the use of something like WSL Containers that is platform specific would need to improve the user experience enough to justify the added development overhead.
If they add support for compose files it would make integration with gramps-workspace much easier.
If Gramps would provide them, that would make contributors’ lives much easier. Gramps’ dependencies are quite a nuisance to deal (or decide not to) with.
This is exactly what gramps-workspace does, it provides a pre-built linux image container with all of the Gramps dependencies installed already. It is fully customizable so you can add any dev tools or addon dependencies you need.