This is an Open Horizon configuration to deploy a vanilla instance of the open-source PostgreSQL database software. This service is intended to be used as an edge service that provides PostgreSQL database functionality to other services running on the same edge node. It is not intended to be a production-ready database server, but rather a lightweight way to provide a database for development or testing purposes.
Management Hub: Install the Open Horizon Management Hub or have access to an existing hub in order to publish this service and register your edge node. You may also choose to use a downstream commercial distribution based on Open Horizon, such as IBM's Edge Application Manager. If you'd like to use the Open Horizon community hub, you may apply for a temporary account and have credentials sent to you.
Edge Node: You will need an x86 computer running Linux or macOS, or a Raspberry Pi computer (arm64) running Raspberry Pi OS or Ubuntu to install and use the Postgres database service as deployed by Open Horizon. You will need to install the Open Horizon agent software, anax, on the edge node and register it with a hub.
Optional utilities to install: With brew on macOS (you may need to install that as well), apt-get on Ubuntu or Raspberry Pi OS, yum on Fedora, install gcc, make, git, jq, curl, net-tools. Not all of those may exist on all platforms, and some may already be installed. But reflexively installing those has proven helpful in having the right tools available when you need them.
Clone the service-postgresql GitHub repo from a terminal prompt on the edge node and enter the folder where the artifacts were copied.
NOTE: This assumes that git has been installed on the edge node.
git clone https://github.com/open-horizon-services/service-postgresql.git
cd service-postgresqlRun make clean to confirm that the "make" utility is installed and working.
Confirm that you have the Open Horizon agent installed by using the CLI to check the version:
hzn versionIt should return values for both the CLI and the Agent (actual version numbers may vary from those shown):
Horizon CLI version: 2.30.0-744
Horizon Agent version: 2.30.0-744
If it returns "Command not found", then the Open Horizon agent is not installed.
If it returns a version for the CLI but not the agent, then the agent is installed but not running. You may run it with systemctl horizon start on Linux or horizon-container start on macOS.
Check that the agent is in an unconfigured state, and that it can communicate with a hub. If you have the jq utility installed, run hzn node list | jq '.configstate.state' and check that the value returned is "unconfigured". If not, running make agent-stop or hzn unregister -f will put the agent in an unconfigured state. Run hzn node list | jq '.configuration' and check that the JSON returned shows values for the "exchange_version" property, as well as the "exchange_api" and "mms_api" properties showing URLs. If those do not, then the agent is not configured to communicate with a hub. If you do not have jq installed, run hzn node list and eyeball the sections mentioned above.
NOTE: If "exchange_version" is showing an empty value, you will not be able to publish and run the service. The only fix found to this condition thus far is to re-install the agent using these instructions:
hzn unregister -f # to ensure that the node is unregistered
systemctl horizon stop # for Linux, or "horizon-container stop" on macOS
export HZN_ORG_ID=myorg # or whatever you customized it to
export HZN_EXCHANGE_USER_AUTH=admin:<admin-pw> # use the pw deploy-mgmt-hub.sh displayed
export HZN_FSS_CSSURL=http://<mgmt-hub-ip>:9443/
curl -sSL https://github.com/open-horizon/anax/releases/latest/download/agent-install.sh | bash -s -- -i anax: -k css: -c css: -p IBM/pattern-ibm.helloworld -w '*' -T 120To manually run PostgreSQL locally as a test, enter make. Running make attach will connect you to a prompt running inside the container, and you can end that session by entering exit. When you are done, run make stop in the terminal to end the test.
Populate the Secrets Manager before publishing services:
hzn sm secret add --secretKey=user --secretDetail=<username> secret_user
hzn sm secret add --secretKey=password --secretDetail=<password> secret_password
hzn sm secret add --secretKey=db --secretDetail=<databaseName> secret_dbThe first time you intend to run this on a host, run sudo -sE make init. This will create the volume that persists data across container restarts. It will also create the directory that the database is stored in and ensure it has the proper permissions.
If you are not running as root, you must add the current user account to the docker group so that it can run docker commands without sudo: sudo usermod -a -G docker $USER.
To create the service definition, publish it to the hub, and then form an agreement to download and run PostgreSQL, enter make publish. When installation is complete and an agreement has been formed, exit the watch command with Control-C.
NOTE: If you are planning to run this on the same host as the exchange, there will be a port conflict. Change the port numbers (5432) in both the Makefile and the service.definition.json before publishing and using.
The Makefile includes several targets to assist you in inspecting what is happening to see if they match your expectations. They include:
make log to see both the event logs and the service logs.
make check to see the values in your environment variables and how they compare to the default values. It will also show the service definition file with those values filled in.
make deploy-check to see if the properties and constraints that you've configured match each other to potentially form an agreement.
make test to see if the web server is responding.
make attach to connect to the running container and open a shell inside it.
Note The service-postgresql container by default runs in un-privileged mode.
default- init run browseinit- optionally create the docker volumerun- manually run the postgres container locally as a testcheck- view current settingsstop- halt a locally-run containerdev- manually run postgresql locally and connect to a terminal in the containerattach- connect to a terminal in the postgresql containertest- request the web UI from the terminal to confirm that it is running and availableclean- remove the container image and docker volumedistclean- clean (see above) AND unregister the node and remove the service files from the hubbuild- N/Apush- N/Apublish-service- Publish the service definition file to the hub in your organizationremove-service- Remove the service definition file from the hub in your organizationpublish-deployment-policy- Publish a deployment policy for the service to the hub in your orgremove-deployment-policy- Remove a deployment policy for the service from the hub in your orgagent-run- register your agent's node policy with the hubpublish- Publish the service def, deployment policy, and then register your agentagent-stop- unregister your agent with the hub, halting all agreements and stopping containersdeploy-check- confirm that a registered agent is compatible with the service and deploymentlog- check the agent event logs