Skip to content

Sys Admin Guide ‐ Docker Install

Jump to bottom
paigewilliams edited this page Jun 23, 2026 · 9 revisions

TEK DB Technical Information and Maintenance Guide for Docker Installed Applications

In 2026, the Ecotrust Software team added support for installing the TEK DB project with Docker. Below is a guide for System Admins on how to maintain their Docker deployed instance.

Dependency Stack

  • Operating System (pick 1):
    • Ubuntu 24.04 LTS (recommended/supported, 26.04 and newer LTS)
    • Other Linux Server distributions
    • Windows Server
  • Docker Engine (pick 1):
    • Docker Engine for Linux (Docker CE)
    • Docker Desktop

Code Source

All code and documentation is available for free (under the MIT license) on Github: https://github.com/Ecotrust/TEKDB

Docker Architecture

We are using Docker Compose for multiple container orchestration. For installations that are intended to not be on the internet, but utilize a Nginx web server, we use the [docker-compose.prod.local.yaml](https://github.com/Ecotrust/TEKDB/blob/main/docker/docker-compose.prod.local.yaml) file.

Containers

In docker-compose.prod.local.yaml, the following containers are defined:

  • db: PostGIS database
  • tekdb_web: Django web application
  • proxy: Nginx proxy for serving the web application
  • redis: Redis cache for tracking interruptible upload deletions
  • tekdb_celery: Celery task queue container used for the delete_expired_chunks task, which deletes expired upload chunks
  • tekdb_celery_beat: Celery Beat scheduler container that keeps the cadence for the delete_expired_chunks task.

Exporting the data

If you are reinstalling the tool and need to preserve or migrate your data you can create a 'fixture' (a backup file) that can be imported into new instances of the TEK DB.

Automated Export for Backup

In 2022, a new feature was added to simplify the process below – it allows users with administrative privileges to export a zipped archive file containing a 'fixture' file to restore database records, as well as a folder containing all relevant media files (videos, photos, audio, pdfs, etc…) supported by the database.

  1. Log in to with admin credentials.
  2. In the top right corner, select the dropdown and click 'administration' to navigate to the Django Administration dashboard.

Warning: the following step downloads all of the traditional knowledge that has been accumulated into the database thus far, captured in a single, unencrypted file.

  1. Click the 'Export to .zip' button

Manual Export for Backup

  1. Determine a safe place to write the file
  2. Determine a meaningful name for the file, such as tek_db_fixture_YYYYMMDD.json, with YYYYMMDD being today's date
  3. Navigate to your project where you have Docker running and run the following command:
docker exec tekdb_web python manage.py dumpdata --indent=2 auth.Group Lookup.LookupPlanningUnit Lookup.LookupTribe Lookup.LookupHabitat TEKDB.Places Lookup.LookupResourceGroup TEKDB.Resources Lookup.LookupPartUsed Lookup.LookupCustomaryUse Lookup.LookupSeason Lookup.LookupTiming Relationships.PlacesResourceEvents Lookup.LookupParticipants Lookup.LookupTechniques Lookup.LookupActivity TEKDB.ResourcesActivityEvents Lookup.People Lookup.LookupReferenceType Lookup.LookupAuthorType TEKDB.Citations Relationships.PlacesCitationEvents Lookup.CurrentVersion Lookup.LookupLocalityType TEKDB.Locality Relationships.LocalityGISSelections Relationships.LocalityPlaceResourceEvent Lookup.LookupMediaType Lookup.LookupUserInfo TEKDB.Media Relationships.MediaCitationEvents Relationships.PlaceAltIndigenousName Relationships.PlaceGISSelections Relationships.PlacesMediaEvents Relationships.PlacesResourceCitationEvents Relationships.PlacesResourceMediaEvents Relationships.ResourceActivityCitationEvents Relationships.ResourceActivityMediaEvents Relationships.ResourceAltIndigenousName Relationships.ResourceResourceEvents Relationships.ResourcesCitationEvents Relationships.ResourcesMediaEvents Accounts.UserAccess Accounts.Users explore.PageContent > /path/to/your/file.json

Installing Docker and the project

Scripted install

We have developed a bash script to run to install Docker, checkout this Git repository, use your environment variables and start the Docker containers using docker compose.

How to:

  1. Create a .env.prod file with your environment variables in an accessible location on your Linux instance.

Copy the code below into an .env.prod file, and replace the # comment with your values.

SECRET_KEY= # a random 50+ character string used for Django.You can generate this yourself or use a tool like [this](https://builtwithdjango.com/tools/django-secret/) to generate one for you.
ALLOWED_HOSTS= # comma-separated list of IP address you want the app to run on 
SQL_ENGINE=django.contrib.gis.db.backends.postgis
SQL_DATABASE= # database name, ex: tekdb
SQL_USER= # database user, ex: postgres
SQL_PASSWORD= # database password
SQL_HOST=db
SQL_PORT=5432
WEB_IMAGE=ghcr.io/ecotrust/tekdb/web 
CELERY_BROKER_URL=redis://redis:6379/0
GIS_USER_PASSWORD= # password for user named ‘gis’ which has permissions for accessing tables with spatial data
  1. Download the script onto your instance with curl:
curl -L -o install-docker-env.sh https://github.com/Ecotrust/TEKDB/raw/refs/heads/main/scripts/Linux/install-docker-env.sh
  1. Ensure the script is executable:
chmod +x install-docker-env.sh
  1. Run the script:
./install-docker-env.sh <file path to env.prod file>
  1. View the TEK DB project at the IP address you specified in ALLOWED_HOSTS! The application is live!

Tear down the Docker containers

Scripted

If you would like to take down the TEK DB project, we have a script to help with this.

  1. From the instance that the TEK DB project is running on, copy the tear down script with curl:
curl -L -o teardown-docker-env.sh https://raw.githubusercontent.com/Ecotrust/TEKDB/refs/heads/main/scripts/Linux/teardown-docker-env.sh
  1. Ensure the script is executable:
chmod +x teardown-docker-env.sh

  1. Locate your docker compose file. If you installed with the install-docker-env.sh script, the file is likely at <where you ran the script>/tekdb/docker. The Docker compose file is called docker-compose.prod.local.yaml.

  2. Run the script:

./teardown-docker-env.sh <file path to .env.prod file> <file path to docker compose>
  • If you would like to remove all of the data in the database with your tear down, add the flag --volumes. Ensure you have a back up before doing this if you would like to persist your data.
  • If you would like to remove any Docker images that are build during the docker-compose up in the install script, add --rmi-local

Manual

  1. Locate your the directory where the docker-compose.prod.local.yaml files lives. This is likely at the location of where you ran the install-docker-env.sh script tekdb/docker.
  2. Navigate to this location.
  3. From that location, stop the docker containers:
docker compose down
  1. Verify that no containers are running:
docker ps

Installing updates

With the Docker architecture, we can utilize image tags to get updated images when new versions of the TEK DB are released. This project has an automated process that publishes a new Docker images to Github Package Registry whenever a Release is created. The Docker images are tagged with their semver version, and if it is the latest release, it receives the tag latest.

The docker-compose.prod.local.yaml file is written to always use the Docker image with the tag latest. If you would like to update your instance with the latest image, From the location of your docker-compose.prod.local.yaml do the following:

  1. Pull the latest tekdb_web image:
docker pull ghcr.io/ecotrust/tekdb/web:latest
  1. Restart the containers:
docker compose --env-file .env.prod -f docker-compose.prod.yaml up -d

Debugging

Container status

To view all running containers:

docker ps

To view all running or stopped containers:

docker ps -a

Viewing Logs

It can be very helpful to view the logs for the different containers when debugging. Logs can be viewed with the following commands:

From the location of the docker-compose.prod.local.yaml file:

  • To view all container logs:
docker compose logs
  • To view a specific containers logs:
docker logs <container name>
  • To attach your terminal to a running containers shell, to view logs as they happen:
docker attach <container name>
  • To exec into your running docker container:
docker exec -it <container name> /bin/bash

If you do not see helpful logs in your tekdb_web container, it is possible that DEBUG=0, suppressing logs from being written. To update the DEBUG level, do the following:

  1. Navigate to your .env.prod file.
  2. Open and edit your .env.prod file with your editor of choice (vim, nano, etc).
  3. Add DEBUG=1 to your .env.prod
  4. Restart the containers:
docker compose --env-file .env.prod -f docker-compose.prod.yaml up -d

Clone this wiki locally