Skip to content

Latest commit

 

History

History
280 lines (192 loc) · 13 KB

DEVELOPMENT.md

File metadata and controls

280 lines (192 loc) · 13 KB
███████╗██╗   ██╗██████╗ ███████╗██████╗  ██████╗ ██████╗ ███╗   ██╗██████╗ ██╗   ██╗ ██████╗████████╗ ██████╗ ██████╗
██╔════╝██║   ██║██╔══██╗██╔════╝██╔══██╗██╔════╝██╔═══██╗████╗  ██║██╔══██╗██║   ██║██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗
███████╗██║   ██║██████╔╝█████╗  ██████╔╝██║     ██║   ██║██╔██╗ ██║██║  ██║██║   ██║██║        ██║   ██║   ██║██████╔╝
╚════██║██║   ██║██╔═══╝ ██╔══╝  ██╔══██╗██║     ██║   ██║██║╚██╗██║██║  ██║██║   ██║██║        ██║   ██║   ██║██╔══██╗
███████║╚██████╔╝██║     ███████╗██║  ██║╚██████╗╚██████╔╝██║ ╚████║██████╔╝╚██████╔╝╚██████╗   ██║   ╚██████╔╝██║  ██║
╚══════╝ ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚═════╝  ╚═════╝  ╚═════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝

Development Mode

Requirements

$ java -version

java version "21.0.5" 2024-10-15 LTS
Java(TM) SE Runtime Environment (build 21.0.5+9-LTS-239)
Java HotSpot(TM) 64-Bit Server VM (build 21.0.5+9-LTS-239, mixed mode, sharing)

$ mvn -version

Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Java version: 21.0.5, vendor: Oracle Corporation

Build Superconductor

Build and install nostr-java dependency library

$ cd <your_git_home_dir>
$ git clone [email protected]:avlo/nostr-java-avlo-fork.git
$ cd nostr-java-avlo-fork
$ git checkout develop
$ mvn clean install

Build and install SuperConductor

$ cd <your_git_home_dir>
$ git clone https://github.com/avlo/superconductor
$ cd superconductor
$ mvn clean install

JUnit / SpringBootTest Superconductor

Two test modes, configurable via appication-test.properties file

1. Non-Secure (WS) tests mode

# ws autoconfigure
# security test (ws) disabled ('false') by default.
server.ssl.enabled=false                                           <--------  "false" for ws/non-secure
# ...
superconductor.relay.url=ws://localhost:5555                       <--------  "ws" protocol for ws/non-secure
2. Secure (WSS/TLS) tests mode
# wss autoconfigure
# to enable secure tests (wss), change below value to 'true' and...
server.ssl.enabled=true                                            <--------  "true" for wss/secure
# ...also for secure (wss), change below value to 'wss'...
superconductor.relay.url=wss://localhost:5555                      <--------  "wss" protocol for wss/secure

Configure SuperConductor run-time security, 3 options:

SecurityLevel Specification Details
Highest SSL Certificate WSS/HTTPS
(industry standard secure encrypted)		 1. Obtain an SSL certificate.
2. Install the certificate
3. Enable SSL configuration options in application-local_wss/dev_wss.properties file.
Medium Self-Signed Certificate WSS/HTTPS (locally created secure encrypted) 1. Create a Self-Signed Certificate.
2. Install the certificate
3. Enable SSL configuration options in application-local_wss/dev_wss.properties file.
None/Default WS/HTTP
non-secure / non-encrypted		 Security-related configuration(s) not required

Run SuperConductor (4 options)

1. Docker + Docker Compose

Confirm minimal docker requirements
$ docker --version

Docker version 27.5.0

$ docker compose version

Docker Compose version v2.32.4

(note: Confirmed compatible with Docker 27.0.3 and Docker Compose version v2.28.1 or higher. Earlier versions are at the liability of the developer/administrator)

Dockerize project

Superconductor spring boot docker uses buildpacks (preferential over Dockerfile)

$ mvn -N wrapper:wrapper
$ mvn spring-boot:build-image

(optionally edit docker-compose-dev_wss.yml parameters as applicable.)

Start docker containers
WSS/HTTPS

run without logging:

docker compose -f docker-compose-dev_wss.yml up

run with container logging displayed to console:

docker compose -f docker-compose-dev_wss.yml up --abort-on-container-failure --attach-dependencies

run with docker logging displayed to console:

docker compose -f docker-compose-dev_wss.yml up -d && dcls | grep 'superconductor-app' | awk '{print $1}' | xargs docker logs -f
WS/HTTP

run without logging:

docker compose -f docker-compose-dev_ws.yml up

run with container logging displayed to console:

docker compose -f docker-compose-dev_ws.yml up --abort-on-container-failure --attach-dependencies

run with docker logging displayed to console:

docker compose -f docker-compose-dev_ws.yml up -d && dcls | grep 'superconductor-app' | awk '{print $1}' | xargs docker logs -f
Stop docker containers
WSS/HTTPS 
docker compose -f docker-compose-dev_wss.yml stop superconductor superconductor-db
WS/HTTP 
docker compose -f docker-compose-prod_ws.yml stop superconductor superconductor-db
Remove docker containers
WSS/HTTPS 
docker compose -f docker-compose-dev_wss.yml down --remove-orphans
WS/HTTP 
docker compose -f docker-compose-prod_ws.yml down --remove-orphans

2. Run locally using maven spring-boot:run target

WSS/HTTPS 
cd <your_git_home_dir>/superconductor
mvn spring-boot:run -P local_wss
WS/HTTP 
cd <your_git_home_dir>/superconductor
mvn spring-boot:run -P local_ws

3. Run locally as executable jar

$ cd <your_git_home_dir>/superconductor
$ java -jar target/superconductor-1.11.0.war

4. Run using pre-existing local application-server-container instance

$ cp <your_git_home_dir>/superconductor/target/superconductor-1.11.0.war <your_container/instance/deployment_directory>

Relay Endpoint for clients

WSS/HTTPS 
wss://localhost:5555
WS/HTTP 
ws://localhost:5555

Default/embedded H2 DB console (local non-docker development mode):

localhost:5555/h2-console/

user: sa
password: // blank

Display all framework table contents (case-sensitive quoted fields/tables when querying):

select id, pub_key, session_id, challenge from auth;
select id, concat(left(event_id_string,10), '...') as event_id_string, kind, nip, created_at, concat(left(pub_key,10), '...') as pub_key, content from event;
select id, event_id, event_tag_id from "event-event_tag-join";
select id, event_id_string, recommended_relay_url, marker from event_tag;
select id, event_id, pubkey_id from "event-pubkey_tag-join";
select id, event_id from deletion_event;
select id, concat(left(public_key,10), '...') as public_key, main_relay_url, pet_name from pubkey_tag;
select id, event_id, subject_tag_id from "event-subject_tag-join";
select id, subject from subject_tag;
select id, hashtag_tag from hashtag_tag;
select id, location from geohash_tag;
select id, identifier from identifier_tag;
select id, event_id, geohash_tag_id from "event-geohash_tag-join";
select id, event_id, hash_tag_id from "event-hashtag_tag-join";
select id, event_id, generic_tag_id from "event-generic_tag-join";
select id, event_id, identifier_tag_id from "event-identifier_tag-join";
select id, code from generic_tag;
select id, generic_tag_id, element_attribute_id from "generic_tag-element_attribute-join";
select id, name, "value" from element_attribute;
select id, event_id, price_tag_id from "event-price_tag-join";
select id, uri from relays_tag;
select id, event_id, relays_id from "event-relays_tag-join";
select id, number, currency, frequency from price_tag;
(Optional Use) bundled web-client URLs for convenience/dev-testing/etc

http://localhost:5555/api-tests.html (nostr events web-client)

http://localhost:5555/request-test.html (nostr request web-client)

Adding new/custom events to SuperConductor

For Nostr clients generating canonical Nostr JSON (as defined in NIP01 spec: Basic protocol flow description, Events, Signatures and Tags), SuperConductor will automatically recognize those JSON events- including their database storage, retrieval and subscriber notification. No additional work or customization is necessary.

Adding new/custom tags to SuperConductor

SuperConductor supports any generic tags automatically. Otherwise, if custom tag structure is required, simply implement the TagPlugin interface (an example can be seen here) and your tag will automatically get included by SuperConductor after rebuilding and redeploying.