Update/040

.github/workflows/buildService.yml

@@ -4,33 +4,18 @@ on:
   workflow_dispatch:
   pull_request:
     paths-ignore: ['*.md']
-    branches: ['main', 'master']
+    branches: ['master']
   push:
     paths-ignore: ['*.md']
-    branches: ['main', 'master']
+    branches: ['master']
 
-jobs:
-  BuildPackage:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Prepare StartOS SDK
-        uses: Start9Labs/sdk@v1
-
-      - name: Checkout services repository
-        uses: actions/checkout@v3
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
 
-      - name: Build the service package
-        id: build
-        run: |
-          git submodule update --init --recursive
-          start-sdk init
-          make
-          PACKAGE_ID=$(yq -oy ".id" manifest.*)
-          echo "::set-output name=package_id::$PACKAGE_ID"
-        shell: bash
-
-      - name: Upload .s9pk
-        uses: actions/upload-artifact@v3
-        with:
-          name: ${{ steps.build.outputs.package_id }}.s9pk
-          path: ./${{ steps.build.outputs.package_id }}.s9pk
+jobs:
+  build:
+    if: github.event.pull_request.draft == false
+    uses: start9labs/shared-workflows/.github/workflows/buildService.yml@master
+    secrets:
+      DEV_KEY: ${{ secrets.DEV_KEY }}

.github/workflows/releaseService.yml

@@ -6,66 +6,14 @@ on:
       - 'v*.*'
 
 jobs:
-  ReleasePackage:
-    runs-on: ubuntu-latest
+  release:
+    uses: start9labs/shared-workflows/.github/workflows/releaseService.yml@master
+    with:
+      REGISTRY: ${{ vars.REGISTRY }}
+      S3_S9PKS_BASE_URL: ${{ vars.S3_S9PKS_BASE_URL }}
+    secrets:
+      DEV_KEY: ${{ secrets.DEV_KEY }}
+      S3_ACCESS_KEY: ${{ secrets.S3_ACCESS_KEY }}
+      S3_SECRET_KEY: ${{ secrets.S3_SECRET_KEY }}
     permissions:
       contents: write
-    steps:
-      - name: Prepare StartOS SDK
-        uses: Start9Labs/sdk@v1
-
-      - name: Checkout services repository
-        uses: actions/checkout@v3
-
-      - name: Build the service package
-        run: |
-          git submodule update --init --recursive
-          start-sdk init
-          make
-
-      - name: Setting package ID and title from the manifest
-        id: package
-        run: |
-          echo "::set-output name=package_id::$(yq -oy ".id" manifest.*)"
-          echo "::set-output name=package_title::$(yq -oy ".title" manifest.*)"
-        shell: bash
-
-      - name: Generate sha256 checksum
-        run: |
-          PACKAGE_ID=${{ steps.package.outputs.package_id }}
-          sha256sum ${PACKAGE_ID}.s9pk > ${PACKAGE_ID}.s9pk.sha256
-        shell: bash
-
-      - name: Generate changelog
-        run: |
-          PACKAGE_ID=${{ steps.package.outputs.package_id }}
-          echo "## What's Changed" > change-log.txt
-          yq e '.release-notes' manifest.yaml >> change-log.txt
-          echo "## SHA256 Hash" >> change-log.txt
-          echo '```' >> change-log.txt
-          sha256sum ${PACKAGE_ID}.s9pk >> change-log.txt
-          echo '```' >> change-log.txt
-        shell: bash
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v1
-        with:
-          tag_name: ${{ github.ref_name }}
-          name: ${{ steps.package.outputs.package_title }} ${{ github.ref_name }}
-          prerelease: true
-          body_path: change-log.txt
-          files: |
-            ./${{ steps.package.outputs.package_id }}.s9pk
-            ./${{ steps.package.outputs.package_id }}.s9pk.sha256
-
-      - name: Publish to Registry
-        env:
-          S9USER: ${{ secrets.S9USER }}
-          S9PASS: ${{ secrets.S9PASS }}
-          S9REGISTRY: ${{ secrets.S9REGISTRY }}
-        run: |
-          if [[ -z "$S9USER" || -z "$S9PASS" || -z "$S9REGISTRY" ]]; then
-            echo "Publish skipped: missing registry credentials."
-          else
-            start-sdk publish https://$S9USER:$S9PASS@$S9REGISTRY ${{ steps.package.outputs.package_id }}.s9pk
-          fi

.gitignore

@@ -1,4 +1,8 @@
-lightning-terminal.s9pk
-image.tar
+*.s9pk
+startos/*.js
+node_modules/
+.DS_Store
 .vscode/
-docker-images/
+docker-images
+javascript
+ncc-cache

CLAUDE.md

@@ -0,0 +1,2 @@
+## How the upstream version is pulled
+- dockerTag in `startos/manifest/index.ts`: `lightninglabs/lightning-terminal:v<version>`

CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+## Building and Development
+
+See the [StartOS Packaging Guide](https://docs.start9.com/packaging/) for complete environment setup and build instructions.
+
+### Quick Start
+
+```bash
+# Install dependencies
+npm ci
+
+# Build universal package
+make
+```

Makefile

@@ -1,34 +1,3 @@
-PKG_ID := $(shell yq e ".id" manifest.yaml)
-PKG_VERSION := $(shell yq e ".version" manifest.yaml)
-TS_FILES := $(shell find ./ -name \*.ts)
-
-# delete the target of a rule if it has changed and its recipe exits with a nonzero exit status
-.DELETE_ON_ERROR:
-
-all: verify
-
-verify: $(PKG_ID).s9pk
-	start-sdk verify s9pk $(PKG_ID).s9pk
-
-install: $(PKG_ID).s9pk
-	start-cli package install $(PKG_ID).s9pk
-
-clean:
-	rm -rf docker-images
-	rm -f image.tar
-	rm -f $(PKG_ID).s9pk
-	rm -f scripts/*.js
-
-scripts/embassy.js: $(TS_FILES)
-	deno bundle scripts/embassy.ts scripts/embassy.js
-
-docker-images/x86_64.tar: Dockerfile docker_entrypoint.sh 
-	mkdir -p docker-images
-	docker buildx build --tag start9/$(PKG_ID)/main:$(PKG_VERSION) --platform=linux/amd64 --build-arg PLATFORM=amd64 -o type=docker,dest=docker-images/x86_64.tar .
-
-docker-images/aarch64.tar: Dockerfile docker_entrypoint.sh 
-	mkdir -p docker-images
-	docker buildx build --tag start9/$(PKG_ID)/main:$(PKG_VERSION) --platform=linux/arm64 --build-arg PLATFORM=arm64 -o type=docker,dest=docker-images/aarch64.tar .
-
-$(PKG_ID).s9pk: manifest.yaml instructions.md LICENSE icon.png scripts/embassy.js docker-images/aarch64.tar docker-images/x86_64.tar
-	start-sdk pack
+ARCHES := x86 arm
+# overrides to s9pk.mk must precede the include statement
+include s9pk.mk

README.md

@@ -1,57 +1,152 @@
-# Wrapper for Lightning Terminal
+<p align="center">
+  <img src="icon.svg" alt="Lightning Terminal Logo" width="21%">
+</p>
 
-`Lightning Terminal (LiT)` is a browser-based interface for managing channel liquidity. This .s9pk wrapper will allow you to run LiT on your Start9 Server.
+# Lightning Terminal on StartOS
 
-## StartOS Service Pre-Requisites:
+> **Upstream docs:** <https://docs.lightning.engineering/lightning-network-tools/lightning-terminal>
+>
+> Everything not listed in this document should behave the same as upstream
+> Lightning Terminal. If a feature, setting, or behavior is not mentioned here, the
+> upstream documentation is accurate and fully applicable.
 
-- [lnd](https://github.com/Start9Labs/lnd-wrapper)
+A browser-based interface for managing channel liquidity on a self-hosted LND node. See the [upstream repo](https://github.com/lightninglabs/lightning-terminal) for general Lightning Terminal documentation.
 
-## Dependencies
+---
 
-- [docker](https://docs.docker.com/get-docker)
-- [docker-buildx](https://docs.docker.com/buildx/working-with-buildx/)
-- [yq](https://mikefarah.gitbook.io/yq)
-- [toml](https://crates.io/crates/toml-cli)
-- [start-sdk](https://github.com/Start9Labs/start-os/tree/master/backend)
-- [make](https://www.gnu.org/software/make/)
+## Table of Contents
 
-## Build enviroment
+- [Image and Container Runtime](#image-and-container-runtime)
+- [Volume and Data Layout](#volume-and-data-layout)
+- [Installation and First-Run Flow](#installation-and-first-run-flow)
+- [Configuration Management](#configuration-management)
+- [Network Access and Interfaces](#network-access-and-interfaces)
+- [Actions](#actions-startos-ui)
+- [Backups and Restore](#backups-and-restore)
+- [Health Checks](#health-checks)
+- [Dependencies](#dependencies)
+- [Limitations and Differences](#limitations-and-differences)
+- [What Is Unchanged from Upstream](#what-is-unchanged-from-upstream)
+- [Contributing](#contributing)
+- [Quick Reference for AI Consumers](#quick-reference-for-ai-consumers)
 
-Before building the lightning terminal package, your build environment must be setup for building StartOS services. Instructions for setting up the proper build environment can be found in the [Developer Docs](https://docs.start9.com/latest/developer-docs/packaging).
+---
 
+## Image and Container Runtime
 
-## Cloning
+| Property | Value |
+|----------|-------|
+| Image | `lightninglabs/lightning-terminal` (upstream, unmodified) |
+| Architectures | x86_64, aarch64 |
+| Entrypoint | `/bin/litd` |
 
-Clone the project locally. Note the submodule link to the original project(s).
+## Volume and Data Layout
 
-```
-git clone https://github.com/Start9Labs/lightning-terminal-wrapper.git
-cd lightning-terminal-wrapper
-git submodule update --init --recursive
-```
+| Volume | Mount Point | Purpose |
+|--------|-------------|---------|
+| `main` | `/root` | All LiT data (configuration, application state) |
 
-## Building
+StartOS-specific files on the `main` volume:
 
-To build the project, run the following commands:
+| File | Purpose |
+|------|---------|
+| `.lit/lit.conf` | LiT configuration (managed by StartOS) |
 
-```
-make
-```
+The LND `main` volume is mounted read-only at `/mnt/lnd` for macaroon and TLS certificate access.
 
-## Installing (on StartOS)
+## Installation and First-Run Flow
 
-Run the following commands to determine successful install:
-> :information_source: Change server-name.local to your Start9 server address
+1. On install, StartOS creates a **critical task** prompting the user to set an admin password via the **Create Password** action
+2. The `.lit/lit.conf` file is written with default configuration and the generated password
+3. LiT connects to the running LND node using the mounted macaroon and TLS certificate
 
-```
-start-cli auth login
-#Enter your StartOS password
-start-cli --host https://server-name.local package install lightning-terminal.s9pk
-```
-**Tip:** You can also install the lightning-terminal.s9pk using **Sideload Service** under the **System > Manage** section.
+## Configuration Management
+
+LiT is configured via the `.lit/lit.conf` file, managed by StartOS. There are no user-configurable settings exposed through StartOS actions — the admin password is the only managed value.
+
+Settings managed by StartOS (hardcoded):
+
+| Setting | Value | Reason |
+|---------|-------|--------|
+| `uipassword` | Auto-generated | Set via Create/Reset Password action |
+| `lit-dir` | `/root` | Maps to the mounted volume |
+| `insecure-httplisten` | `lightning-terminal.startos:8443` | StartOS service networking |
+| `remote.lnd.rpcserver` | `lnd.startos:10009` | StartOS service networking |
+| `remote.lnd.macaroonpath` | `/mnt/lnd/data/chain/bitcoin/mainnet/admin.macaroon` | Mounted dependency volume |
+| `remote.lnd.tlscertpath` | `/mnt/lnd/tls.cert` | Mounted dependency volume |
+
+## Network Access and Interfaces
+
+| Interface | Port | Protocol | Purpose |
+|-----------|------|----------|---------|
+| Web UI | 8443 | HTTP | Lightning Terminal web interface |
+
+## Actions (StartOS UI)
+
+| Action | Purpose | Availability | Inputs |
+|--------|---------|-------------|--------|
+| **Create/Reset Password** | Generate a random 22-character admin password for the web UI | Any | None |
+
+The action name changes dynamically: "Create Password" on first use, "Reset Password" thereafter. The generated password is displayed once as a copyable value.
+
+## Backups and Restore
 
-## Verify Install
+**Backed up:** The entire `main` volume (configuration, application data).
 
-Go to your StartOS Services page, select lightning-terminal and start the service.
+**Restore behavior:** Standard restore — the configuration and data are restored as-is. The configured LND node must be available.
 
-**Done!** 
+## Health Checks
+
+| Check | Method | Messages |
+|-------|--------|----------|
+| **Web Interface** | Port listening (8443) | Ready: "The web interface is ready" |
+
+## Dependencies
+
+| Dependency | Required | Purpose |
+|------------|----------|---------|
+| LND | Required | Lightning Network node access via gRPC |
+
+LND must be installed and running. LiT connects to LND using the admin macaroon and TLS certificate from the mounted volume.
+
+## Limitations and Differences
+
+1. **Remote mode only** — LiT runs in remote mode connecting to a separate LND instance; integrated mode (where LiT runs its own LND) is not available
+2. **No user-configurable settings** — all configuration is managed by StartOS; the only user action is password management
+3. **Password-only authentication** — the UI password is auto-generated via the StartOS action; there is no option to set a custom password manually
+
+## What Is Unchanged from Upstream
+
+- Lightning Loop (submarine swaps — Loop In and Loop Out)
+- Lightning Pool (channel liquidity marketplace)
+- Channel visualization and balance management
+- All web UI functionality
+- Faraday (channel analytics)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions and development workflow.
+
+---
+
+## Quick Reference for AI Consumers
+
+```yaml
+package_id: lightning-terminal
+image: lightninglabs/lightning-terminal
+architectures: [x86_64, aarch64]
+volumes:
+  main: /root
+ports:
+  ui: 8443
+dependencies:
+  - lnd (required)
+startos_managed_files:
+  - .lit/lit.conf
+actions:
+  - reset-password
+health_checks:
+  - port_listening: 8443
+backup_volumes:
+  - main
+```

assets/ABOUT.md

@@ -0,0 +1 @@
+Use the `/assets` directory to include additional files or scripts needed by your service.