# 🐲 dragonion-server
Websocket chat server on-top of onion network for 
[dragonion](https://github.com/kotikotprojects/dragonion)

## 📜 Table of Contents
* [🐲 dragonion-server](#-dragonion-server)
  * [📜 Table of Contents](#-table-of-contents)
  * [🛣️ Usage plan](#%EF%B8%8F-usage-plan)
  * [🔖️ About](#%EF%B8%8F-about)
  * [💻 Usage](#-usage)
  * [⚙️ Configuration guide](#%EF%B8%8F-configuration-guide)
  * [📃 Credits](#-credits)

## 🛣️ Usage plan
1. Check [[Table of Contents](#-table-of-contents)] (optionally)
2. Read [[About](#%EF%B8%8F-about)] (optionally)
3. Read [[Usage guide](#-usage)]
4. Go to [[Configuration guide](#%EF%B8%8F-configuration-guide)], choose your platform,
navigate to opted installation method (they are arranged from most to least 
recommended)
5. Install pre-requirements, install app, run it, 
checking [[usage guide](#-usage)] if needed

## 🔖️ About
A configured and running dragonion-server is required for dragonion chat to work. 
Built on-top of dragonion-core, it implements work with the protocol and 
websockets server, that broadcasts and handles messages.

## 💻 Usage
To use dragonion-server, you need to install it first. To do this, you can visit
[[Configuration guide](#%EF%B8%8F-configuration-guide)].

You can talk with this repo using collectivai chat. 
[[Visit this page](https://chat.collectivai.com/dragonionx/dragonion-server)] and 
discuss your questions. AI will respond with up-to-date information using the data 
of this repository.

dragonion-server is controlled from cli. When you run it in some location on your
disk, `data` folder with tor and `data.storage` config file are created. You should
keep them safe to avoid data and key leaks. Using `data.storage` file anyone can
start server on your onion service id.

#### Guide sections:
- [Getting help](#getting-help)
- [Running a service](#running-a-service)
- [Updating a service](#updating-a-service)
- [Removing a service](#removing-a-service)

#### Getting help
To check all available commands, you can run
```commandline
dragonion-server --help
```
To get help for specific command, you should run
```commandline
dragonion-server command-name --help
```
where `command-name` is name of existing command, for example
```commandline
dragonion-server service-run --help
```

#### Running a service
To use dragonion chat, you need to run onion service with dragonion-server. 
In this situation, service is an onion service, an anonymous network service 
that is exposed over the Tor network. dragonion-server runs service, that
points to local endpoint with running websocket server.

To run a service, you should run
```commandline
dragonion-server service-run --name SERVICE_NAME
```

Available command options:

- `-n` or `--name` is required and used to specify service name. If service with
this name exists in config, it will run with saved parameters (like port), and 
if not - new will be created
- `-p` or `--port` is used to specify port, where local server will be started.
It is saved to config file. Remember, that it isn't only port, that server will
take. You cannot control tor ports using this option. If not specified, random 
available will be picked.
- `-wt` (`--without-tor`) and `-ot` (`--only-tor`) are used mostly for development,
to separate the processes of the proxy and the server itself

After running this command, `tor` will start, and you will see that service is now
available on onion host. To connect to service, you should share two colorful
strings (orange and purple), that are service id and auth string, to your users.
Also, sharing `SERVICE_NAME.auth` file, that is created in working dir can be more
convenient for some users as connect option, so you should share it also.

[[Back to sections](#guide-sections)]

#### Updating a service
You may have a situation where you need to update or write a service without 
actually starting it. In such cases, you can use the command provided below. 
It allows you to generate an id-key pair for a new name and overwrite the port 
for an existing name.

To run update a service, you should run
```commandline
dragonion-server service-write --name SERVICE_NAME --port PORT
```

Available command options:

- `-n` or `--name` is required and used to specify service name to write.
- `-p` or `--port` is required here and will rewrite port in settings.

[[Back to sections](#guide-sections)]

#### Removing a service
In some situations, you may need to remove the service. In this case, you will no 
longer be able to run the server on the same id due to the nature of the tor 
network, so be careful with this. Also, do not forget that the loss of the 
`.storage` (config file) means no access to the service ID-key pair, which also 
means the loss of the ability to start the server without the possibility of 
recovery.

To run update a service, you should run
```commandline
dragonion-server service-remove --name SERVICE_NAME
```

Available command options:

- `-n` or `--name` is required and used to specify service name to remove.

[[Back to sections](#guide-sections)]

Remember, if you still have questions about the operation of the server, you can 
[[discuss them with AI](https://chat.collectivai.com/dragonionx/dragonion-server)] 
or create an issue.

## ⚙️ Configuration guide
- [Windows](#windows)
- [Linux](#linux)
- [MacOS](#macos)

### Windows
#### Pre-requirements:
- [[Python3](https://www.python.org/downloads/)] (with pip)
- [[Git](https://git-scm.com/download/win)]
- [[Windows terminal](https://github.com/microsoft/terminal)] is recommended, 
[[install it from Microsoft Store](https://aka.ms/terminal)]

#### Install options:
- [Use pipx](#use-pipx)
- [Clone repo and use venv](#clone-repo-and-use-venv)

##### Use pipx
pipx is a tool to help you install and run end-user applications written in Python.
It creates isolated environments for each application to install it.

Fresh installation:
```
pip install pipx
pipx ensurepath
pipx install git+https://github.com/kotikotprojects/dragonion-server
```
Launch options:
- After fresh install, re-run your shell, than run `dragonion-server` 
(it is in your PATH because of pipx)

Updating:

```commandline
pipx upgrade dragonion-server
```

[[Back to Usage guide](#-usage)]

##### Clone repo and use venv
Fresh installation:
```commandline
git clone https://github.com/kotikotprojects/dragonion-server
cd dragonion-server
python -m venv venv
venv\Scripts\activate
pip install .
```
Launch options:
- After fresh install, run `dragonion-server` in environment 
(or `python -m dragonion-server`)
- `cd` to app folder, run `venv\Scripts\activate`, than `dragonion-server` in 
environment (`python -m dragonion-server`)
- Run `dragonion-server.exe` from `venv\Scripts`. You can also copy it anywhere you
want, but remember that data and config files are saved near executable file

Updating:

`cd` to app directory, than 
```commandline
git pull
```
If there are new changes, run
```commandline
venv\Scripts\activate
pip install .
```

[[Back to Usage guide](#-usage)]

### Linux
#### Pre-requirements (install them via your package manager):
For x64/x86 systems:
- `python3` `python3-pip` `python3-venv`
- `git`

For arm (arm64, aarch64) systems:
- All from above
- `tor`

#### Install options:
- [Use pipx](#use-pipx-1)
- [Clone repo and use venv](#clone-repo-and-use-venv-1)

##### Use pipx
pipx is a tool to help you install and run end-user applications written in Python.
It creates isolated environments for each application to install it.

Install pipx:
```commandline
apt install pipx
```
or
```commandline
pip install pipx
```

Fresh installation:
```
pipx ensurepath
pipx install git+https://github.com/kotikotprojects/dragonion-server
```
You may use `python3 -m pipx` for this

Launch options:
- After fresh installation relaunch your shell (if pipx was previously installed,
you can skip this), than run `dragonion-server` (it is in your env because of pipx)

Updating:

```commandline
pipx upgrade dragonion-server
```

[[Back to Usage guide](#-usage)]

##### Clone repo and use venv
Fresh installation:
```commandline
git clone https://github.com/kotikotprojects/dragonion-server
cd dragonion-server
python3 -m venv venv
. venv/bin/activate
pip install .
```
Launch options:
- After fresh install, run `dragonion-server` in environment 
(or `python3 -m dragonion-server`)
- `cd` to app folder, run `. venv/bin/activate`, than `dragonion-server` in 
environment (`python3 -m dragonion-server`)
- Run `dragonion-server` from `venv\bin`. You can also copy it anywhere you
want, but remember that data and config files are saved near executable file

Updating:

`cd` to app directory, than 
```commandline
git pull
```
If there are new changes, run
```
. venv/bin/activate
pip install .
```

[[Back to Usage guide](#-usage)]


### MacOS
#### Pre-requirements (install them via your package manager):
- `python3` `python3-pip` `python3-venv`
- `git`

#### Install options:
- [Use pipx](#use-pipx-2)
- [Clone repo and use venv](#clone-repo-and-use-venv-2)

##### Use pipx
pipx is a tool to help you install and run end-user applications written in Python.
It creates isolated environments for each application to install it.

Install pipx:
```commandline
brew install pipx
```
or
```commandline
pip3 install pipx
```

Fresh installation:
```
pipx ensurepath
pipx install git+https://github.com/kotikotprojects/dragonion-server
```
You may use `python3 -m pipx` for this

Launch options:
- After fresh installation relaunch your shell (if pipx was previously installed,
you can skip this), than run `dragonion-server` (it is in your env because of pipx)

Updating:

```commandline
pipx upgrade dragonion-server
```

[[Back to Usage guide](#-usage)]

##### Clone repo and use venv
Fresh installation:
```commandline
git clone https://github.com/kotikotprojects/dragonion-server
cd dragonion-server
python3 -m venv venv
. venv/bin/activate
pip install .
```
Launch options:
- After fresh install, run `dragonion-server` in environment 
(or `python3 -m dragonion-server`)
- `cd` to app folder, run `. venv/bin/activate`, than `dragonion-server` in 
environment (`python3 -m dragonion-server`)
- Run `dragonion-server` from `venv\bin`. You can also copy it anywhere you
want, but remember that data and config files are saved near executable file

Updating:

`cd` to app directory, than 
```commandline
git pull
```
If there are new changes, run
```
. venv/bin/activate
pip install .
```

[[Back to Usage guide](#-usage)]


## 📃 Credits
- [[OnionShare project](https://github.com/onionshare)] - code inspiration for 
integrating application with tor