Skip to content

development.md

Latest commit

 

History

History
490 lines (332 loc) · 10.9 KB

development.md

File metadata and controls

490 lines (332 loc) · 10.9 KB

init-database development

The following instructions are useful during development.

Note: This has been tested on Linux and Darwin/macOS. It has not been tested on Windows.

Prerequisites for development

🤔 The following tasks need to be complete before proceeding. These are "one-time tasks" which may already have been completed.

  1. The following software programs need to be installed:
    1. git
    2. make
    3. docker
    4. go

Install Senzing C library

Since the Senzing library is a prerequisite, it must be installed first.

  1. Verify Senzing C shared objects, configuration, and SDK header files are installed.

    1. /opt/senzing/er/lib
    2. /opt/senzing/er/sdk/c
    3. /etc/opt/senzing

  2. If not installed, see How to Install Senzing for Go Development.

Install Git repository

  1. Identify git repository.

    export GIT_ACCOUNT=senzing-garage
export GIT_REPOSITORY=init-database
export GIT_ACCOUNT_DIR=~/${GIT_ACCOUNT}.git
export GIT_REPOSITORY_DIR="${GIT_ACCOUNT_DIR}/${GIT_REPOSITORY}"

  2. Using the environment variables values just set, follow steps in clone-repository to install the Git repository.

Dependencies

  1. A one-time command to install dependencies needed for make targets. Example:

    cd ${GIT_REPOSITORY_DIR}
make dependencies-for-development

  2. Install dependencies needed for Go code. Example:

    cd ${GIT_REPOSITORY_DIR}
make dependencies

Lint

  1. Run linting. Example:

    cd ${GIT_REPOSITORY_DIR}
make lint

Build

  1. Build the binaries. Example:

    cd ${GIT_REPOSITORY_DIR}
make clean build

  2. The binaries will be found in the ${GIT_REPOSITORY_DIR}/target directory. Example:

    tree ${GIT_REPOSITORY_DIR}/target

Run

  1. Run program. Examples:

    1. Linux

      ${GIT_REPOSITORY_DIR}/target/linux-amd64/init-database

    2. macOS

      ${GIT_REPOSITORY_DIR}/target/darwin-amd64/init-database

    3. Windows

      ${GIT_REPOSITORY_DIR}/target/windows-amd64/init-database

  2. Clean up. Example:

    cd ${GIT_REPOSITORY_DIR}
make clean

Test

  1. Run tests. Example:

    cd ${GIT_REPOSITORY_DIR}
make clean setup test

  2. Optional: View the SQLite database. Example:

    docker run \
    --env SQLITE_DATABASE=G2C.db \
    --interactive \
    --publish 9174:8080 \
    --rm \
    --tty \
    --volume /tmp/sqlite:/data \
    coleifer/sqlite-web

    Visit localhost:9174.

Coverage

Create a code coverage map.

  1. Run Go tests. Example:

    cd ${GIT_REPOSITORY_DIR}
make clean setup coverage

    A web-browser will show the results of the coverage. The goal is to have over 80% coverage. Anything less needs to be reflected in testcoverage.yaml.

Documentation

  1. View documentation. Example:

    cd ${GIT_REPOSITORY_DIR}
make clean documentation

  2. If a web page doesn't appear, visit localhost:6060.

  3. Senzing documentation will be in the "Third party" section. github.com > senzing-garage > template-go

  4. When a versioned release is published with a v0.0.0 format tag, the reference can be found by clicking on the following badge at the top of the README.md page. Example:

    [![Go Reference Badge]][Go Reference]

  5. To stop the godoc server, run

    cd ${GIT_REPOSITORY_DIR}
make clean

Package

Package RPM and DEB files

  1. Use make target to run a Docker images that builds RPM and DEB files. Example:

    cd ${GIT_REPOSITORY_DIR}
make package

  2. The results will be in the ${GIT_REPOSITORY_DIR}/target directory. Example:

    tree ${GIT_REPOSITORY_DIR}/target

Test DEB package on Ubuntu

  1. Determine if init-database is installed. Example:

    apt list --installed | grep init-database

  2. ✏️ Install init-database. The init-database-... filename will need modification. Example:

    cd ${GIT_REPOSITORY_DIR}/target
sudo apt install ./init-database-0.0.0.deb

  3. ✏️ Identify database. One option is to bring up PostgreSQL as see in Test using Docker-compose stack with PostgreSQL database. Example:

    export SENZING_TOOLS_DATABASE_URL=sqlite3://na:na@/tmp/sqlite/G2C.db

  4. ✏️ Run command. Example:

    export LD_LIBRARY_PATH=/opt/senzing/er/lib/
init-database

  5. Remove init-database from system. Example:

    sudo apt-get remove init-database

Make documents

Make documents visible at hub.senzing.com/init-database.

  1. Identify repository. Example:

    export GIT_ACCOUNT=senzing
export GIT_REPOSITORY=init-database
export GIT_ACCOUNT_DIR=~/${GIT_ACCOUNT}.git
export GIT_REPOSITORY_DIR="${GIT_ACCOUNT_DIR}/${GIT_REPOSITORY}"

  2. Make documents. Example:

    export LD_LIBRARY_PATH=/opt/senzing/er/lib/
init-database docs --dir ${GIT_REPOSITORY_DIR}/docs

Docker compose instructions

SQLite

  1. Bring up Docker composition.

    docker-compose -f docker-compose/docker-compose.sqlite.yaml up

  2. Visit database at localhost:9174.

  3. Bring down Docker composition. --volumes is an optional parameter to delete the contents of the volumes.

    docker-compose -f docker-compose/docker-compose.sqlite.yaml down --volumes

PostgreSQL

  1. Bring up Docker composition.

    docker-compose -f docker-compose/docker-compose.postgresql.yaml up

  2. Visit database at localhost:9171.

    1. Login
      1. Username and Password are shown in "Senzing demonstration" box.
    2. On right-hand side, click on "Servers" > "senzing"
      1. Password: postgres

  3. Bring down Docker composition. --volumes is an optional parameter to delete the contents of the volumes.

    docker-compose -f docker-compose/docker-compose.postgresql.yaml down --volumes

MySQL

  1. Bring up Docker composition.

    docker-compose -f docker-compose/docker-compose.mysql.yaml up

  2. Visit database at localhost:9173.

    1. Login
      1. Username: mysql
      2. Password: mysql

  3. Bring down Docker composition. --volumes is an optional parameter to delete the contents of the volumes.

    docker-compose -f docker-compose/docker-compose.mysql.yaml down --volumes

MS SQL

  1. Bring up Docker composition.

    docker-compose -f docker-compose/docker-compose.mssql.yaml up

  2. Visit database at localhost:9177.

    1. Login
      1. System: MS SQL (beta)
      2. Server: senzing-mssql
      3. Username: sa
      4. Password: Passw0rd
      5. Database: G2

  3. Bring down Docker composition. --volumes is an optional parameter to delete the contents of the volumes.

    docker-compose -f docker-compose/docker-compose.mssql.yaml down --volumes

Oracle

  1. Bring up Docker composition.

    docker-compose -f docker-compose/docker-compose.oracle.yaml up

  2. xxx

  3. Bring down Docker composition. --volumes is an optional parameter to delete the contents of the volumes.

    docker-compose -f docker-compose/docker-compose.oracle.yaml down --volumes

Archive instructions

Test using Docker-compose stack with PostgreSQL database

The following instructions show how to bring up a test stack to be used in testing the sz-sdk-go-core packages.

  1. Identify a directory to place docker-compose artifacts. The directory specified will be deleted and re-created. Example:

    export SENZING_DEMO_DIR=~/my-senzing-demo

  2. Bring up the docker-compose stack. Example:

    export PGADMIN_DIR=${SENZING_DEMO_DIR}/pgadmin
export POSTGRES_DIR=${SENZING_DEMO_DIR}/postgres
export RABBITMQ_DIR=${SENZING_DEMO_DIR}/rabbitmq
export SENZING_VAR_DIR=${SENZING_DEMO_DIR}/var
export SENZING_UID=$(id -u)
export SENZING_GID=$(id -g)

rm -rf ${SENZING_DEMO_DIR:-/tmp/nowhere/for/safety}
mkdir ${SENZING_DEMO_DIR}
mkdir -p ${PGADMIN_DIR} ${POSTGRES_DIR} ${RABBITMQ_DIR} ${SENZING_VAR_DIR}
chmod -R 777 ${SENZING_DEMO_DIR}

curl -X GET \
    --output ${SENZING_DEMO_DIR}/docker-versions-stable.sh \
    https://raw.githubusercontent.com/senzing-garage/knowledge-base/main/lists/docker-versions-stable.sh
source ${SENZING_DEMO_DIR}/docker-versions-stable.sh
curl -X GET \
    --output ${SENZING_DEMO_DIR}/docker-compose.yaml \
    "https://raw.githubusercontent.com/senzing-garage/docker-compose-demo/main/resources/postgresql/docker-compose-postgresql-uninitialized.yaml"

cd ${SENZING_DEMO_DIR}
sudo --preserve-env docker-compose up

  3. In a separate terminal window, set environment variables. Identify Database URL of database in docker-compose stack. Example:

    export LOCAL_IP_ADDRESS=$(curl --silent https://raw.githubusercontent.com/senzing-garage/knowledge-base/main/gists/find-local-ip-address/find-local-ip-address.py | python3 -)
export SENZING_TOOLS_DATABASE_URL=postgresql://postgres:postgres@${LOCAL_IP_ADDRESS}:5432/er/?sslmode=disable

  4. Run tests.

    cd ${GIT_REPOSITORY_DIR}
make clean test

  5. Optional: View the PostgreSQL database.

    Visit localhost:9171. For the initial login, review the instructions at the top of the web page. For server password information, see the POSTGRESQL_POSTGRES_PASSWORD value in ${SENZING_DEMO_DIR}/docker-compose.yaml. Usually, it's "postgres".

  6. Cleanup.

    cd ${SENZING_DEMO_DIR}
sudo --preserve-env docker-compose down

cd ${GIT_REPOSITORY_DIR}
make clean

References