This is an A to Z guide that will help you get `wetty` up and running on Debian
This is an A to Z guide that will help you get WeTTY up and running on a Debian based system. It covers the key configuration areas by using copy and paste commands. This will help you install this application and get it securely up and running with minimal system interference and reversible changes. It should also provide enough information to allow you to understand and extend that configuration for your personal requirements.
Stable. It covers the key configuration areas by using copy and paste commands
to help you install this application and get it securely up and running. It
should also provide enough information to allow you to understand and extend
that configuration for your personal requirements.
### Required dependencies
**Note:** Some of these configurations are optional, such as self signed SSL and public key authentication. The purpose of the guide is to show you how to correctly understand, configure, install and use these options should you wish to use them but they are not required to use WeTTY in general.
You will need the package `build-essential` to be installed. We need this
## Required dependencies
specifically for `node-gyp` to build packages when using `npm` or `yarn` to
install packages.
`Node` - WeTTY requires node v14 or greater. We will install this locally for a non root user later in the guide.
`python` - This should be installed by default but we will include it in our `apt-get` command to be safe.
`build-essential` - We need this specifically for `node-gyp` to build packages when using `npm` or `yarn` to install packages.
As the `root` user run these commands:
As the `root` user run these commands:
```bash
```bash
apt update
apt update
apt install -y build-essential
apt install -y build-essential python
```
```
If you do not have root access and just want to check the dependency is
If you have no root access and just want to check the dependencies are installed you can use these commands:
installed you can use this command:
```bash
```bash
dpkg -s python | grep Status:
dpkg -s build-essential | grep Status:
dpkg -s build-essential | grep Status:
```
```
If the program is installed you will see this result:
If the package is installed you will see this result:
```bash
```bash
Status: install ok installed
Status: install ok installed
```
```
### Create a local user account
## Create a local user account
For this guide, unless specifically stated, you should not use a `root` account
For this guide, unless specifically stated, you should not use a `root` account to install and run WeTTY. Please use an existing local account or create one now.
to install and run `wetty`. Please use an existing local account or create one
now.
**Note:** Whichever user runs `wetty` should be the same user you wish to
**Note:** Whichever user runs WeTTY should be the same user you wish to authenticate with via `ssh` to keep this guide simple.
authenticate with via `ssh` to keep this simple.
If you need to create a local user account you can run this command:
If you need to create a local user account you can run this command:
**Important note:** replace `username` with a user name of your choosing and
**Important note:** replace `username` with a user name of your choosing and create a password when prompted
create a password when prompted
```bash
```bash
adduser --gecos "" username
adduser --gecos "" username
```
```
Switch to your local user now and open an `ssh` session to continue with this
Switch to your local user now and open an `ssh` session to continue with this guide.
guide.
### Install node locally
## Install node locally
To install and manage `node` as a local user we are going to use
To install and manage `node` as a local user we are going to use [Node Version Manager](https://github.com/nvm-sh/nvm). This is an established solution for installing and managing multiple versions of node without needing `root` access. This will allow you to install and use multiple versions of `node` at the same time.
[Node Version Manager](https://github.com/nvm-sh/nvm) as an established solution
to installing and managing multiple versions of node without needing `root`
This command will download and install `nvm` and reload our shell.
access. We are going to install the `lts` or long term support release of `node`
This command will install the latest version of the v14 branch, which is the minimum required version for WeTTY.
```bash
nvm install 14
```
```
You can now call `node` to check it works using this command.
You can now call `node` to check it works using this command.
@ -75,29 +73,20 @@ node -v
Your result should look something like this.
Your result should look something like this.
```bash
```bash
v12.16.2
v14.14.0
```
```
**Note:** There is consideration with this method. `node` is only in the local
**Note:** There is an important consideration with the `nvm` method. `node` is only in the local user's path through sourcing of the `~/.nvm/nvm.sh` which is done when the user logs in and the shell sources the user's `.bashrc` file. So for some applications who are not aware of this local shell environment `node` will not be usable unless we provide a full path and `nvm` commands will also be unavailable. The way we over come this issue for the needs of this guide is by using this command substitution to provide the full path, where applicable:
user's path through sourcing of the `~/.nvm/nvm.sh` via the users `.bashrc`
file. Unless this is done `node` will not be usable unless directly linked to
and `nvm` commands will be unavailable.
The way we overcome this issue for the needs of this guide is by using this
command where applicable:
```bash
```bash
source ~/.nvm/nvm.sh && nvm which 14
$(source ~/.nvm/nvm.sh && nvm which 14)
```
```
**Why?** This command will always provide us with the path to the most current
**Why?** This command will always provide us with the path to the most current version of `node 14` installed via `nvm` regardless of other versions of `node` installed with `nvm`.
version of `node 12` installed via `nvm` regardless of other versions of `node`
installed.
### Generate openssl certificates.
## Generate OpenSSL certificates
**Why?** So that later we can configure `wetty` to work with `https` and make
**Why?** So that later we can configure WeTTY to work with `https` and make sure we interact with WeTTY over a secure connection at all times.
sure we interact with `wetty` over a secure connection at all times.
Make the required directory using this command:
Make the required directory using this command:
@ -105,13 +94,12 @@ Make the required directory using this command:
mkdir -p ~/.ssl
mkdir -p ~/.ssl
```
```
Generate the self-signed `openssl` certificates we will use to encrypt our web
Generate the self signed `openssl` certificates we will use to encrypt our web traffic when using WeTTY using this command:
traffic when using `wetty` using this command:
**Note:** we are using`ecdsa` using the `secp521r1` curve.
**Note:** we are using`ecdsa` using the `secp384r1` curve. Tested to be compatible with Chrome and Firefox browsers.
**Important Note:** You must add the public key to your `authorized_keys` file
**Important Note:** You must add the public key to your `authorized_keys` file in order to be able to log in using your `ssh` key file when accessing WeTTY via a web browser.
in order to be able to log in using your `ssh` key file when accessing `wetty`
via a web browser.
Copy the key to our `~/.ssh/authorized_keys` file, using this command:
Copy the key to our `~/.ssh/authorized_keys` file, using this command:
**Optional:** A housekeeping command. If you need to remove all entries of the
**Optional:** A housekeeping command. If you need to remove all entries of the WeTTY public key with the comment `wetty-keyfile` from the `~/.ssh/authorized_keys` file use this command. Otherwise ignore this.
`wetty` public key with the comment `wetty-keyfile` from the
`~/.ssh/authorized_keys` file use this command. Otherwise ignore this.
```bash
```bash
sed -r '/^ssh-ed25519(.*)wetty-keyfile$/d' -i ~/.ssh/authorized_keys
sed -r '/^ssh-ed25519(.*)wetty-keyfile$/d' -i ~/.ssh/authorized_keys
```
```
### Install wetty
## Install WeTTY
**Note:** we are using `-g` for `npm` or `global` for `yarn` along with
**Note:** we are using `-g` for `npm` or `global` for `yarn` along with `--prefix ~/` so that the application's symbolic link is installed to our `~/bin` directory and available in our local user's `PATH`.
`--prefix ~/` so that the application symbolic link is installed to our `~/bin`
directory and available in our local user's `PATH`.
As your local user run these commands to install `wetty` and `forever`. We will
As your local user run these commands:
need `forever` later to run wetty in the background.
First, we need to make sure the local user's `~/bin` folder exists and is in the
To make sure the local user's `~/bin` directory exists and is in the `PATH` please run the following command.
`PATH` for the following commands to work.
```bash
```bash
mkdir -p ~/bin && source ~/.profile
mkdir -p ~/bin && source ~/.profile
```
```
Please use either the `npm` or `yarn` method and not both. The `yarn` method is
Now use `npm` to install the `yarn` packet manager.
recommended but I provide both as you may have a personal preference. The
outcome is effectively the same.
`npm ` - optional - use `npm` to install wetty
```bash
```bash
npm install -g wetty forever --prefix ~/
npm install -g yarn --prefix ~/
```
```
`yarn` - recommended - use `yarn` to install wetty
Then use `yarn` to install `wetty`.
```bash
```bash
npm install -g yarn --prefix ~/
yarn global add wetty --prefix ~/
yarn global add wetty forever --prefix ~/
```
```
Once successfully installed the application should be available in your local
Once successfully installed the application should be available in your local user's `PATH`. To test the installation was successful please use this command:
user's `PATH`. To test the installation was successful please use this command:
```bash
```bash
wetty -h
wetty -h
```
```
### Accessing the web interface.
## Accessing the web interface via our external IP
This needs to be done here because it is not easy to do in the next steps if
If you are using your external IP and not a domain to access WeTTY this step needs to be done here because it is not easy to do in the next steps if WeTTY is running in the terminal.
`wetty` is running in the terminal.
This command will generate the correct URL you need to visit after using the
This command will generate the correct URL you need to visit after using the start up commands in the following section.
start up commands in the following section.
```bash
```bash
echo https://$(curl -s4 icanhazip.com):3000
echo https://$(curl -s4 icanhazip.com):3000
```
```
_Please make make a note of this URL now._
*Please make make a note of this URL now.*
### Running wetty
## Running WeTTY
Now we have all the ground work done we can focus on our `wetty` server
Now we have all the ground work done we can focus on our WeTTY server configuration settings.
configuration settings.
For example, the below command would provide a `https` instance with automatic
For example, the below command would provide a `https` instance with automatic `ssh` authorisation using our `wetty` private key on port `3000` accessible at `https://IP:3000` .
`ssh` authorisation using our `wetty` private key on port `3000` accessible at
`https://IP:3000` . Refer to the previous URL generation command.
**Important note:** This command will run in your current terminal session and
**Important note:** This command will run in your current terminal session and not in the background. The key combination of `CTRL` + `c` will exit the application.
To stop `wetty` from running you can use this command
```bash
```bash
forever stop ~/bin/wetty
--host 0.0.0.0 -p 3000 --title wetty --base /
```
```
#### Optional - config file.
`--host 0.0.0.0` - defines the interface we want to bind to. Using `0.0.0.0` means that we bind to all available interfaces so using this setting just works. When we use nginx we can change this to `--host 127.0.0.1` in order to prevent generic port access to the application and force traffic through our nginx reverse proxy URL.
Create a directory to store our configuration data using this command:
`-p 3000` - defines the local listening port. You will use this port to connect via the remotely accessible web server or when configuring a reverse proxy through nginx.
```bash
`--title wetty` - an optional setting to set the window title for this `wetty` session.
mkdir -p ~/.config/wetty
```
Now populate our `config` file with some settings. This example is the same
`--base /` - changes the default base URL setting from `/wetty/` to define the remote URL. We use `--base /` to make `wetty` accessible on the URL format `https://IP:3000` instead of `https://IP:3000/wetty` but we would change this back if we use nginx to reverse proxy the application.
Now we can load this file as part of the command we pass to `wetty` with shell
`--ssh-key ~/.ssh/wetty` - we are telling WeTTY to load our `ssh` key file that we generated earlier.
expansion and command substitution.
```bash
`--ssh-host localhost` - optional setting telling WeTTY to connect the host `localhost`
wetty --conf ~/.config/wetty/config.json
```
#### forever using a config file
`--ssh-user $(whomai)` - defines our `ssh` username. In this case via the command substitution of `whoami` which will not require your input of a username.
Now you can use `forever` to run it in the background instead of directly in
`--ssh-port 22` - optional setting to set the `ssh` port we need to connect to.
your terminal
```bash
`--ssh-auth publickey` defines the accepted authentication types. You do not have to use the key file and you can instead require a password but setting this to `--sshauth password`. You can specify both `--sshauth publickey,password`
`--ssh-key ~/.ssh/wetty` - we are telling `wetty` to load our `ssh` key file
Here is the template `config.json` you need to use.
that we generated earlier.
`--ssh-host localhost` - optional setting telling `wetty` to connect the host
**Note:** All option that you do not want to use can be commented out using `//`. For example `// title: 'Terminal', // Page title` will comment out this line and it will be ignored.
`localhost`
`--ssh-user $(whomai)` - defines our `ssh` username. In this case via the
```json
command substitution of `whoami` which will not require your input of a
{
username.
ssh: {
user: 'username', // default user to use when ssh-ing
host: 'localhost', // Server to ssh to
auth: 'publickey,password', // shh authentication, method. Defaults to "password", you can use "publickey,password" instead'
pass: "password", // Password to use when sshing
key: "/home/username/.ssh/wetty", // path to an optional client private key, connection will be password-less and insecure!
port: 22, // Port to ssh to
knownHosts: '/dev/null', // ssh knownHosts file to use
},
server: {
base: '/terminal/', // URL base to serve resources from
`--ssl-cert ~/.ssl/wetty.crt` - tells `wetty` to load our `openssl` generates
There are currently no environment settings for variables not listed above.
certificate file.
### Systemd service settings
## Systemd service settings
We will use a local user `systemd` service file to manage the `wetty` service.
We will use a local user `systemd` service file to manage the `wetty` service.
@ -378,42 +349,74 @@ First, create the required directory, if it does not exist.
mkdir -p ~/.config/systemd/user
mkdir -p ~/.config/systemd/user
```
```
#### Systemd service.
### Systemd service
Here is the example using our pseudo configuration file. All modifications to
Here is an example template of how to use service file with hardcoded values you can set in the `wetty.service` file with all options enabled.
the start up of `wetty` will be done by editing the `~/.config/Wetty/config`
file and then reloading the ` wetty.service`.
Use `nano` to open the file for editing.
Use `nano` to open a file for editing.
```bash
nano ~/.config/systemd/user/wetty.service
```
The copy and paste this code.
**Note:** This is an example service file based on all the options documented and configured so far. You may not want all these option enabled so please remove or modify the `ExecStart` command based on your needs.
Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and exit `nano`.
### Optional - Systemd service with config file
Here is the example using our pseudo configuration file. All modifications to the start up of `wetty` will be done by editing the `~/.config/Wetty/config` file and then reloading the ` wetty.service`.
Use `nano` to open the file for editing.
```bash
nano ~/.config/systemd/user/wetty.service
nano ~/.config/systemd/user/wetty.service
```
```
The copy and paste this code.
The copy and paste this code.
**Note:** This `ExecStart` assumes the location of your `config.json` to be `~/.config/wetty/config.json`. Please make sure you use the correct location for this file.
If you want to use nginx as a revers proxy here is the configuration file you
If you want to use nginx as a reverse proxy here is the configuration file you can use.
can use.
Please modify these specific environment settings:
Please modify these specific environment settings:
**Why?** This will disable generic port access to the application and force
**Why?** This will disable generic port access to the application and force traffic via the nginx reverse proxy.
traffic via the nginx reverse proxy.
```bash
```bash
--host 127.0.0.1
--host 127.0.0.1
```
```
**Why?** This change is so that our application does not attempt to load as the
**Why?** This change is so that our application does not attempt to load as the web root of `/` for nginx.
web root of `/` for nginx.
```bash
```bash
--base /wetty/
--base /wetty/
@ -458,38 +458,38 @@ web root of `/` for nginx.
Now you can use this nginx configuration file.
Now you can use this nginx configuration file.
**Note:** we are using `https` here `https://127.0.0.1:3000/wetty;` because we
**Note:** we are using `https` with `https://127.0.0.1:3000/wetty;` because we configured `wetty` to run via `https` using our self signed ssl certificates. If you chose not to run WeTTY with a self signed certificate you should changes this to `http://127.0.0.1:3000/wetty;`
configured `wetty` to run via `https`
The copy and paste this into the `https` server block of your enable server
The copy and paste this into the `https` server block of your enable server configuration file.
userdocs
4 years ago
GitHub