Deploying Gramps Web with Docker
The most convenient option to host Gramps Web is with Docker Compose. We will assume that Docker and Docker Compose are already installed in your system. Your can use Windows, Mac OS, or Linux as a host system. The supported architectures include not only x86-64 (desktop systems), but also ARM systems such as a Raspberry Pi, which can serve as a low-cost, but powerful (enough) web server.
Note
You do not need to install Gramps on the server as it is contained in the docker image.
Step 1: Upload Gramps database
Upload the Gramps database from your computer to the server. This is the directory that shows up before the family tree name when you run gramps -l
. We will assume you will put it into the directory ~/gramps_db
.
Note
This only works if you use Gramps 5.1 locally and the family tree uses SQLite (BSDDB is not supported).
Alternatively, you can upload a Gramps XML export to the server and import it later.
Step 2: Upload media files
Upload your media files to the server. Make sure your Gramps database uses relative paths and not absolute paths as these will not work. We will assume the media base directory on your server will be located at ~/gramps_media
.
Note
Use the "Convert media paths from absolute to relative" option in the "Media Manager" tool in Gramps' "Tools" menu if necessary.
Step 3: Docker configuration
Create a new file on the server named docker-compose.yml
and insert the following contents:
version: "3.7"
services:
grampsweb:
image: ghcr.io/gramps-project/grampsweb:latest
restart: always
ports:
- "80:5000"
environment:
TREE: "..." # set the name of your family tree
SECRET_KEY: "..." # set your secret key
BASE_URL: "http://localhost:5554"
volumes:
- gramps_users:/app/users
- gramps_index:/app/indexdir
- gramps_thumb_cache:/app/thumbnail_cache
- ~/gramps_db:/root/.gramps/grampsdb
- ~/gramps_media:/app/media
volumes:
gramps_users:
gramps_index:
gramps_thumb_cache:
This will generate three named volumes to make sure that the user database, search index, and thumbnail cache will persist, and will mount the Gramps database directory and the directory holding your media files into the container (the paths on the left-hand side of the colon :
refer to your host machine, the ones on the right hand side to the container and should not be changed). For more configuration options, see Configuration.
Warning
The above will make the API available on port 80 of the host machine without SSL/TLS protection. You can use this for local testing, but do not expose this directly to the internet, it is completely insecure!
Step 4: Secure access with SSL/TLS
The web API must be served to the public internet over HTTPS. There are several options, e.g.
- Using docker hosting that includes SSL/TLS automatically
- Using an Nginx Reverse Proxy with a Let's Encrypt certificate
A particularly convenient option is to use a dockerized Nginx reverse proxy with automated Let's Encrypt certificate generation. This is achieved with the following docker-compose.yml
:
version: "3.7"
services:
grampsweb:
image: ghcr.io/gramps-project/grampsweb:latest
restart: always
environment:
VIRTUAL_PORT: "5000"
VIRTUAL_HOST: ... # e.g. gramps.mydomain.com
LETSENCRYPT_HOST: ... # e.g. gramps.mydomain.com
LETSENCRYPT_EMAIL: ... # your email
TREE: "..." # set the name of your family tree
SECRET_KEY: "..." # set your secret key
BASE_URL: "http://localhost:5554"
volumes:
- gramps_users:/app/users
- gramps_index:/app/indexdir
- gramps_thumb_cache:/app/thumbnail_cache
- ~/gramps_db:/root/.gramps/grampsdb
- ~/gramps_media:/app/media
networks:
- proxy-tier
- default
proxy:
image: nginxproxy/nginx-proxy
restart: always
ports:
- 80:80
- 443:443
environment:
ENABLE_IPV6: "true"
volumes:
- conf:/etc/nginx/conf.d
- dhparam:/etc/nginx/dhparam
- certs:/etc/nginx/certs:ro
- vhost.d:/etc/nginx/vhost.d
- html:/usr/share/nginx/html
- /var/run/docker.sock:/tmp/docker.sock:ro
networks:
- proxy-tier
acme-companion:
image: nginxproxy/acme-companion
container_name: nginx-proxy-acme
restart: always
volumes_from:
- proxy
volumes:
- certs:/etc/nginx/certs:rw
- acme:/etc/acme.sh
- /var/run/docker.sock:/var/run/docker.sock:ro
networks:
- proxy-tier
depends_on:
- proxy
volumes:
acme:
certs:
conf:
dhparam:
vhost.d:
html:
gramps_users:
gramps_index:
gramps_thumb_cache:
networks:
proxy-tier:
Please see the acme-companion docs for how to set up your domain.
Step 5: Import database
If you have copied the Gramps database directory directly in Step 1, you can skip this step.
If you have uploaded a Gramps XML instead, you need to import it into a new family tree using the Gramps executable inside the docker container. This can be achieved with the command
docker-compose run --entrypoint "" grampsweb \
gramps -C 'My family tree' \
-i /root/.gramps/grampsdb/my_tree.gramps \
--config=database.backend:sqlite \
--config=database.path:/root/.gramps/grampsdb
My family tree
is the name of the new family tree (must match the setting in the config file) and my_tree.gramps
the file name of the Gramps XML export.
Step 6: Add users
Initialize the user system by creating an administrator account with the command
docker-compose run grampsweb \
python3 -m gramps_webapi user add \
--fullname 'My full name' \
--email 'my@email' \
--role 4 \
my_username my_password
See User system for more details and how to add additional users.
Step 7: Start the server
Run
docker-compose up -d
On first run, it will build the full-text search index that powers the app's search function.