Station Headless Proposal v1

Motivation

Let operators run Station in headless mode, on servers and other machines that don’t have a graphical environment. This grows the Station ecosystem:

  • Station in data centers, with fast connections
  • Stations on always-on hardware
  • Stations on beefy hardware

High-level plan

Pull the core business logic out of Station Desktop into a CLI that can be run on servers and other headless environments.

Make Station Desktop also bundle that new CLI, in order to keep the code-base small.

Eventually let Station Desktop connect to the CLI over the network, for remote management use cases.

Projects overview

  • Station Core
    Station core node (this is new)
    https://github.com/filecoin-station/core
    npm install @filecoin-station/core
  • Station Desktop
    Desktop app (comes with Station node, slightly rebranded)
    Filecoin Station → Filecoin Station Desktop
    https://github.com/filecoin-station/desktop

Roadmap

Timelines assume mostly uninterrupted work by @Julian Gruber.

02/2023 M0 Experiment: Run electron app in virtual frame buffer ✅

Evaluate running Station Desktop (basically) unmodified inside a virtual frame-buffer. Can we just re-package the Desktop app for headless environments?

Tasks

Work absolutely required:

  • Skip onboarding

Missing core features that are trivial to implement:

  • Store module output in log files

Missing core features that are non-trivial:

  • Auto updates
  • Pass wallet address as env var

Assumption

This won’t be a fruitful path and therefore M1 and following will continue as planned.

Example usage

$ xvfb-run ./Station.app

# Get latest metrics
$ cat ~/.config/job-stats/stats.json

Result:

03/2023 M1 Station Core alpha

Develop a functional but rudimentary binary for early adopters.

Features

  • Bundled Modules
    • Saturn L2 Node
  • CLI
    • $ npm install -g @filecoin-station/core
    • $ station
  • Configuration
    • Require environment variable FIL_WALLET_ADDRESS
  • Storage
    • Pick folder on disk $STATION_ROOT = ~/.station/
    • (Re-)create folder structure on launch
    • Store event streams (module logs, activity log) in individual log files
    • Truncate log files to 10MB each max
  • Process management
    • Launch module process
    • Restart module process
    • Pass module data folder
      ROOT_DIR=$STATION_ROOT/modules/${MODULE_NAME}
    • Pass wallet address
      FIL_WALLET_ADDRESS=f1...
    • Store module stdout
      • File: $STATION_ROOT/logs/modules/${MODULE_NAME}.log
      • Example: 2023-02-16T22:59:47.385+0100 INFO: Saturn Node is online and connected to 9 peers
    • Store module stderr
      • File: $STATION_ROOT/logs/modules/${MODULE_NAME}.err.log
      • Example: 2023-02-16T22:59:47.385+0100 Dang!
  • Metrics
    • Collect module metrics (totalJobsCompleted)
    • Write metrics updates to disk
      • File: $STATION_ROOT/logs/metrics.log
      • Example: 2023-02-16T22:59:47.385+0100 {"totalJobsCompleted":123}

Example usage

# Installation
$ npm install -g @filecoin-station/core
$ station
...

# Configuration
$ export STATION_ROOT=~/.station/ # (default)
$ export STATION_FIL_WALLET_ADDRESS=f1...

# Get latest metrics
$ tail -n1 $STATION_ROOT/logs/metrics.log
2023-02-16T22:59:47.385+0100 {"totalJobsCompleted":123}

# List module logs
$ tail -f $STATION_ROOT/logs/modules/saturn-l2-node{,.err}.log
==> $STATION_ROOT/logs/modules/saturn-l2-node.log <==
2023-02-16T22:59:47.385+0100 INFO: Saturn Node is online and connected to 9 peers
2023-02-16T22:59:47.385+0100 ERROR: Saturn Node is not able to connect to the network

==> $STATION_ROOT/logs/modules/saturn-l2-node.err.log <==
2023-02-16T22:59:47.385+0100 Dang!
...

03/2023 M2 Station Core

Productionize the Station Core CLI in order to reach a larger audience.

Features

  • CLI
    • station --help
    • station activity
    • station logs [<module>]
    • station metrics [<module>]
  • Activity log
    • Aggregate high-level logs
      • File: $STATION_ROOT/logs/activity.log
      • Example: 2023-02-16T22:59:47.385+0100 Saturn Node is online and connected to 9 peers
      • File: $STATION_ROOT/logs/activity.err.log
      • Example: 2023-02-16T22:59:47.385+0100 Saturn Node is not able to connect to the network
  • Documentation
    • README
    • Installation
    • Getting started
    • Contributing

Example usage

# Installation
$ npm install -g @filecoin-station/core
$ station
...

# Configuration
$ export STATION_ROOT=~/.station/ # (default)
$ export STATION_FIL_WALLET_ADDRESS=f1...

# Get latest metrics
$ station metrics
totalJobsCompleted=123

# List module logs
$ station logs saturn-l2-node
2023-02-16T22:59:47.385+0100 INFO: Saturn Node is online and connected to 9 peers
...

# List activity
$ station activity
2023-02-16T22:59:47.385+0100 Saturn Node is online and connected to 9 peers
2023-02-16T22:59:47.385+0100 Saturn Node is online and connected to 7 peers
...

(04/2023) M3 HTTP interface for Station Core

In preparation for integration with Station Desktop, add an HTTP interface in addition to the Station Core CLI. This interface can also be convenient without Station Desktop.

Features

  • HTTP interface
    Aside being a potentially nicer interface than direct access to log files, Station Desktop can connect to Station Core through this over the network. The file interface is limited to same machine access. We can then turn Station Desktop into a light client for this HTTP interface. By default, Station Desktop will bundle and connect to its own instance of Station Core.
    • GET /logs/modules/:name
    • GET /logs/modules/:name?err
    • GET /metrics
    • GET /wallet/address
    • GET /wallet/balance
    • GET /wallet/transactions
    • POST /wallet/transfer/:destination
    • Authentication
      • SSH tunnel?
      • JWT?
    • Default port: 3266

Example usage

# Installation
$ npm install -g @filecoin-station/core
$ station
...

# Configuration
$ export STATION_ROOT=~/.station/ # (default)
$ export STATION_FIL_WALLET_ADDRESS=f1...

# Get latest metrics
$ curl http://localhost:3266/metrics
{"totalJobsCompleted":123}

# List module logs
$ curl http://localhost:3266/logs/modules/saturn-l2-node{,?err}
2023-02-16T22:59:47.385+0100 INFO: Saturn Node is online and connected to 9 peers
2023-02-16T22:59:47.385+0100 ERROR: Saturn Node is not able to connect to the network
...

# List activity
$ curl http://localhost:3266/logs/activity{,?err}
2023-02-16T22:59:47.385+0100 Saturn Node is online and connected to 9 peers
2023-02-16T22:59:47.385+0100 Saturn Node is online and connected to 7 peers
...

(4/2023) M4 Integrate Station Core into Station Desktop

Greatly simplify Station Desktop and the product ecosystem in general by letting Station Desktop leverage Station Core

Tasks

  • Bundle Station Core with Station Desktop
  • Consume Station Core via HTTP
  • Remove obsolete Station logic from Station Desktop

Future milestones

M5 Station Desktop connects to Station Core over the network

Allow use of Station Desktop as a remote management interface for Station Core.

Future features

  • Docker
    • Deploy Station through docker (instead of Nodejs)
    • Mirror Saturn’s Docker + Watchtower setup
  • Wallet
    • ❓ What is the safest architecture? Who owns the private key, are we able to offer safe remote access to a wallet? Or should Station Desktop (the client) own the wallet?
    • Create/read/store seed phrase
    • Get wallet address from API
    • Pass to module via ENV var
    • Periodically fetch and print new transactions
      • File: $STATION_ROOT/logs/wallet/transactions.log
      • Example: 2023-02-16T22:59:47.385+0100 {"from":"...","amount":"..."}
    • Periodically fetch and print updated balance
      • File: $STATION_ROOT/logs/wallet/balance.log
      • Example: 2023-02-16T22:59:47.385+0100 100
    • Provide command for transferring funds
      $ station transfer $DESTINATION_ADDRESS
    • Authentication
      • MetaMask?
    • CLI
      • filstation wallet balance
      • filstation wallet transactions
      • filstation wallet transfer <destination>
  • Auto-start
  • Auto-update
    For now, operators are required to update Station themselves. This is the standard mode of operation in Linux systems.
    • Create helper binary
    • Periodically check npm version
    • Update using npm install
    • Launch filecoin-station
    • Restart on failure

Name

  • Desktop
    Keep “Station” name for desktop version, or call it “Station Desktop”. The name shouldn’t be technical, since it’s an accessible desktop application
    • Station Desktop ✔️
    • Station Viewer
      Too technical ❓
    • Station Panel
      Too technical ❓
    • Station
      The Desktop app is just a UI, the core product is the headless version. Therefore, the Desktop app shouldn’t have a name as if it were the core product ❌
  • Headless
    Test: “People are running … all over the world”
    • Station Node
      ”      People are running Station Nodes all over the world” ✔️
      ”Node” is an overused product term
    • Station Core
      ”People are running Station Cores all over the world” ✔️
      Eventually migrate to just “Station”
    • Station

      “People are running Stations all over the world” ❓

    • Station CLI
      ”People are running Station CLIs all over the world” ❌
    • Station Daemon
      ”People are running Station Daemons all over the world” ❌
    • Station Server
      ”People are running Station Servers all over the world” ❌
      Station is a P2P product, therefore there shouldn’t be a server (or client)
    • Headless Station
      ”People are running Headless Stations all over the world” ❌
      Too technical

Experiment: Electron in virtual frame buffer

Setup

sudo apt install xvfb libfuse2 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
  libgtk2.0-dev libgtk-3-dev libasound2-dev libsecret-1-dev
curl -OL https://github.com/filecoin-station/filecoin-station/releases/download/v0.13.3/filecoin-station-linux-x86_64.AppImage
chmod +x filecoin-station-linux-x86_64.AppImage
xvfb-run ./filecoin-station-linux-x86_64.AppImage

Output

ubuntu@ubuntu-s-1vcpu-512mb-10gb-fra1-01:~$ xvfb-run ./filecoin-station-linux-x86_64.AppImage 
Log file: /home/ubuntu/.config/Filecoin Station/logs/main.log
09:41:39.937 (config) › Loading Station configuration from /home/ubuntu/.config/Filecoin Station/config.json
09:41:41.565 (main)    › Filecoin Station build version: 0.13.3 linux-x64
09:41:41.567 (main)    › Machine spec: Linux version 5.19.0-23-generic
(node:2337) DeprecationWarning: findLogPath() is deprecated and will be removed in v5.
(Use `filecoin-station --trace-deprecation ...` to show where the warning was created)
[2337:0222/094143.150497:ERROR:bus.cc(399)] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2337:0222/094143.177046:ERROR:bus.cc(399)] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2337:0222/094144.436499:ERROR:bus.cc(399)] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2369:0222/094144.686462:ERROR:viz_main_impl.cc(186)] Exiting GPU process due to errors during initialization
[2337:0222/094144.936974:ERROR:bus.cc(399)] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
09:41:45.952 (updater) › Checking for update
09:41:46.764 (main)    › Error: Unknown or unsupported transport “disabled” for address “disabled:”

Challenges

  • I don’t know where it’s failing exactly
  • I don’t yet have a linux dev environment, in which I can build and run the electron app using xvfb
  • That’s a huge apt install string. Other machines will need different instructions → we need to introduce Docker (heavy overhead)

Result

❌ Shipping the Electron app into headless environments comes with too much complexity. Develop a Node.js solution instead.