postgsail/docs

Architecture

Simple and scalable architecture.

For more clarity and visibility the complete Entity-Relationship Diagram (ERD) is export as Mermaid, PNG and SVG file.

Using PostgSail

A full-featured development environment.

Development

With CodeSandbox

• Develop on
  • or via direct link

With DevPod

• 
  • or via direct link

With Docker Dev Environments

• Open in Docker dev-envs!

On-premise (self-hosted)

pre-deploy configuration

To get these running, copy .env.example and rename to .env then set the value accordingly.

# cp .env.example .env

# nano .env

Notice, that PGRST_JWT_SECRET must be at least 32 characters long.

$ cat /dev/urandom | LC_ALL=C tr -dc 'a-zA-Z0-9' | fold -w 42 | head -n 1

PGSAIL_APP_URL is the url in you connect to in your browser.

PGSAIL_API_URL is the URL where PGSAIL_APP_URL connect to.

PGRST_DB_URI is the URI where the PGSAIL_API_URL connect to.

To summarize:

flowchart LR
    subgraph frontend
        direction TB
        A(PGSAIL_APP_URL)
        B(PGSAIL_API_URL)
    end
    subgraph backend
        direction TB
        B(PGSAIL_API_URL) -- SQL --> C(PGRST_DB_URI)
    end
    %% ^ These subgraphs are identical, except for the links to them:

    %% Link *to* subgraph1: subgraph1 direction is maintained

    User -- HTTP --> A
    User -- HTTP --> B
    %% Link *within* subgraph2:
    %% subgraph2 inherits the direction of the top-level graph (LR)

    Boat -- HTTP --> B

Deploy

By default there is no network set and all data are store in a docker volume. You can update the default settings by editing docker-compose.yml and docker-compose.dev.yml to your need.

First let's initialize the database.

Step 1. Initialize database

First let's import the SQL schema, execute:

$ docker compose up db

Step 2. Start backend (db, api)

Then launch the full stack (db, api) backend, execute:

$ docker compose up db api

The API should be accessible via port HTTP/3000. The database should be accessible via port TCP/5432.

You can connect to the database via a web gui like pgadmin or you can use a client dbeaver.

Step 3. Start frontend (web)

Then launch the web frontend, execute:

$ docker compose up web

The frontend should be accessible via port HTTP/8080.

SQL Configuration

Check and update your postgsail settings via SQL in the table app_settings:

SELECT * FROM app_settings;

UPDATE app_settings
    SET
        value = 'new_value'
    WHERE name = 'app.email_server';

As it is all about SQL, Read more about the database and explore your data.

Ingest data

Next, to ingest data from signalk, you need to install signalk-postgsail plugin on your signalk server instance.

Also, if you like, you can import saillogger data using the postgsail helpers, postgsail-helpers.

You might want to import your influxdb1 data as well, outflux. For InfluxDB 2.x and 3.x. You will need to enable the 1.x APIs to use them. Consult the InfluxDB documentation for more details.

Last, if you like, you can import the sample data from Signalk NMEA Plaka by running the tests. If everything goes well all tests pass successfully and you should receive a few notifications by email or PushOver or Telegram. End-to-End (E2E) Testing.

$ docker-compose up tests

API Documentation

The OpenAPI description output depends on the permissions of the role that is contained in the JWT role claim.

Other applications can also use the PostgSAIL API.

API anonymous:

$ curl http://localhost:3000/

API user_role:

$ curl http://localhost:3000/ -H 'Authorization: Bearer my_token_from_login_or_signup_fn'

API vessel_role:

$ curl http://localhost:3000/ -H 'Authorization: Bearer my_token_from_register_vessel_fn'

API main workflow

Check the End-to-End (E2E) test sample.

Docker dependencies

docker-compose is used to start environment dependencies. Dependencies consist of 3 containers:

• timescaledb-postgis alias db, PostgreSQL with TimescaleDB extension along with the PostGIS extension.
• postgrest alias api, Standalone web server that turns your PostgreSQL database directly into a RESTful API.
• grafana alias app, visualize and monitor your data

Optional docker images

• pgAdmin, web UI to monitor and manage multiple PostgreSQL
• Swagger, web UI to visualize documentation from PostgREST

docker-compose -f docker-compose-optional.yml up