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.
**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.
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.
**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.
## Required dependencies
`Node` - WeTTY requires node v14 or greater. We will install this locally for a non root user later in the guide.
`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.
`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.
`build-essential` - We need this specifically for `node-gyp` to build packages
when using `npm` or `yarn` to install packages.
As the `root` or `sudo` user run these commands:
@ -19,7 +30,8 @@ sudo apt update
sudo apt install -y build-essential curl python
```
If you have no root access and just want to check the dependencies are installed you can use these commands:
If you have no root access and just want to check the dependencies are installed
you can use these commands:
```bash
dpkg -s python | grep Status:
@ -34,23 +46,32 @@ Status: install ok installed
## Create a local user 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.
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.
**Note:** Whichever user runs WeTTY should be the same user you wish to authenticate with via `ssh` to keep this guide simple.
**Note:** Whichever user runs WeTTY should be the same user you wish to
authenticate with via `ssh` to keep this guide simple.
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 create a password when prompted
**Important note:** replace `username` with a user name of your choosing and
create a password when prompted
```bash
adduser --gecos "" username
```
Switch to your local user now and open an `ssh` session to continue with this guide.
Switch to your local user now and open an `ssh` session to continue with this
guide.
## Install node locally
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.
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.
This command will download and install `nvm` and reload our shell.
@ -58,7 +79,8 @@ This command will download and install `nvm` and reload our shell.
This command will install the latest version of the v14 branch, which is the minimum required version for WeTTY.
This command will install the latest version of the v14 branch, which is the
minimum required version for WeTTY.
```bash
nvm install 14
@ -76,17 +98,26 @@ Your result should look something like this.
v14.16.1
```
**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:
**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:
```bash
$(source ~/.nvm/nvm.sh && nvm which 14)
```
**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`.
**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`.
## Generate OpenSSL certificates
**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.
**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.
Make the required directory using this command:
@ -94,9 +125,11 @@ Make the required directory using this command:
mkdir -p ~/.ssl
```
Generate the self signed `openssl` certificates we will use to encrypt our web traffic when using WeTTY using this command:
Generate the self signed `openssl` certificates we will use to encrypt our web
traffic when using WeTTY using this command:
**Note:** we are using `ecdsa` using the `secp384r1` curve. Tested to be compatible with Chrome and Firefox browsers.
**Note:** we are using `ecdsa` using the `secp384r1` curve. Tested to be
**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.
**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.
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 WeTTY public key with the comment `wetty-keyfile` from the `~/.ssh/authorized_keys` file use this command. Otherwise ignore this.
**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.
```bash
sed -r '/^ssh-ed25519(.*)wetty-keyfile$/d' -i ~/.ssh/authorized_keys
@ -152,11 +191,14 @@ sed -r '/^ssh-ed25519(.*)wetty-keyfile$/d' -i ~/.ssh/authorized_keys
## Install WeTTY
**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`.
**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`.
As your local user run these commands:
To make sure the local user's `~/bin` directory exists and is in the `PATH` please run the following command.
To make sure the local user's `~/bin` directory exists and is in the `PATH`
please run the following command.
```bash
mkdir -p ~/bin && source ~/.profile
@ -174,7 +216,8 @@ Then use `yarn` to install `wetty`.
yarn global add wetty --prefix ~/
```
Once successfully installed the application should be available in your local user's `PATH`. To test the installation was successful please use this command:
Once successfully installed the application should be available in your local
user's `PATH`. To test the installation was successful please use this command:
```bash
wetty -h
@ -182,9 +225,12 @@ wetty -h
## Accessing the web interface via our external IP
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.
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.
This command will generate the correct URL you need to visit after using the start up commands in the following section.
This command will generate the correct URL you need to visit after using the
start up commands in the following section.
```bash
echo https://$(curl -s4 icanhazip.com):3000
@ -194,17 +240,23 @@ _Please make make a note of this URL now._
## Running WeTTY
Now we have all the ground work done we can focus on our WeTTY server configuration settings.
Now we have all the ground work done we can focus on our WeTTY server
configuration settings.
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` .
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` .
**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.
**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
Since you may not need all these settings we will look through what each one does below so that you can decide how to best configure your instance.
Since you may not need all these settings we will look through what each one
does below so that you can decide how to best configure your instance.
### Environment settings explained
@ -214,33 +266,51 @@ Let's break it down so that we can understand what's being done and why.
--host 0.0.0.0 --port 3000 --title wetty --base /
```
`--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.
`--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.
`--port 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.
`--port 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.
`--title wetty` - an optional setting to set the window title for this `wetty` session.
`--title wetty` - an optional setting to set the window title for this `wetty`
session.
`--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.
`--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.
### SSH settings explained
These settings are all specific to `ssh` and will enable you to automatically log into you `ssh` session for the selected user.
These settings are all specific to `ssh` and will enable you to automatically
`--ssh-key ~/.ssh/wetty` - we are telling WeTTY to load our `ssh` key file that we generated earlier.
`--ssh-key ~/.ssh/wetty` - we are telling WeTTY to load our `ssh` key file that
we generated earlier.
`--ssh-host localhost` - optional setting telling WeTTY to connect the host `localhost`
`--ssh-host localhost` - optional setting telling WeTTY to connect the host
`localhost`
`--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.
`--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.
`--ssh-port 22` - optional setting to set the `ssh` port we need to connect to.
`--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-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-config configfile` - (not used for this guide) alternative ssh configuration file. From ssh(1):
`--ssh-config configfile` - (not used for this guide) alternative ssh
configuration file. From ssh(1):
> If a configuration file is given on the command line, the system-wide
> configuration file (/etc/ssh/ssh_config) will be ignored. The default for the
@ -248,19 +318,23 @@ These settings are all specific to `ssh` and will enable you to automatically lo
### SSL settings explained
These settings are specific to `openssl` to make WeTTY load https webserver so that all data is transmitted over a secure connection.
These settings are specific to `openssl` to make WeTTY load https webserver so
that all data is transmitted over a secure connection.
Here is the template `config.json` you need to use.
**Note:** To be [validated json](https://codebeautify.org/jsonvalidator) the below json example should have the `// ...` comments removed. With all comments removed the example is valid json. They are in the example to help explain the options and won't stop wetty from loading if you leave them in place. Lines you do not need can be commented out but should be removed if you want the json to pass validation.
**Note:** To be [validated json](https://codebeautify.org/jsonvalidator) the
below json example should have the `// ...` comments removed. With all comments
removed the example is valid json. They are in the example to help explain the
options and won't stop wetty from loading if you leave them in place. Lines you
do not need can be commented out but should be removed if you want the json to
pass validation.
```json
"ssh": {
@ -304,13 +383,16 @@ Here is the template `config.json` you need to use.
}
```
Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and exit `nano`.
Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and
exit `nano`.
## System Environment Variables
**Note:** We will not be using this section to configure WeTTY. We are simply documenting it.
**Note:** We will not be using this section to configure WeTTY. We are simply
documenting it.
There are some environment variables you can export that can be used by WeTTY to configure an instance.
There are some environment variables you can export that can be used by WeTTY to
**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.
**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.
```bash
[Unit]
@ -376,11 +461,14 @@ SyslogIdentifier=wetty
WantedBy=default.target
```
Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and exit `nano`.
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`.
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`
**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.
**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.
```bash
[Unit]
@ -409,7 +499,8 @@ SyslogIdentifier=wetty
WantedBy=default.target
```
Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and exit `nano`.
Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and
If you want to use nginx as a reverse proxy here is the configuration file you can use.
If you want to use nginx as a reverse proxy here is the configuration file you
can use.
Please modify these specific environment settings:
**Why?** This will disable generic port access to the application and force traffic via the nginx reverse proxy.
**Why?** This will disable generic port access to the application and force
traffic via the nginx reverse proxy.
```bash
--host 127.0.0.1
```
**Why?** This change is so that our application does not attempt to load as the web root of `/` for nginx.
**Why?** This change is so that our application does not attempt to load as the
web root of `/` for nginx.
```bash
--base /wetty/
@ -453,9 +547,13 @@ Please modify these specific environment settings:
Now you can use this nginx configuration file.
**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;`
**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;`
The copy and paste this into the `https` server block of your enable server configuration file.
The copy and paste this into the `https` server block of your enable server
configuration file.
```nginx
location /wetty {
@ -484,7 +582,8 @@ location /wetty {
}
```
Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and exit `nano`
Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and
exit `nano`
Now you would need to reload nginx service using this command:
@ -496,7 +595,8 @@ systemctl restart nginx
Visit the URL format `https://YourIPorDomain/wetty` and you can access WeTTY.
This command will generate the correct URL you need to visit it you are not using a domain.
This command will generate the correct URL you need to visit it you are not
Cian Butler
3 years ago
GitHub