Project

General

Profile

Wiki » Development Using a Docker Container »

Starting the Runtime Environment in Docker

Introduction

This is the process to start the FWD server. Before executing these steps, you MUST have successfully completed the both Runtime Setup Using Docker and Database Import Using Docker.

Start the Environment

If you do not have a Docker container running, use dbash.sh to make sure you have a running container. This simply starts a bash shell in a Docker container. To include PostGreSQL within the environment, add appropriate --pg<14|15|16|17> option and the -v volume you created in the Database Import Using Docker section. The command would be similar to:

dbash.sh -v hotel_db_postgres --pg17 -w

Start the Database

Make sure the PostgreSQL database is started with the following command:

(cd /tmp; PGDATA=/opt/db/fwdcluster sudo startup_pg.sh &)

The database will be ready for connections via port 5432. If you need to have PostgreSQL listen on a different port, specify it with PGPORT=<port>.

Automated Startup

The dbash.sh command has options which will help automate the startup of PostgreSQL in the container:

       --pgport=<port> Use this port for PostgreSQL. The default is 5432. It will export PGPORT=<port>.
       --pgdata=<pgdata> Startup PostgreSQL using this cluster. It will export PGDATA=/opt/db/<pgdata>
       --detach = Run the container detached. Use "docker attach ..." to attach and "CTRL-p CTRL-q" to detach again.

If port 5432 is the port you are using, you do not need to specify --pgport=<port>. That is only if you want to use a different port.
If you specify the directory where the cluster resides with --pgdata=<pgdata>, the container will automatically attempt to startup PostgreSQL on that cluster. Output would look similar to:




	

Failure to Launch



	
There are 2 typical situations where PostgreSQL may have issues starting.



	
1. Wrong version



	
If the database was created with an older version than the version in the image, you would see something like the below:
dbash.sh -v hotel_db_postgres --pg17 -w --pgdata=fwdcluster
Running: docker run -e DBASH=true --name basedev_ubuntu_2404_pg17_latest_container -h basedev_ubuntu_2404_pg17_latest_container --rm -it -v hotel_db_postgres:/opt/db -v /home/rfb:/home/fwd --pull always -e PGPORT=5432 -e PGDATA=/opt/db/fwdcluster -e JDK_VERSION=17 -e HOST_UID=1000 -e HOST_GID=1000 -e HOME=/home/fwd -e USER=fwd -w /home/fwd goldencode/basedev_ubuntu_24.04_pg17:latest fwd -- bash 
latest: Pulling from goldencode/basedev_ubuntu_24.04_pg17
Digest: sha256:07c149e1dc22498b68c04633685d6d47b2d11b1bcf7d0bc36c1f5c2deeb78410
Status: Image is up to date for goldencode/basedev_ubuntu_24.04_pg17:latest
Warning: Running as root. This will affect all users.
INFO: Starting PostgreSQL cluster /opt/db/fwdcluster, port=5432...
pg_ctl: another server might be running; trying to start server anyway
Switched to JDK 17
waiting for server to start....
2026-07-02 16:53:50.208 EDT [65] FATAL:  database files are incompatible with server
2026-07-02 16:53:50.208 EDT [65] DETAIL:  The data directory was initialized by PostgreSQL version 14, which is not compatible with this version 17.10 (Ubuntu 17.10-1.pgdg24.04+1).
 stopped waiting
pg_ctl: could not start server
Examine the log output.
fwd@basedev_ubuntu_2404_pg17_latest_container:~$ 




	
You can pass the --pgxx option that matches with the database:
dbash.sh -v hotel_db_postgres --pg14 -w --pgdata=fwdcluster
Running: docker run -e DBASH=true --name basedev_ubuntu_2404_pg14_latest_container -h basedev_ubuntu_2404_pg14_latest_container --rm -it -v hotel_db_postgres:/opt/db -v /home/rfb:/home/fwd --pull always -e PGPORT=5432 -e PGDATA=/opt/db/fwdcluster -e JDK_VERSION=17 -e HOST_UID=1000 -e HOST_GID=1000 -e HOME=/home/fwd -e USER=fwd -w /home/fwd goldencode/basedev_ubuntu_24.04_pg14:latest fwd -- bash 
latest: Pulling from goldencode/basedev_ubuntu_24.04_pg14
Digest: sha256:92b7e8236344bfdcb636b55cbcf8ed012887cb0a15ba43ae0a0f221595cfa558
Status: Image is up to date for goldencode/basedev_ubuntu_24.04_pg14:latest
Warning: Running as root. This will affect all users.
INFO: Starting PostgreSQL cluster /opt/db/fwdcluster, port=5432...
pg_ctl: another server might be running; trying to start server anyway
waiting for server to start....
Switched to JDK 17
2026-07-02 16:58:25.854 EDT [57] LOG:  starting PostgreSQL 14.23 (Ubuntu 14.23-1.pgdg24.04+1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
2026-07-02 16:58:25.854 EDT [57] LOG:  listening on IPv4 address "0.0.0.0", port 5432
2026-07-02 16:58:25.854 EDT [57] LOG:  listening on IPv6 address "::", port 5432
2026-07-02 16:58:25.864 EDT [57] LOG:  listening on Unix socket "/opt/db/fwdcluster/.s.PGSQL.5432" 
2026-07-02 16:58:25.878 EDT [65] LOG:  database system was interrupted; last known up at 2026-06-29 10:27:22 EDT
...
2026-07-02 16:58:29.239 EDT [65] LOG:  database system was not properly shut down; automatic recovery in progress
2026-07-02 16:58:29.247 EDT [65] LOG:  redo starts at 0/331C930
2026-07-02 16:58:29.282 EDT [65] LOG:  invalid record length at 0/3544810: wanted 24, got 0
2026-07-02 16:58:29.282 EDT [65] LOG:  redo done at 0/35447D8 system usage: CPU: user: 0.00 s, system: 0.01 s, elapsed: 0.03 s
2026-07-02 16:58:29.626 EDT [57] LOG:  database system is ready to accept connections
 done
server started
✅ Cluster is running at: /opt/db/fwdcluster
fwd@basedev_ubuntu_2404_pg14_latest_container:~$




	
or you can migrate your database with the Migrator. See PostGreSQL Migration for details.



	
2. Improperly Stopped



	
When the database is improperly stopped, the next time the engine starts, it performs a recover. You can see that in the example output from above:
2026-07-02 16:58:29.239 EDT [65] LOG:  database system was not properly shut down; automatic recovery in progress
2026-07-02 16:58:29.247 EDT [65] LOG:  redo starts at 0/331C930
2026-07-02 16:58:29.282 EDT [65] LOG:  invalid record length at 0/3544810: wanted 24, got 0
2026-07-02 16:58:29.282 EDT [65] LOG:  redo done at 0/35447D8 system usage: CPU: user: 0.00 s, system: 0.01 s, elapsed: 0.03 s
2026-07-02 16:58:29.626 EDT [57] LOG:  database system is ready to accept connections




	
Most of the time the recovery goes smoothly. But once in a while it will take longer than the startup_pg.sh script will allow, and abort startup. You can override this by running the startup_pg.sh command manually with the --recovery option. This will allow for the startup to wait much longer for the recovery to finish:
sudo startup_pg.sh --recovery &




	

Start the Server



	
The server can be started using the ./start_server.sh script, or the ./server.sh script (if more control is needed). 
cd deploy/server
./start_server.sh




	
Debug Options
If there is a need to debug the server, the -d option can be passed to the ./server.sh wrapper script:
./server.sh -d




	
This sets the debugger to listen on port 2080 (see Testing Using Docker for more details), which you would attach to with Eclipse or your preferred IDE. If you need to debug the startup routines, you can include the -y option, and the JVM will start is suspended mode:
./server.sh -d -y




	

FWD Clients



	
You are still within the dbash.sh container, but now you want to access it from another session (or workstation). To make it accessible via certain ports, you need to have started the server allowing access via those ports. By default, dbash.sh allows access from clients via port 7443. However, if you want to access the container via ssh, port 22 in the container would need to be made available. There is an additional option to dbash.sh to allow manual port additions to the container:
--manual_port=<hport:cport>[,<hport:cport>...] include one or more port openings with "-p hport:cport".


So adding --manual_port=2202:22 adds an additional port for ssh. If dbash.sh is started with that option, you would be able to start sshd in the container with sudo service ssh start. There can be multiple ports listed, each separated by commas (no spaces). After that you can access the container via ssh from the host using:
ssh <user>@localhost -p 2202


or from a different host using:
ssh <user>@<hostname> -p 2202


where <hostname> is you hostname. This should allow you to run a ChUI application.



	
Of course the port 7443 is still available, so you can spawn a web ChUI using http://localhost:7443/chui if you application is setup to service that connection. Likewise http://localhost:7443/gui.



	
Note that Firefox will not allow the iframe unless you load a self-signed root certificate. Chrome does not have the same restriction.



	

Stop the Server



	
When you are done with your testing, you can run ./stop_server.sh



	

Stop the Database



	
You can stop the database with sudo shutdown_pg.sh







	
© 2004-2026 Golden Code Development Corporation.  ALL RIGHTS RESERVED.