Oxen Debian/Ubuntu builds (by Jason)
====================================

This repository contains debian/ubuntu builds of:

- the core oxen tools (oxend, cli/rpc wallets, blockchain tools)
- Oxen GUI wallet [oxen-electron-wallet]
- Session [Package name: session-desktop]
- oxen-storage-server for running a service node
- oxen-service-node metapackage for a simple service node setup
- lokinet packages for getting on lokinet or for running a service node

build for recent Debian and Ubuntu releases.

Requirements
------------
One of:
- Debian 11 ("bullseye")
- Debian 12 ("bookworm")
- Debian testing ("trixie")
- Debian unstable ("sid")
- Ubuntu 20.04 ("focal")
- Ubuntu 22.04 ("jammy")
- Ubuntu 24.04 ("noble")

*** - following Ubuntu's own support schedule, non-LTS Ubuntu releases will be supported for 9
      months (i.e. giving a 3 month upgrade window to the next release).

Some Ubuntu-derived distributions (Mint, Elementary OS) will likely work as well using the Ubuntu
packages of the appropriate version, but are less tested.


TL;DR
=====

Set up this repository on your system by running these three commands:

    sudo curl -so /etc/apt/trusted.gpg.d/oxen.gpg https://deb.oxen.io/pub.gpg

    echo "deb https://deb.oxen.io $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/oxen.list

    sudo apt update

(You only need to do this once).

Once you have lokinet access, you can also fetch packages over lokinet by changing `https://deb.oxen.io` to
`http://deb.loki` (note "http" instead of "https").

Once set up you can install Session or the GUI wallet using one of:

    sudo apt install session-desktop
    sudo apt install oxen-electron-wallet

Or you can install a service node using:

    sudo apt install oxen-service-node

The services will run via systemd as `oxen-node.service`, `oxen-storage-server.service`, and `lokinet-router.service`.

If you want to run a lokinet *client* you can install it with:

    sudo apt install lokinet

(you may need a little extra configuration to resolve .loki addresses -- see lokinet documentation)


TL;DR (testnet)
===============

Sometimes pre-release debs are available as well by changing `deb https://deb.oxen.io $(lsb_release -sc) main'
to `deb https://deb.oxen.io/beta $(lsb_release -sc) main' (adding the "/beta").

We do not recommend debs from this alternate repository for mainnet nodes -- they are provided for testnet builds of
upcoming features.  (When we are confident the release is ready we will put the debs on the main repository, above).


Long is good, will read:
========================

Initial repository setup
------------------------

You only need to do this step the first time you want to set up the repository; once you've done it
once, the repository will automatically update whenever you fetch new system updates.

To add the apt repository run the following command, replacing DISTRO in the second line with the
appropriate value (see below).

    sudo curl -so /etc/apt/trusted.gpg.d/oxen.gpg https://deb.oxen.io/pub.gpg
    echo "deb https://deb.oxen.io DISTRO main" | sudo tee /etc/apt/sources.list.d/oxen.list

The first command installs my public key used to sign the binaries.  The second command tells `apt`
where to find the packages, and needs you to replace DISTRO with one of:

    - sid      (Debian unstable)
    - trixie   (Debian testing, eventually Debian 13)
    - bookworm (Debian 12)
    - bullseye (Debian 11)
    - noble    (Ubuntu 24.04)
    - jammy    (Ubuntu 22.04)
    - focal    (Ubuntu 20.04)

(You can usually get this codename by running `lsb_release -sc`, as in the TL;DR version above).

If you are wondering which release to try, generally stick to the most recent Debian release, or the
most recent LTS Ubuntu release (which are the even-number.04, e.g. 20.04, 22.04); the other Ubuntu
releases are short-lived support (e.g. 9 months) both by Ubuntu and ourselves.

If you are using a Debian- or Ubuntu-derived distribution then you may have to relace DISTRO with
the compatible version from the list above.  (And if this works, let us know so that we can add an
alias.  Currently we have aliases for Linux Mint and Elementary OS releases that point to the base
Ubuntu version so those should work already).

Then resync your package repositories with:

    sudo apt update

Now you can install one or more of the following packages as desired:

    - oxen-service-node     -- metapackage that does everything you need for a running service node
    - oxend                 -- the oxen daemon (automatically pulled in by oxen-service-node)
    - oxen-storage-server   -- the oxen storage server, required for a service node (automatically pulled in by oxen-service-node)
    - oxen-wallet-cli       -- the command-line wallet
    - oxen-wallet-rpc       -- the rpc wallet (for script-based wallet interaction such as a pool would need)
    - oxen-blockchain-tools -- the various oxen-blockchain-* commands for advanced blockchain management.
    - lokinet-router        -- the lokinet binaries + configuration for running lokinet as a router
    - lokinet               -- the lokinet binaries + configuration for running a client or snapp
    - oxen-electron-wallet  -- the OXEN GUI wallet
    - session-desktop       -- the Session messenger

There are also a few lib* library packages containing the shared library code, but these will be
installed automatically as needed.

For example, to install and start up a brand new service node:

    sudo apt install oxen-service-node

To install a non-service-node oxend and the cli wallet:

    sudo apt install oxend oxen-wallet-cli

Once installed the binaries will be in your path, so you can simply run `oxen-wallet-cli` as an
ordinary user to use the command-line wallet.


Non-service node Loki operation
-------------------------------

Installing the oxend package sets up a `oxen-node` systemd service that runs an ordinary oxen node,
but not a service node.  This node can be used, for example, for wallet synchronization.  If you
don't want the node to run you can stop it after installation using:

    sudo systemctl stop oxen-node

and if you want to disable it entirely (so that it doesn't start up automatically at boot) you can use:

    sudo systemctl disable --now oxen-node

If you later want to re-enable it you would use

    sudo systemctl enable --now oxen-node

(remove the `--now` if you want to reenable it but not actually try starting it).

If you want to change some of the oxend settings you can add the settings to /etc/oxen/oxen.conf.
Note that you can add any of oxend's command-line arguments as settings in this file rather than
needing to change the service file.  For example, if you wanted to run oxend as
`oxend --p2p-bind-ip 1.2.3.4 --p2p-bind-port=22222 --restricted-rpc` then you would add:

    p2p-bind-ip=1.2.3.4
    p2p-bind-port=22222
    restricted-rpc=1

into /etc/oxen/oxen.conf and then restart oxend using

    sudo systemctl restart oxen-node

For advanced users, oxend creates a `_loki` user and stores all the files (blockchain, service node
key, etc.) owned by this user in /var/lib/oxen.


Loki service node operation
---------------------------

Running a service node requires multiple packages (oxend and oxen-storage-server) with synchronized
configuration between them.  There are two ways to approach this:

- Manually.  Install both `oxend` and `oxen-storage-server` packages, then edit the configuration in
  /etc/oxen/oxen.conf and /etc/oxen/storage.conf (see docs.oxen.io for more detail).  Restart both after
  configuration updates using:
  
      systemctl restart oxen-node oxen-storage-server

- Automatic.  Install the `oxen-service-node` package.  This will detect your public IP (or allow
  you to enter it yourself) and automatically update the oxen.conf configuration file with the
  necessary additional settings to run a service node.


Running a testnet node
----------------------

The oxend package also installs a second systemd service, oxen-testnet-node, for easily running a
testnet node (either at the same time or instead of the mainnet node).  To enable and start this,
simply run:

    sudo systemctl enable --now oxen-testnet-node

which will start it and configure systemd to automatically start it when the system boots.

The `oxen-service-node` package also updates the testnet.conf file to run as a (testnet) service
node; in order to actually run it you need to activate and start both the oxen-testnet-node.service
(as above) and also the oxen-testnet-storage-server.service:

    sudo systemctl enable --now oxen-testnet-node
    sudo systemctl enable --now oxen-testnet-storage-server


Interacting with the running oxend
----------------------------------

If you run the oxend binary with a command, it forwards this command to the running oxend.  So, for
example, to get the current oxend status you can run (note that sudo is not required!):

    oxend status
    oxend print_sn_status

and to prepare a service node registration:

    oxend prepare_registration

For a full list of supported commands run:

    oxend help

For interacting with a running testnet node, add `--testnet` into the command, such as:

    oxend --testnet status
    oxend --testnet print_sn_status
    oxend --testnet prepare_registration


Upgrading
---------

When a new release is available upgrading it as simple as
Sync with the repository:

    sudo apt update

and the install any updates using:

    sudo apt upgrade

Note that this will install both updated oxend packages *and* any available system updates (this is
generally a good thing!).  During the upgrade, oxend (both mainnet and testnet) will be restarted if
they are currently running to switch to the updated oxend.

If for some reason you want to install *only* updated oxen package upgrades but not other system
packages then instead of the `sudo apt upgrade` you can use

    sudo apt install oxen-storage-server oxend oxen-wallet-cli

to update just those packages (plus any required dependencies that need updating).


Reporting issues
----------------

Contact me via @jagerman42 (Telegram) or jagerman (on Session).