README
¶
@go-nostr/nostr
⚠️ WARNING: This project is actively under development and no stable releases have been made yet. ⚠️
Please be aware that the code and documentation may contain unfinished features or inconsistencies. We appreciate your interest in the project and encourage you to check back for updates on progress towards a stable release.
Roadmap:
| Status | Milestone | Description |
|---|---|---|
| In-progress | nostr |
core package for use by external applications and executable |
| In-progress | internal/cli |
command-line client interface for Nostr client |
| To-do | internal/cmd |
relay server with persistent data repositories |
| To-do | internal/docs |
documentation site built with Hugo |
| To-do | internal/web |
web client and relay administrator interface built with Angular |
Overview
All-in-one Angular/Go/Hugo monorepo for the Nostr protocol, featuring comprehensive documentation, an all-in-one Go executable and reusable packages with an Angular web client.
Getting Started
Prerequisites
Before starting development, make sure to install the following dependencies:
Installation
After prerequisites have been installed, use the following shell commands from the project directory to install dependencies:
Install Go dependencies
Fetch and install all Go dependencies for the project. The -d flag ensures that the packages are downloaded only, without installing them.
go get -d ./...
Install NPM dependencies
Install all NPM dependencies for the monorepo workspaces. The -ws flag ensures that the installation is performed across all workspaces.
npm i -ws
Usage
To instantly set up and run the Nostr application, simply execute the following Docker command. This will pull the latest Nostr image, map the necessary ports, and get your local instance up and running:
docker run -p 3001:3001 -p 4200:4200 ghcr.io/go-nostr/nostr:latest
Build Docker image
Create a Docker image for the application by using the Dockerfile in the repository. This command will build the image and tag it with the name 'nostr'.
docker build -t nostr -f internal/config/Dockerfile .
Build Docker services
Build all the services defined in the docker-compose.yml file. This command will create Docker images for each service and store them locally.
docker-compose -f ./internal/config/docker-compose.yml build --no-cache
Build Hugo site
Build the Hugo documentation site maintained in the internal/docs directory. This command will build the Hugo the documentation site for distribution, placing the output in the internal/docs/public directory.
hugo -s internal/docs # exclude drafts
hugo -s internal/docs -D # include drafts
Build NPM packages
Compile and build all NPM packages in the monorepo, considering their interdependencies. The -ws flag ensures that the build is performed across all workspaces.
npm run build -ws
Format Go files
Format all Go source files in the repository by running the Go formatter. This ensures consistent coding style across the project.
go fmt ./...
Generate Go dependencies
Automatically generate code for Go dependencies, such as mocks, based on the source files. This command should be executed whenever there are changes to the Go source files.
go generate ./...
Run Docker image
Run the Docker image defined in the Dockerfile file. This command will run the image and display the logs in the console.
docker run -p 3001:3001 -p 4200:4200 nostr
Run Docker services
Start all the Docker services defined in the docker-compose.yml file. This command will run the containers and display the logs in the console.
docker-compose -f ./internal/config/docker-compose.yml up --build
Run Go tests
Execute all Go tests in the repository, including unit and integration tests. This command will also display a summary of the test results.
go test ./...
Run Hugo server
Build and serve the Hugo documentation site maintained in the internal/docs directory. This command will start the Hugo server and generate the documentation site, which can be accessed in a web browser.
hugo server -s internal/docs # exclude drafts
hugo server -s internal/docs -D # include drafts
Run NPM tests
Run all NPM tests in the monorepo, considering their interdependencies. The -ws flag ensures that the tests are executed across all workspaces.
npm test -ws
Contributing
If you're an Angular or Go developer looking to help advance the Nostr protocol, we'd love your help! To get started, make sure you're familiar with the Nostr protocol and comfortable creating pull requests and issues.
Before contributing, please take a moment to familiarize yourself with our project's vision by reading our VISION document. We also suggest contributors follow our CODE_OF_CONDUCT to maintain good vibes.
Deployment
The deployment process is handled by GitHub Actions, with separate workflows for Angular, Docker, Go, and Hugo. When a push is made, the Angular workflow runs, building the application, running tests, and linting the code. The built Angular application is then archived into a dist.tar file, which is uploaded as a build artifact.
On pushes to the main branch, the Docker workflow builds and pushes a Docker image to the GitHub Container Registry (GHCR), supporting both amd64 and arm64 platforms. The Go workflow runs in parallel, checking Go code formatting, building NPM packages, and running Go tests. The Hugo workflow, also triggered on pushes to the main branch, builds NPM packages and generates the Hugo site, uploading the artifacts and deploying them to GitHub Pages. This process ensures the codebase remains up-to-date and deployable, making it easy for current and future contributors to understand the project's deployment process.
| Badge | Description |
|---|---|
 |
Builds, tests, and lints the Angular application, and uploads the build artifacts. |
 |
Builds and pushes Docker images to the GitHub Container Registry. |
 |
Checks Go code formatting, generates Go dependencies, and runs Go tests. |
 |
Builds NPM packages, generates the Hugo site, and deploys to GitHub Pages. |
Built-with
This project is built with the following core technologies:
Acknowledgements
- @peaceiris for the Hugo GitHub Action
Authors
Versioning
This project uses semantic versioning and GitHub to publish new versions and manage releases.
License
This project is licensed under the terms of the LICENSE.
References
For additional materials helpful for contributors or users, please see:
Directories