tempdb_web_shell_docker

This directory contains a shell-first Docker setup for Links temporal DB web application. It is intended for interactive use.

The container provides the Links application code, PostgreSQL, bash, git, psql, linx and an interactive shell environment. The web app does not start automatically when you enter the container. Instead, you are dropped into a shell and can choose what to run.

The container provides a link to the app at http://localhost:8081 when the app is running.

There are two different ways to run this container from an image.

1. Build the image yourself on your own computer using the Dockerfile,

   • either run the bash script - more details on what the script does

     ./run-web-shell.sh
     

   • or use the following command

     docker build --no-cache -t tempdb_web_shell .
     

     followed by

     docker run -it \
       --name tempdb_web_shell \
       -p 8081:8080 \
       -v tempdb_web_shell_pgdata:/opt/postgres-data \
       tempdb_web_shell:latest
     

   Another option is to use the containers tool extension in Visual Studio Code: https://code.visualstudio.com/docs/containers/overview

2. Download the image and run it. The image generated by this setup is available at https://hub.docker.com/repository/docker/vcgalpin/xps_dcc_app/ with the tag tempdb_web_shell_test

   • use

     docker run -it \
     --name tempdb_web_shell \
     -p 8081:8080 \
     -v tempdb_web_shell_pgdata:/opt/postgres-data \
     vcgalpin/xps_dcc_app:tempdb_web_shell_test
     

     and to restart it or to view the logs, use

     docker start -ai tempdb_web_shell
     docker logs -f tempdb_simple_web
     

   • It is not clear whether it is possible to start an interactive container via Docker Desktop.

   (Note: This image does not provide the functionality of run-web-shell.sh. This functionality can only be accessed when building the image from the Dockerfile rather than just running the downloaded image as a container.)

What the container does

When the container starts, it:

1. starts PostgreSQL
2. creates the database role if needed
3. creates the database if needed
4. loads the SQL dump if the database does not already exist
5. opens an interactive shell with the correct opam environment loaded

This means linx should be available directly in the shell.

Useful container-side commands

Start the web app from inside the container

linx --config=config.debug.0.9.8 src/startXPS.links

Start the Links REPL

linx

Connect to PostgreSQL

psql -h /tmp -p 5432 -d linksdb -U linksuser

Show PostgreSQL tables

psql -h /tmp -p 5432 -d linksdb -U linksuser -c '\dt'

Check Git repo status

git status

Ports

The container is started with this mapping:

• host port 8081
• container port 8080

So if you start the web app inside the container, it should be reachable at http://localhost:8081

Database persistence

The PostgreSQL data is stored in the Docker volume:

tempdb_web_shell_pgdata

This means:

• the database persists across container restarts
• rebuilding the image does not automatically reset the database
• recreating the volume removes the existing database state

Running the bash script

When you run ./run-web-shell.sh the script can:

1. optionally show the current local Docker status of the image, the container and the data volume

2. check GitHub for the latest version of the configured branch

3. compare the current local image commit with the latest remote commit

4. classify changes as:

   • no changes
   • only code changed
   • only SQL dump changed
   • both code and SQL dump changed

5. show a second status section describing:

   • local commit
   • remote commit
   • detected change type
   • currently selected actions

6. let the user choose manual override actions:

   • rebuild image anyway
   • recreate database volume anyway
   • both
   • neither

7. ask any additional targeted questions if needed

8. start or attach to the shell container

First-time setup

Make the scripts executable:

chmod +x run-web-shell.sh show-status.sh show-change-status.sh show-commands.sh

Useful host-side commands

Show running containers

docker ps

Open a shell in the running container

docker exec -it tempdb_web_shell bash

Show logs

docker logs tempdb_web_shell

Stop the container

docker stop tempdb_web_shell

Remove the container

docker rm -f tempdb_web_shell

Remove the database volume

docker volume rm tempdb_web_shell_pgdata

Configuration values in the script

The main values are currently set in run-web-shell.sh:

• image name
• container name
• volume name
• GitHub repo URL
• GitHub branch
• SQL dump path
• database name
• database user
• database password
• web app start command

If you need to change behaviour, those are the first places to look.

Notes

Linux user

The container runs as linksuser

PostgreSQL user

The DB user is linksuser

Shell

The interactive shell is bash

Links executable

Use linx, not links