search

bcgov / biohubbc-taxonomy

Apache License 2.0
1 stars 0 forks source link

readme

Lifecycle:Experimental

BioDiversityHub BC

BioDiversityHub BC - Taxonomy

Sub-project under the BioHubBC project, the source of BC's taxonomy data.

The objectives for the BioHubBC Taxonomy project are:

Pre-reqs

Install Node/NPM

Install Git

Clone the repo

Install Docker

Windows

If prompted, install Docker using Hyper-V (not WSL 2)

Grant Docker access to your local folders

This setup for biohub taxonomy uses volumes to support live reload.
To leverage live reload you will need to ensure Docker is running using Hyper-V (not the WSL2 engine).

MacOS

Windows

Ensure you can run the make command

MacOS

Windows

Note: you will need to run choco commands in a terminal as administrator

Configuring Local IDE

You can use any code IDE you prefer, though VSCode is recommended.

For convenience, you can install all node_modules by running the following command from the repo's root folder.

make install

You can also manually run npm install in each of the /api/, /app/, and /database/ folders.

Building/Running the App

Note: Run all make commands from the root folder of the repo.

Note: Run all commands in a terminal that supports make. On Mac you can use the default Terminal, on Windows you can use git-bash.

Initialize the ./env file.

This will copy ./env_config/env.docker to ./.env.
This should only need to be run once.
This file may need additional editing to provide secrets for external services (like S3).

make env

Result of running make env for the first time:
make env screenshot

Start all BioHub Taxonomy Applications

Starts all applications (database, api, and web app).

make web

Result of running make web (condensed to only show the important parts):
make web screenshot

Access the Running Applications

api:

app:

Helpful Makefile Commands

See ./Makefile for all available commands.

Note: Run all make commands from the root folder of the repo.

Print Makefile Help Doc

make help

Install All Dependencies

Will run npm install in each of the project folders (api, app, database).

make install

Delete All Containers

Will stop and delete the biohub taxonomy docker containers.
This is useful when you want to clear out all database content, returning it to its initial default state.
After you've run make clean, running make web will launch new containers, with a fresh instance of the database.

make clean

View the logs for a container

API

make log-api

APP

make log-app

Database

make log-db

Database Setup (migrations + seeding)

make log-db-setup

Run Linter and Fix Issues

Will run the projects code linter and attempt to fix all issues found.

Note: Not all formatting issues can be auto-fixed.

make lint-fix

Run Formatter and Fix Issues

Will run the projects code formatter and attempt to fix all issues found.

Note: Not all formatting issues can be auto-fixed.

make format-fix

Shell Into a Docker Container (database, api, app)

Database

This is useful if you want to access the PSQL database through the CLI.
See DBeaver for a GUI-centric way of accessing the PSQL database.

make database

Api

make api

App

make app

Helpful Docker Commands

Show all running containers

docker ps

Show all containers (running and closed)

docker ps -a

What a successfully built/run set of docker containers looks like: make web screenshot

Note: The exited container is correct, as that container executes database migrations and then closes

View the logs for a container

docker logs <container id or name>
Include -f to "follow" the container logs, showing logs in real time

Prune Docker Artifacts

Over a long period time, Docker can run out of storage memory. When this happens, docker will log a message indicating it is out of memory.

The below command will delete docker artifacts to recover docker hard-drive space.

See documentation for OPTIONS.

docker system prune [OPTIONS]

Troubleshooting

Make Issues

If you get an error saying the make command is not found, you may need to install it first.
See Ensure you can run the make command

Docker Timezone Issue

While trying to run a make command such as make web, if you encounter an issue along the lines of:

E: Release file for http://deb.debian.org/debian/dists/buster-updates/InRelease is not valid yet (invalid for another 1d 1h 5min 13s). Updates for this repository will not be applied.

it may be possible that your system clock is out of date or not synced (dockerfile timezone has to match your machine timezone). In this case, make sure your timezone is correct and matches that of docker and restart your machine/terminal window and try again.

Database Container Wont Start

If you already had PSQL installed, it is likely that the default port 5432 is already in use and the instance running in Docker fails because it can't acquire that port.

Helpful Tools

DBeaver

GUI-centric application for viewing/interacting with Databases.

Pre-req

Add a new connection

Note: all of the above connection values can be found in the .env file

License

Copyright 2019 Province of British Columbia

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.