Browse Source
- Add Gitea issue templates for bug reports and feature requests with structured YAML forms for version, database backend, and log level - Add GitHub Actions CI workflow for automated testing on push/PR - Add GitHub Actions release workflow for building multi-platform binaries on tag push with SHA256 checksums - Add CONTRIBUTING.md with development setup, PR guidelines, and commit message format documentation - Add DECENTRALIZE_NOSTR.md expansion plan outlining WireGuard tunnel, GUI installer, system tray, and proxy server architecture - Update allowed commands in Claude settings - Bump version to v0.35.5 Files modified: - .gitea/issue_template/: Bug report, feature request, and config YAML - .github/workflows/: CI and release automation workflows - CONTRIBUTING.md: New contributor guide - docs/plans/DECENTRALIZE_NOSTR.md: Expansion architecture plan - .claude/settings.local.json: Updated allowed commands - pkg/version/version: Version bump to v0.35.5 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>main
mleku
4 weeks ago
9 changed files with 881 additions and 2 deletions
@ -0,0 +1,118 @@ |
|||||||
|
name: Bug Report |
||||||
|
about: Report a bug or unexpected behavior in ORLY relay |
||||||
|
title: "[BUG] " |
||||||
|
labels: |
||||||
|
- bug |
||||||
|
body: |
||||||
|
- type: markdown |
||||||
|
attributes: |
||||||
|
value: | |
||||||
|
## Bug Report Guidelines |
||||||
|
|
||||||
|
Thank you for taking the time to report a bug. Please fill out the form below to help us understand and reproduce the issue. |
||||||
|
|
||||||
|
**Before submitting:** |
||||||
|
- Search [existing issues](https://git.mleku.dev/mleku/next.orly.dev/issues) to avoid duplicates |
||||||
|
- Check the [documentation](https://git.mleku.dev/mleku/next.orly.dev) for configuration guidance |
||||||
|
- Ensure you're running a recent version of ORLY |
||||||
|
|
||||||
|
- type: input |
||||||
|
id: version |
||||||
|
attributes: |
||||||
|
label: ORLY Version |
||||||
|
description: Run `./orly version` to get the version |
||||||
|
placeholder: "v0.35.4" |
||||||
|
validations: |
||||||
|
required: true |
||||||
|
|
||||||
|
- type: dropdown |
||||||
|
id: database |
||||||
|
attributes: |
||||||
|
label: Database Backend |
||||||
|
description: Which database backend are you using? |
||||||
|
options: |
||||||
|
- Badger (default) |
||||||
|
- Neo4j |
||||||
|
- WasmDB |
||||||
|
validations: |
||||||
|
required: true |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: description |
||||||
|
attributes: |
||||||
|
label: Bug Description |
||||||
|
description: A clear and concise description of the bug |
||||||
|
placeholder: Describe what happened and what you expected to happen |
||||||
|
validations: |
||||||
|
required: true |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: reproduction |
||||||
|
attributes: |
||||||
|
label: Steps to Reproduce |
||||||
|
description: Detailed steps to reproduce the behavior |
||||||
|
placeholder: | |
||||||
|
1. Start relay with `./orly` |
||||||
|
2. Connect with client X |
||||||
|
3. Perform action Y |
||||||
|
4. Observe error Z |
||||||
|
validations: |
||||||
|
required: true |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: expected |
||||||
|
attributes: |
||||||
|
label: Expected Behavior |
||||||
|
description: What did you expect to happen? |
||||||
|
validations: |
||||||
|
required: true |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: logs |
||||||
|
attributes: |
||||||
|
label: Relevant Logs |
||||||
|
description: | |
||||||
|
Include relevant log output. Set `ORLY_LOG_LEVEL=debug` or `trace` for more detail. |
||||||
|
This will be automatically formatted as code. |
||||||
|
render: shell |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: config |
||||||
|
attributes: |
||||||
|
label: Configuration |
||||||
|
description: | |
||||||
|
Relevant environment variables or configuration (redact sensitive values). |
||||||
|
This will be automatically formatted as code. |
||||||
|
render: shell |
||||||
|
placeholder: | |
||||||
|
ORLY_ACL_MODE=follows |
||||||
|
ORLY_POLICY_ENABLED=true |
||||||
|
ORLY_DB_TYPE=badger |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: environment |
||||||
|
attributes: |
||||||
|
label: Environment |
||||||
|
description: Operating system, Go version, etc. |
||||||
|
placeholder: | |
||||||
|
OS: Linux 6.8.0 |
||||||
|
Go: 1.25.3 |
||||||
|
Architecture: amd64 |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: additional |
||||||
|
attributes: |
||||||
|
label: Additional Context |
||||||
|
description: Any other context, screenshots, or information that might help |
||||||
|
|
||||||
|
- type: checkboxes |
||||||
|
id: checklist |
||||||
|
attributes: |
||||||
|
label: Checklist |
||||||
|
options: |
||||||
|
- label: I have searched existing issues and this is not a duplicate |
||||||
|
required: true |
||||||
|
- label: I have included version information |
||||||
|
required: true |
||||||
|
- label: I have included steps to reproduce the issue |
||||||
|
required: true |
||||||
@ -0,0 +1,8 @@ |
|||||||
|
blank_issues_enabled: false |
||||||
|
contact_links: |
||||||
|
- name: Documentation |
||||||
|
url: https://git.mleku.dev/mleku/next.orly.dev |
||||||
|
about: Check the repository documentation before opening an issue |
||||||
|
- name: Nostr Protocol (NIPs) |
||||||
|
url: https://github.com/nostr-protocol/nips |
||||||
|
about: For questions about Nostr protocol specifications |
||||||
@ -0,0 +1,118 @@ |
|||||||
|
name: Feature Request |
||||||
|
about: Suggest a new feature or enhancement for ORLY relay |
||||||
|
title: "[FEATURE] " |
||||||
|
labels: |
||||||
|
- enhancement |
||||||
|
body: |
||||||
|
- type: markdown |
||||||
|
attributes: |
||||||
|
value: | |
||||||
|
## Feature Request Guidelines |
||||||
|
|
||||||
|
Thank you for suggesting a feature. Please provide as much detail as possible to help us understand your proposal. |
||||||
|
|
||||||
|
**Before submitting:** |
||||||
|
- Search [existing issues](https://git.mleku.dev/mleku/next.orly.dev/issues) to avoid duplicates |
||||||
|
- Check if this is covered by an existing [NIP](https://github.com/nostr-protocol/nips) |
||||||
|
- Review the [documentation](https://git.mleku.dev/mleku/next.orly.dev) for current capabilities |
||||||
|
|
||||||
|
- type: dropdown |
||||||
|
id: category |
||||||
|
attributes: |
||||||
|
label: Feature Category |
||||||
|
description: What area of ORLY does this feature relate to? |
||||||
|
options: |
||||||
|
- Protocol (NIP implementation) |
||||||
|
- Database / Storage |
||||||
|
- Performance / Optimization |
||||||
|
- Policy / Access Control |
||||||
|
- Web UI / Admin Interface |
||||||
|
- Deployment / Operations |
||||||
|
- API / Integration |
||||||
|
- Documentation |
||||||
|
- Other |
||||||
|
validations: |
||||||
|
required: true |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: problem |
||||||
|
attributes: |
||||||
|
label: Problem Statement |
||||||
|
description: | |
||||||
|
What problem does this feature solve? Is this related to a frustration you have? |
||||||
|
A clear problem statement helps us understand the motivation. |
||||||
|
placeholder: "I'm always frustrated when..." |
||||||
|
validations: |
||||||
|
required: true |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: solution |
||||||
|
attributes: |
||||||
|
label: Proposed Solution |
||||||
|
description: | |
||||||
|
Describe the solution you'd like. Be specific about expected behavior. |
||||||
|
placeholder: "I would like ORLY to..." |
||||||
|
validations: |
||||||
|
required: true |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: alternatives |
||||||
|
attributes: |
||||||
|
label: Alternatives Considered |
||||||
|
description: | |
||||||
|
Describe any alternative solutions or workarounds you've considered. |
||||||
|
placeholder: "I've tried X but it doesn't work because..." |
||||||
|
|
||||||
|
- type: input |
||||||
|
id: nip |
||||||
|
attributes: |
||||||
|
label: Related NIP |
||||||
|
description: If this relates to a Nostr Implementation Possibility, provide the NIP number |
||||||
|
placeholder: "NIP-XX" |
||||||
|
|
||||||
|
- type: dropdown |
||||||
|
id: impact |
||||||
|
attributes: |
||||||
|
label: Scope of Impact |
||||||
|
description: How significant is this feature? |
||||||
|
options: |
||||||
|
- Minor enhancement (small quality-of-life improvement) |
||||||
|
- Moderate feature (adds useful capability) |
||||||
|
- Major feature (significant new functionality) |
||||||
|
- Breaking change (requires migration or config changes) |
||||||
|
validations: |
||||||
|
required: true |
||||||
|
|
||||||
|
- type: dropdown |
||||||
|
id: contribution |
||||||
|
attributes: |
||||||
|
label: Willingness to Contribute |
||||||
|
description: Would you be willing to help implement this feature? |
||||||
|
options: |
||||||
|
- "Yes, I can submit a PR" |
||||||
|
- "Yes, I can help with testing" |
||||||
|
- "No, but I can provide more details" |
||||||
|
- "No" |
||||||
|
validations: |
||||||
|
required: true |
||||||
|
|
||||||
|
- type: textarea |
||||||
|
id: additional |
||||||
|
attributes: |
||||||
|
label: Additional Context |
||||||
|
description: | |
||||||
|
Any other context, mockups, examples, or references that help explain the feature. |
||||||
|
|
||||||
|
For protocol features, include example event structures or message flows if applicable. |
||||||
|
|
||||||
|
- type: checkboxes |
||||||
|
id: checklist |
||||||
|
attributes: |
||||||
|
label: Checklist |
||||||
|
options: |
||||||
|
- label: I have searched existing issues and this is not a duplicate |
||||||
|
required: true |
||||||
|
- label: I have described the problem this feature solves |
||||||
|
required: true |
||||||
|
- label: I have checked if this relates to an existing NIP |
||||||
|
required: false |
||||||
@ -0,0 +1,53 @@ |
|||||||
|
name: CI |
||||||
|
|
||||||
|
on: |
||||||
|
push: |
||||||
|
branches: [main, develop] |
||||||
|
pull_request: |
||||||
|
branches: [main] |
||||||
|
|
||||||
|
jobs: |
||||||
|
test: |
||||||
|
runs-on: ubuntu-latest |
||||||
|
steps: |
||||||
|
- name: Checkout code |
||||||
|
uses: actions/checkout@v4 |
||||||
|
|
||||||
|
- name: Set up Go |
||||||
|
uses: actions/setup-go@v5 |
||||||
|
with: |
||||||
|
go-version: '1.23' |
||||||
|
|
||||||
|
- name: Download libsecp256k1 |
||||||
|
run: | |
||||||
|
wget -q https://git.mleku.dev/mleku/nostr/raw/branch/main/crypto/p8k/libsecp256k1.so -O libsecp256k1.so |
||||||
|
chmod +x libsecp256k1.so |
||||||
|
|
||||||
|
- name: Run tests |
||||||
|
run: | |
||||||
|
export LD_LIBRARY_PATH="${LD_LIBRARY_PATH:+$LD_LIBRARY_PATH:}$(pwd)" |
||||||
|
CGO_ENABLED=0 go test ./... |
||||||
|
|
||||||
|
- name: Build binary |
||||||
|
run: | |
||||||
|
CGO_ENABLED=0 go build -o orly . |
||||||
|
./orly version |
||||||
|
|
||||||
|
lint: |
||||||
|
runs-on: ubuntu-latest |
||||||
|
steps: |
||||||
|
- name: Checkout code |
||||||
|
uses: actions/checkout@v4 |
||||||
|
|
||||||
|
- name: Set up Go |
||||||
|
uses: actions/setup-go@v5 |
||||||
|
with: |
||||||
|
go-version: '1.23' |
||||||
|
|
||||||
|
- name: Check go mod tidy |
||||||
|
run: | |
||||||
|
go mod tidy |
||||||
|
git diff --exit-code go.mod go.sum |
||||||
|
|
||||||
|
- name: Run go vet |
||||||
|
run: CGO_ENABLED=0 go vet ./... |
||||||
@ -0,0 +1,154 @@ |
|||||||
|
name: Release |
||||||
|
|
||||||
|
on: |
||||||
|
push: |
||||||
|
tags: |
||||||
|
- 'v*' |
||||||
|
|
||||||
|
jobs: |
||||||
|
build: |
||||||
|
runs-on: ubuntu-latest |
||||||
|
strategy: |
||||||
|
matrix: |
||||||
|
include: |
||||||
|
- goos: linux |
||||||
|
goarch: amd64 |
||||||
|
platform: linux-amd64 |
||||||
|
ext: "" |
||||||
|
lib: libsecp256k1.so |
||||||
|
- goos: linux |
||||||
|
goarch: arm64 |
||||||
|
platform: linux-arm64 |
||||||
|
ext: "" |
||||||
|
lib: libsecp256k1.so |
||||||
|
- goos: darwin |
||||||
|
goarch: amd64 |
||||||
|
platform: darwin-amd64 |
||||||
|
ext: "" |
||||||
|
lib: libsecp256k1.dylib |
||||||
|
- goos: darwin |
||||||
|
goarch: arm64 |
||||||
|
platform: darwin-arm64 |
||||||
|
ext: "" |
||||||
|
lib: libsecp256k1.dylib |
||||||
|
- goos: windows |
||||||
|
goarch: amd64 |
||||||
|
platform: windows-amd64 |
||||||
|
ext: ".exe" |
||||||
|
lib: libsecp256k1.dll |
||||||
|
|
||||||
|
steps: |
||||||
|
- name: Checkout code |
||||||
|
uses: actions/checkout@v4 |
||||||
|
|
||||||
|
- name: Set up Go |
||||||
|
uses: actions/setup-go@v5 |
||||||
|
with: |
||||||
|
go-version: '1.23' |
||||||
|
|
||||||
|
- name: Set up Node.js |
||||||
|
uses: actions/setup-node@v4 |
||||||
|
with: |
||||||
|
node-version: '20' |
||||||
|
|
||||||
|
- name: Install bun |
||||||
|
run: | |
||||||
|
curl -fsSL https://bun.sh/install | bash |
||||||
|
echo "$HOME/.bun/bin" >> $GITHUB_PATH |
||||||
|
|
||||||
|
- name: Build Web UI |
||||||
|
run: | |
||||||
|
cd app/web |
||||||
|
$HOME/.bun/bin/bun install |
||||||
|
$HOME/.bun/bin/bun run build |
||||||
|
|
||||||
|
- name: Get version |
||||||
|
id: version |
||||||
|
run: echo "version=$(cat pkg/version/version)" >> $GITHUB_OUTPUT |
||||||
|
|
||||||
|
- name: Build binary |
||||||
|
env: |
||||||
|
CGO_ENABLED: 0 |
||||||
|
GOOS: ${{ matrix.goos }} |
||||||
|
GOARCH: ${{ matrix.goarch }} |
||||||
|
run: | |
||||||
|
VERSION=${{ steps.version.outputs.version }} |
||||||
|
OUTPUT="orly-${VERSION}-${{ matrix.platform }}${{ matrix.ext }}" |
||||||
|
go build -ldflags "-s -w -X main.version=${VERSION}" -o ${OUTPUT} . |
||||||
|
sha256sum ${OUTPUT} > ${OUTPUT}.sha256 |
||||||
|
|
||||||
|
- name: Download runtime library |
||||||
|
run: | |
||||||
|
VERSION=${{ steps.version.outputs.version }} |
||||||
|
LIB="${{ matrix.lib }}" |
||||||
|
wget -q "https://git.mleku.dev/mleku/nostr/raw/branch/main/crypto/p8k/${LIB}" -O "${LIB}" || true |
||||||
|
if [ -f "${LIB}" ]; then |
||||||
|
sha256sum "${LIB}" > "${LIB}.sha256" |
||||||
|
fi |
||||||
|
|
||||||
|
- name: Upload artifacts |
||||||
|
uses: actions/upload-artifact@v4 |
||||||
|
with: |
||||||
|
name: orly-${{ matrix.platform }} |
||||||
|
path: | |
||||||
|
orly-* |
||||||
|
libsecp256k1* |
||||||
|
|
||||||
|
release: |
||||||
|
needs: build |
||||||
|
runs-on: ubuntu-latest |
||||||
|
steps: |
||||||
|
- name: Checkout code |
||||||
|
uses: actions/checkout@v4 |
||||||
|
|
||||||
|
- name: Get version |
||||||
|
id: version |
||||||
|
run: echo "version=$(cat pkg/version/version)" >> $GITHUB_OUTPUT |
||||||
|
|
||||||
|
- name: Download all artifacts |
||||||
|
uses: actions/download-artifact@v4 |
||||||
|
with: |
||||||
|
path: artifacts |
||||||
|
merge-multiple: true |
||||||
|
|
||||||
|
- name: Create combined checksums |
||||||
|
run: | |
||||||
|
cd artifacts |
||||||
|
cat *.sha256 | sort -k2 > SHA256SUMS.txt |
||||||
|
rm -f *.sha256 |
||||||
|
|
||||||
|
- name: List release files |
||||||
|
run: ls -la artifacts/ |
||||||
|
|
||||||
|
- name: Create Release |
||||||
|
uses: softprops/action-gh-release@v1 |
||||||
|
with: |
||||||
|
name: ORLY ${{ steps.version.outputs.version }} |
||||||
|
body: | |
||||||
|
## ORLY ${{ steps.version.outputs.version }} |
||||||
|
|
||||||
|
### Downloads |
||||||
|
|
||||||
|
Download the appropriate binary for your platform. The `libsecp256k1` library is optional but recommended for better cryptographic performance. |
||||||
|
|
||||||
|
### Installation |
||||||
|
|
||||||
|
1. Download the binary for your platform |
||||||
|
2. (Optional) Download the corresponding `libsecp256k1` library |
||||||
|
3. Place both files in the same directory |
||||||
|
4. Make the binary executable: `chmod +x orly-*` |
||||||
|
5. Run: `./orly-*-linux-amd64` (or your platform's binary) |
||||||
|
|
||||||
|
### Verify Downloads |
||||||
|
|
||||||
|
```bash |
||||||
|
sha256sum -c SHA256SUMS.txt |
||||||
|
``` |
||||||
|
|
||||||
|
### Configuration |
||||||
|
|
||||||
|
See the [repository documentation](https://git.mleku.dev/mleku/next.orly.dev) for configuration options. |
||||||
|
files: | |
||||||
|
artifacts/* |
||||||
|
draft: false |
||||||
|
prerelease: false |
||||||
@ -0,0 +1,101 @@ |
|||||||
|
# Contributing to ORLY |
||||||
|
|
||||||
|
Thank you for your interest in contributing to ORLY! This document outlines the process for reporting bugs, requesting features, and submitting contributions. |
||||||
|
|
||||||
|
**Canonical Repository:** https://git.mleku.dev/mleku/next.orly.dev |
||||||
|
|
||||||
|
## Issue Reporting Policy |
||||||
|
|
||||||
|
### Before Opening an Issue |
||||||
|
|
||||||
|
1. **Search existing issues** to avoid duplicates |
||||||
|
2. **Check the documentation** in the repository |
||||||
|
3. **Verify your version** - run `./orly version` and ensure you're on a recent release |
||||||
|
4. **Review the CLAUDE.md** file for configuration guidance |
||||||
|
|
||||||
|
### Bug Reports |
||||||
|
|
||||||
|
Use the **Bug Report** template when reporting unexpected behavior. A good bug report includes: |
||||||
|
|
||||||
|
- **Version information** - exact ORLY version from `./orly version` |
||||||
|
- **Database backend** - Badger, Neo4j, or WasmDB |
||||||
|
- **Clear description** - what happened vs. what you expected |
||||||
|
- **Reproduction steps** - detailed steps to trigger the bug |
||||||
|
- **Logs** - relevant log output (use `ORLY_LOG_LEVEL=debug` or `trace`) |
||||||
|
- **Configuration** - relevant environment variables (redact secrets) |
||||||
|
|
||||||
|
#### Log Levels for Debugging |
||||||
|
|
||||||
|
```bash |
||||||
|
export ORLY_LOG_LEVEL=trace # Most verbose |
||||||
|
export ORLY_LOG_LEVEL=debug # Development debugging |
||||||
|
export ORLY_LOG_LEVEL=info # Default |
||||||
|
``` |
||||||
|
|
||||||
|
### Feature Requests |
||||||
|
|
||||||
|
Use the **Feature Request** template when suggesting new functionality. A good feature request includes: |
||||||
|
|
||||||
|
- **Problem statement** - what problem does this solve? |
||||||
|
- **Proposed solution** - specific description of desired behavior |
||||||
|
- **Alternatives considered** - workarounds you've tried |
||||||
|
- **Related NIP** - if this implements a Nostr protocol specification |
||||||
|
- **Impact assessment** - is this a minor tweak or major change? |
||||||
|
|
||||||
|
#### Feature Categories |
||||||
|
|
||||||
|
- **Protocol** - NIP implementations and Nostr protocol features |
||||||
|
- **Database** - Storage backends, indexing, query optimization |
||||||
|
- **Performance** - Caching, SIMD operations, memory optimization |
||||||
|
- **Policy** - Access control, event filtering, validation |
||||||
|
- **Web UI** - Admin interface improvements |
||||||
|
- **Operations** - Deployment, monitoring, systemd integration |
||||||
|
|
||||||
|
## Code Contributions |
||||||
|
|
||||||
|
### Development Setup |
||||||
|
|
||||||
|
```bash |
||||||
|
# Clone the repository |
||||||
|
git clone https://git.mleku.dev/mleku/next.orly.dev.git |
||||||
|
cd next.orly.dev |
||||||
|
|
||||||
|
# Build |
||||||
|
CGO_ENABLED=0 go build -o orly |
||||||
|
|
||||||
|
# Run tests |
||||||
|
./scripts/test.sh |
||||||
|
|
||||||
|
# Build with web UI |
||||||
|
./scripts/update-embedded-web.sh |
||||||
|
``` |
||||||
|
|
||||||
|
### Pull Request Guidelines |
||||||
|
|
||||||
|
1. **One feature/fix per PR** - keep changes focused |
||||||
|
2. **Write tests** - for new functionality and bug fixes |
||||||
|
3. **Follow existing patterns** - match the code style of surrounding code |
||||||
|
4. **Update documentation** - if your change affects configuration or behavior |
||||||
|
5. **Test your changes** - run `./scripts/test.sh` before submitting |
||||||
|
|
||||||
|
### Commit Message Format |
||||||
|
|
||||||
|
``` |
||||||
|
Short summary (72 chars max, imperative mood) |
||||||
|
|
||||||
|
- Bullet point describing change 1 |
||||||
|
- Bullet point describing change 2 |
||||||
|
|
||||||
|
Files modified: |
||||||
|
- path/to/file1.go: Description of change |
||||||
|
- path/to/file2.go: Description of change |
||||||
|
``` |
||||||
|
|
||||||
|
## Communication |
||||||
|
|
||||||
|
- **Issues:** https://git.mleku.dev/mleku/next.orly.dev/issues |
||||||
|
- **Documentation:** https://git.mleku.dev/mleku/next.orly.dev |
||||||
|
|
||||||
|
## License |
||||||
|
|
||||||
|
By contributing to ORLY, you agree that your contributions will be licensed under the same license as the project. |
||||||
@ -0,0 +1,325 @@ |
|||||||
|
# ORLY Expansion Plan: Documentation, Installer, Tray, and WireGuard |
||||||
|
|
||||||
|
## Overview |
||||||
|
|
||||||
|
Expand ORLY from a relay binary into a complete ecosystem for personal Nostr relay deployment, with: |
||||||
|
1. **Textbook-style README** - Progressive documentation from novice to expert |
||||||
|
2. **GUI Installer** - Wails-based setup wizard (Linux + macOS) |
||||||
|
3. **System Tray** - Service monitoring and control |
||||||
|
4. **WireGuard Client** - Embedded tunnel for NAT traversal |
||||||
|
5. **Proxy Server** - Self-hostable AND managed service option |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
## Architecture |
||||||
|
|
||||||
|
``` |
||||||
|
USER SYSTEMS |
||||||
|
┌─────────────────────────────────────────────────────────────────────┐ |
||||||
|
│ │ |
||||||
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ |
||||||
|
│ │ orly-setup │ │ orly │ │ orly --tray │ │ |
||||||
|
│ │ (Installer) │ │ (Relay) │ │ (Systray) │ │ |
||||||
|
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ |
||||||
|
│ │ │ │ │ |
||||||
|
│ │ generates │ serves │ monitors │ |
||||||
|
│ ▼ ▼ ▼ │ |
||||||
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ |
||||||
|
│ │ ~/.config/ │ │ :3334 WS/HTTP│ │ /api/admin/* │ │ |
||||||
|
│ │ systemd svc │ │ + WG tunnel │ │ status/ctrl │ │ |
||||||
|
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │ |
||||||
|
│ │ │ |
||||||
|
│ ┌───────┴───────┐ │ |
||||||
|
│ │ pkg/tunnel/ │ │ |
||||||
|
│ │ WireGuard │ │ |
||||||
|
│ └───────┬───────┘ │ |
||||||
|
└─────────────────────────────┼───────────────────────────────────────┘ |
||||||
|
│ WG Tunnel (UDP :51820) |
||||||
|
▼ |
||||||
|
┌─────────────────────────────────────────────────────────────────────┐ |
||||||
|
│ PROXY SERVER │ |
||||||
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ |
||||||
|
│ │ WG Server │───▶│ Nostr Auth │───▶│ Public Proxy │ │ |
||||||
|
│ │ :51820 │ │ (npub-based) │ │ Egress │ │ |
||||||
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │ |
||||||
|
└─────────────────────────────────────────────────────────────────────┘ |
||||||
|
``` |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
## Package Structure |
||||||
|
|
||||||
|
``` |
||||||
|
next.orly.dev/ |
||||||
|
├── cmd/ |
||||||
|
│ ├── orly-setup/ # NEW: Wails installer |
||||||
|
│ │ ├── main.go |
||||||
|
│ │ ├── app.go # Backend logic |
||||||
|
│ │ ├── frontend/ # Svelte wizard UI |
||||||
|
│ │ │ └── src/steps/ # Welcome, Config, Install, Complete |
||||||
|
│ │ └── install/ |
||||||
|
│ │ ├── preflight.go # Dependency checks |
||||||
|
│ │ ├── systemd.go # Service creation |
||||||
|
│ │ └── verify.go # Post-install checks |
||||||
|
│ │ |
||||||
|
│ └── proxy-server/ # NEW: WireGuard proxy |
||||||
|
│ ├── main.go |
||||||
|
│ ├── server.go # WG server |
||||||
|
│ ├── auth.go # Nostr auth |
||||||
|
│ └── registry.go # User management |
||||||
|
│ |
||||||
|
├── pkg/ |
||||||
|
│ ├── tunnel/ # NEW: Embedded WG client |
||||||
|
│ │ ├── tunnel.go # Main interface |
||||||
|
│ │ ├── client.go # wireguard-go wrapper |
||||||
|
│ │ ├── reconnect.go # Auto-reconnect |
||||||
|
│ │ └── health.go # Connection health |
||||||
|
│ │ |
||||||
|
│ ├── tray/ # NEW: System tray |
||||||
|
│ │ ├── tray.go # Platform abstraction |
||||||
|
│ │ ├── tray_linux.go # Linux implementation |
||||||
|
│ │ ├── tray_darwin.go # macOS implementation |
||||||
|
│ │ └── menu.go # Menu construction |
||||||
|
│ │ |
||||||
|
│ ├── admin/ # NEW: Admin HTTP API |
||||||
|
│ │ ├── api.go # Router |
||||||
|
│ │ ├── status.go # GET /api/admin/status |
||||||
|
│ │ ├── control.go # POST /api/admin/start|stop|restart |
||||||
|
│ │ └── logs.go # GET /api/admin/logs (SSE) |
||||||
|
│ │ |
||||||
|
│ └── interfaces/ |
||||||
|
│ ├── tunnel/tunnel.go # Tunnel interface |
||||||
|
│ ├── tray/tray.go # Tray interface |
||||||
|
│ └── admin/admin.go # Admin API interface |
||||||
|
│ |
||||||
|
└── docs/ |
||||||
|
└── README.adoc # NEW: Textbook-style docs |
||||||
|
``` |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
## Implementation Phases |
||||||
|
|
||||||
|
### Phase 1: Documentation Foundation |
||||||
|
**Files to create/modify:** |
||||||
|
- `README.adoc` - New textbook-style documentation |
||||||
|
- `docs/` - Reorganize scattered docs |
||||||
|
|
||||||
|
**README Structure (Textbook Style):** |
||||||
|
``` |
||||||
|
Chapter 1: Quick Start (5-minute setup) |
||||||
|
Chapter 2: Installation (platform-specific) |
||||||
|
Chapter 3: Configuration (all env vars) |
||||||
|
Chapter 4: Operations (systemd, monitoring) |
||||||
|
Chapter 5: Security (TLS, ACLs, policy) |
||||||
|
Chapter 6: Advanced (Neo4j, clustering, WoT) |
||||||
|
Chapter 7: Architecture (internals) |
||||||
|
Appendices: Reference tables, troubleshooting |
||||||
|
``` |
||||||
|
|
||||||
|
### Phase 2: Admin API |
||||||
|
**Files to create:** |
||||||
|
- `pkg/admin/api.go` - Router and middleware |
||||||
|
- `pkg/admin/status.go` - Status endpoint |
||||||
|
- `pkg/admin/control.go` - Start/stop/restart |
||||||
|
- `pkg/admin/logs.go` - Log streaming via SSE |
||||||
|
- `pkg/interfaces/admin/admin.go` - Interface definition |
||||||
|
|
||||||
|
**Files to modify:** |
||||||
|
- `app/server.go` - Register `/api/admin/*` routes |
||||||
|
- `app/config/config.go` - Add admin API config |
||||||
|
|
||||||
|
**Endpoints:** |
||||||
|
``` |
||||||
|
GET /api/admin/status - Relay status, uptime, connections |
||||||
|
POST /api/admin/start - Start relay (when in tray mode) |
||||||
|
POST /api/admin/stop - Graceful shutdown |
||||||
|
POST /api/admin/restart - Graceful restart |
||||||
|
GET /api/admin/logs - SSE log stream |
||||||
|
``` |
||||||
|
|
||||||
|
### Phase 3: System Tray |
||||||
|
**Files to create:** |
||||||
|
- `pkg/tray/tray.go` - Platform abstraction |
||||||
|
- `pkg/tray/tray_linux.go` - Linux (dbus/appindicator) |
||||||
|
- `pkg/tray/tray_darwin.go` - macOS (NSStatusBar) |
||||||
|
- `pkg/tray/menu.go` - Menu construction |
||||||
|
- `pkg/interfaces/tray/tray.go` - Interface |
||||||
|
|
||||||
|
**Files to modify:** |
||||||
|
- `main.go` - Add `--tray` flag handling |
||||||
|
- `app/config/config.go` - Add tray config |
||||||
|
|
||||||
|
**Features:** |
||||||
|
- Status icon (green/yellow/red) |
||||||
|
- Start/Stop/Restart menu items |
||||||
|
- Open Web UI (launches browser) |
||||||
|
- View Logs submenu |
||||||
|
- Auto-start on login toggle |
||||||
|
|
||||||
|
### Phase 4: Installer GUI (Wails) |
||||||
|
**Files to create:** |
||||||
|
- `cmd/orly-setup/main.go` - Wails entry point |
||||||
|
- `cmd/orly-setup/app.go` - Backend methods |
||||||
|
- `cmd/orly-setup/frontend/` - Svelte wizard |
||||||
|
- `cmd/orly-setup/install/preflight.go` - Dependency checks |
||||||
|
- `cmd/orly-setup/install/systemd.go` - Service creation |
||||||
|
- `cmd/orly-setup/install/config.go` - Config generation |
||||||
|
- `cmd/orly-setup/install/verify.go` - Post-install checks |
||||||
|
- `scripts/build-installer.sh` - Build script |
||||||
|
|
||||||
|
**Wizard Steps:** |
||||||
|
1. Welcome - Introduction, license |
||||||
|
2. Preflight - Check Go, disk, ports |
||||||
|
3. Configuration - Port, data dir, TLS domains |
||||||
|
4. Admin Setup - Generate or import admin keys |
||||||
|
5. Database - Choose Badger or Neo4j |
||||||
|
6. WireGuard (optional) - Tunnel config |
||||||
|
7. Installation - Create service, start relay |
||||||
|
8. Complete - Verify and show status |
||||||
|
|
||||||
|
### Phase 5: WireGuard Client |
||||||
|
**Files to create:** |
||||||
|
- `pkg/tunnel/tunnel.go` - Main interface |
||||||
|
- `pkg/tunnel/client.go` - wireguard-go wrapper |
||||||
|
- `pkg/tunnel/config.go` - WG configuration |
||||||
|
- `pkg/tunnel/reconnect.go` - Auto-reconnect logic |
||||||
|
- `pkg/tunnel/health.go` - Health monitoring |
||||||
|
- `pkg/tunnel/handoff.go` - Graceful restart |
||||||
|
- `pkg/interfaces/tunnel/tunnel.go` - Interface |
||||||
|
|
||||||
|
**Files to modify:** |
||||||
|
- `app/config/config.go` - Add WG config fields |
||||||
|
- `app/main.go` - Initialize tunnel on startup |
||||||
|
- `main.go` - Tunnel lifecycle management |
||||||
|
|
||||||
|
**Config additions:** |
||||||
|
```go |
||||||
|
WGEnabled bool `env:"ORLY_WG_ENABLED" default:"false"` |
||||||
|
WGServer string `env:"ORLY_WG_SERVER"` |
||||||
|
WGPrivateKey string `env:"ORLY_WG_PRIVATE_KEY"` |
||||||
|
WGServerPubKey string `env:"ORLY_WG_PUBLIC_KEY"` |
||||||
|
WGKeepalive int `env:"ORLY_WG_KEEPALIVE" default:"25"` |
||||||
|
WGMTU int `env:"ORLY_WG_MTU" default:"1280"` |
||||||
|
WGReconnect bool `env:"ORLY_WG_RECONNECT" default:"true"` |
||||||
|
``` |
||||||
|
|
||||||
|
### Phase 6: Proxy Server |
||||||
|
**Files to create:** |
||||||
|
- `cmd/proxy-server/main.go` - Entry point |
||||||
|
- `cmd/proxy-server/server.go` - WG server management |
||||||
|
- `cmd/proxy-server/auth.go` - Nostr-based auth |
||||||
|
- `cmd/proxy-server/registry.go` - User/relay registry |
||||||
|
- `cmd/proxy-server/bandwidth.go` - Traffic monitoring |
||||||
|
- `cmd/proxy-server/config.go` - Server configuration |
||||||
|
|
||||||
|
**Features:** |
||||||
|
- WireGuard server (wireguard-go) |
||||||
|
- Nostr event-based authentication (NIP-98 style) |
||||||
|
- User registration via signed events |
||||||
|
- Relay discovery and assignment |
||||||
|
- Bandwidth monitoring and quotas |
||||||
|
- Multi-tenant isolation |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
## Key Interfaces |
||||||
|
|
||||||
|
### Tunnel Interface |
||||||
|
```go |
||||||
|
type Tunnel interface { |
||||||
|
Connect(ctx context.Context) error |
||||||
|
Disconnect() error |
||||||
|
Status() TunnelStatus |
||||||
|
Handoff() (*HandoffState, error) |
||||||
|
Resume(state *HandoffState) error |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
### Admin API Interface |
||||||
|
```go |
||||||
|
type AdminAPI interface { |
||||||
|
Status() (*RelayStatus, error) |
||||||
|
Start() error |
||||||
|
Stop() error |
||||||
|
Restart() error |
||||||
|
Logs(ctx context.Context, lines int) (<-chan LogEntry, error) |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
### Tray Interface |
||||||
|
```go |
||||||
|
type TrayApp interface { |
||||||
|
Run() error |
||||||
|
Quit() |
||||||
|
UpdateStatus(status StatusLevel, tooltip string) |
||||||
|
ShowNotification(title, message string) |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
## Dependencies to Add |
||||||
|
|
||||||
|
```go |
||||||
|
// go.mod additions |
||||||
|
require ( |
||||||
|
github.com/wailsapp/wails/v2 v2.x.x // Installer GUI |
||||||
|
golang.zx2c4.com/wireguard v0.x.x // WireGuard client |
||||||
|
github.com/getlantern/systray v1.x.x // System tray (or fyne.io/systray) |
||||||
|
) |
||||||
|
``` |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
## Build Commands |
||||||
|
|
||||||
|
```bash |
||||||
|
# Standard relay build (unchanged) |
||||||
|
CGO_ENABLED=0 go build -o orly |
||||||
|
|
||||||
|
# Relay with tray support |
||||||
|
CGO_ENABLED=0 go build -tags tray -o orly |
||||||
|
|
||||||
|
# Installer GUI |
||||||
|
cd cmd/orly-setup && wails build -platform linux/amd64,darwin/amd64 |
||||||
|
|
||||||
|
# Proxy server |
||||||
|
CGO_ENABLED=0 go build -o orly-proxy ./cmd/proxy-server |
||||||
|
|
||||||
|
# All platforms |
||||||
|
./scripts/build-all.sh |
||||||
|
``` |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
## Critical Files Reference |
||||||
|
|
||||||
|
| File | Purpose | |
||||||
|
|------|---------| |
||||||
|
| `app/config/config.go` | Add WG, tray, admin API config | |
||||||
|
| `app/server.go` | Register admin API routes | |
||||||
|
| `main.go` | Add --tray flag, WG initialization | |
||||||
|
| `scripts/deploy.sh` | Pattern for installer service creation | |
||||||
|
| `app/web/src/App.svelte` | Pattern for installer UI | |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
## Backward Compatibility |
||||||
|
|
||||||
|
- Main `orly` binary behavior unchanged without flags |
||||||
|
- All new features opt-in via environment variables |
||||||
|
- WireGuard gracefully degrades if connection fails |
||||||
|
- Tray mode only activates with `--tray` flag |
||||||
|
- Admin API can be disabled via `ORLY_ADMIN_API_ENABLED=false` |
||||||
|
|
||||||
|
--- |
||||||
|
|
||||||
|
## Success Criteria |
||||||
|
|
||||||
|
1. New user can install via GUI wizard in < 5 minutes |
||||||
|
2. README guides user from zero to running relay |
||||||
|
3. System tray provides one-click relay management |
||||||
|
4. WireGuard tunnel auto-connects and reconnects |
||||||
|
5. Proxy server enables home relay exposure without port forwarding |
||||||
|
6. All existing functionality preserved |
||||||
Loading…
Reference in new issue