userdocs 5 years ago
parent
commit
e5c6e2ce8a
  1. 184
      docs/atoz.md

184
docs/atoz.md

@ -8,22 +8,22 @@ You will need the package `build-essential` to be installed. We need this specif
As the `root` user run these commands:
~~~bash
```bash
apt update
apt install -y build-essential
~~~
```
If you do not have root access and just want to check the dependency is installed you can use this command:
~~~bash
```bash
dpkg -s build-essential | grep Status:
~~~
```
If the program is installed you will see this result:
~~~bash
```bash
Status: install ok installed
~~~
```
### Create a local user account
@ -35,9 +35,9 @@ 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
~~~bash
```bash
adduser --gecos "" username
~~~
```
Switch to your local user now and open an `ssh` session to continue with this guide.
@ -45,30 +45,30 @@ Switch to your local user now and open an `ssh` session to continue with this gu
To install and manage `node` as a local user we are going to use [Node Version Manager](https://github.com/nvm-sh/nvm) as an established solution to installing and managing multiple versions of node without needing `root` access. We are going to install the `lts` or long term support release of `node` to use with this application.
~~~bash
```bash
bash <(curl -s https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh) && source ~/.profile
nvm install --lts
~~~
```
You can now call `node` to check it works using this command.
~~~bash
```bash
node -v
~~~
```
Your result should look something like this.
~~~bash
```bash
v12.16.2
~~~
```
**Note:** There is consideration with this method. `node` is only in the local 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 over come this issue for the needs of this guide is by using this command where applicable:
~~~bash
```bash
source ~/.nvm/nvm.sh && nvm which 12
~~~
```
**Why?** This command will always provide us with the path to the most current version of `node 12` installed via `nvm` regardless of other versions of `node` installed.
@ -78,25 +78,25 @@ source ~/.nvm/nvm.sh && nvm which 12
Make the required directory using this command:
~~~bash
```bash
mkdir -p ~/.ssl
~~~
```
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 `secp521r1` curve.
~~~bash
```bash
openssl req -x509 -nodes -days 1095 -newkey ec:<(openssl ecparam -name secp521r1) -subj "/C=GB/ST=None/L=None/O=None/OU=None/CN=None" -out ~/.ssl/wetty.crt -keyout ~/.ssl/wetty.key
~~~
```
Now give these file and folders the correct permissions using these commands:
~~~bash
```bash
chmod 700 ~/.ssl
chmod 644 ~/.ssl/wetty.crt
chmod 600 ~/.ssl/wetty.key
~~~
```
This is all we need to do for now in regards to https.
@ -106,37 +106,37 @@ This is all we need to do for now in regards to https.
Make the required directory, if it does not exist, using this command:
~~~bash
```bash
mkdir -p ~/.ssh
~~~
```
Create the `ssh` private key using `ed25519` that we need to authorise our local connection, using this command:
~~~bash
```bash
ssh-keygen -q -C "wetty-keyfile" -t ed25519 -N '' -f ~/.ssh/wetty 2>/dev/null <<< y >/dev/null
~~~
```
**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:
~~~bash
```bash
cat ~/.ssh/wetty.pub >> ~/.ssh/authorized_keys
~~~
```
Now give these file and folders the correct permissions, using these commands:
~~~bash
```bash
chmod 700 ~/.ssh
chmod 644 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/wetty
~~~
```
**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
```bash
sed -r '/^ssh-ed25519(.*)wetty-keyfile$/d' -i ~/.ssh/authorized_keys
~~~
```
### Install wetty
@ -146,30 +146,30 @@ As your local user run these commands to install `wetty` and `forever`. We will
First, we need to make sure the local user's `~/bin` folder exists and is in the `PATH` for the following commands to work.
~~~bash
```bash
mkdir -p ~/bin && source ~/.profile
~~~
```
Please use either the `npm` or `yarn` method and not both. The `yarn` method is 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 ~/
~~~
```
`yarn` - recommended - use `yarn` to install wetty
~~~bash
```bash
npm install -g yarn --prefix ~/
yarn global add wetty forever --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:
~~~bash
```bash
wetty -h
~~~
```
### Accessing the web interface.
@ -177,9 +177,9 @@ This needs to be done here because it is not easy to do in the next steps if `we
This command will generate the correct URL you need to visit after using the start up commands in the following section.
~~~bash
```bash
echo https://$(curl -s4 icanhazip.com):3000
~~~
```
*Please make make a note of this URL now.*
@ -191,23 +191,23 @@ For example, the below command would provide a `https` instance with automatic `
**Important note:** This command will run in your current terminal session and not in the background.
~~~bash
```bash
wetty --host 0.0.0.0 -p 3000 --title wetty --base / --sshkey ~/.ssh/wetty --sshhost localhost --sshuser $(whoami) --sshport 22 --sshauth publickey --sslkey ~/.ssl/wetty.key --sslcert ~/.ssl/wetty.crt
~~~
```
#### forever to manage wetty
Now you can use `forever` we installed to run `wetty` in the background instead of directly in your terminal
~~~bash
```bash
forever start ~/bin/wetty --host 0.0.0.0 -p 3000 --title wetty --base / --sshkey ~/.ssh/wetty --sshhost localhost --sshuser $(whoami) --sshport 22 --sshauth publickey --sslkey ~/.ssl/wetty.key --sslcert ~/.ssl/wetty.crt
~~~
```
To stop `wetty` from running you can use this command
~~~bash
```bash
forever stop ~/bin/wetty
~~~
```
#### Optional - config file.
@ -217,49 +217,49 @@ Since `wetty` does not have configurations files and all commands are passed as
Create a directory to store our configuration data using this command:
~~~bash
```bash
mkdir -p ~/.config/wetty
~~~
```
Now populate our `config` file with some settings. This examples is the same command as above.
~~~bash
```bash
echo -n '--host 0.0.0.0 -p 3000 --title wetty --base / --sshkey ~/.ssh/wetty --sshhost localhost --sshuser $(whoami) --sshport 22 --sshauth publickey --sslkey ~/.ssl/wetty.key --sslcert ~/.ssl/wetty.crt' > ~/.config/wetty/config
~~~
```
This configuration file is now available here for you to manage your settings.
~~~bash
```bash
~/.config/wetty/config
~~~
```
Now we can load this file as part of the command we pass to `wetty` with shell expansion and command substitution.
~~~bash
```bash
wetty $(eval echo $(cat ~/.config/wetty/config))
~~~
```
#### forever using a config file
Now you can use `forever` to run it in the background instead of directly in your terminal
~~~bash
```bash
forever start ~/bin/wetty $(eval echo $(cat ~/.config/wetty/config))
~~~
```
To stop `wetty` from running you can use this command:
~~~bash
```bash
forever stop ~/bin/wetty
~~~
```
#### Environment settings explained
Let's break it down so that we can understand what's being done and why.
~~~bash
```bash
--host 0.0.0.0 -p 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.
@ -273,9 +273,9 @@ Let's break it down so that we can understand what's being done and why.
These settings are all specific to `ssh` and will enable you to automatically log into you ssh session for the selected user.
~~~bash
```bash
--sshkey ~/.ssh/wetty --sshhost localhost --sshuser $(whoami) --sshport 22 --sshauth publickey
~~~
```
`--sshkey ~/.ssh/wetty` - we are telling `wetty` to load our `ssh` key file that we generated earlier.
@ -291,9 +291,9 @@ These settings are all specific to `ssh` and will enable you to automatically lo
These settings are specific to `openssl` to make `wetty` load https webserver so that all data is transmitted over a secure connection.
~~~bash
```bash
--sslkey ~/.ssl/wetty.key --sslcert ~/.ssl/wetty.crt
~~~
```
`--sslkey ~/.ssl/wetty.key` - tells `wetty` to load our `openssl` generated key file.
@ -305,9 +305,9 @@ We will use a local user `systemd` service file to manage the `wetty` service.
First, create the required directory, if it does not exist.
~~~bash
```bash
mkdir -p ~/.config/systemd/user
~~~
```
#### Systemd service.
@ -315,13 +315,13 @@ Here is a normal service file template with hardcoded values you can insert into
Use `nano` to open the file for editing.
~~~
```
nano ~/.config/systemd/user/wetty.service
~~~
```
The copy and paste this code.
~~~bash
```bash
[Unit]
Description=wetty
After=network.target
@ -337,7 +337,7 @@ RestartSec=2
[Install]
WantedBy=multi-user.target
~~~
```
Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and exit `nano`.
@ -347,13 +347,13 @@ Here is the example using our pseudo configuration file. All modifications to th
Use `nano` to open the file for editing.
~~~bash
```bash
nano ~/.config/systemd/user/wetty.service
~~~
```
The copy and paste this code.
~~~bash
```bash
[Unit]
Description=wetty
After=network.target
@ -369,7 +369,7 @@ RestartSec=2
[Install]
WantedBy=multi-user.target
~~~
```
Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and exit `nano`.
@ -377,15 +377,15 @@ Press `ctrl` + `x` and then press `y` to save then press `enter` to confirm and
The you can enable and start your service.
~~~bash
```bash
systemctl --user enable --now wetty
~~~
```
#### Managing your services
These commands will help you manage your service.
~~~bash
```bash
systemctl --user daemon-reload
systemctl --user status wetty
systemctl --user start wetty
@ -393,7 +393,7 @@ systemctl --user stop wetty
systemctl --user restart wetty
systemctl --user disable --now wetty
systemctl --user enable --now wetty
~~~
```
### Nginx reverse proxy
@ -403,15 +403,15 @@ Please modify these specific environment settings:
**Why?** This will disable generic port access to the application and force traffic via the nginx reverse proxy.
~~~bash
```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.
~~~bash
```bash
--base /wetty/
~~~
```
Now you can use this nginx configuration file.
@ -419,7 +419,7 @@ Now you can use this nginx configuration file.
The copy and paste this into the `https` server block of your enable server configuration file.
~~~nginx
```nginx
location /wetty {
proxy_pass https://127.0.0.1:3000/wetty;
#
@ -444,29 +444,29 @@ location /wetty {
proxy_redirect off;
proxy_buffering off;
}
~~~
```
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:
~~~bash
```bash
systemctl restart nginx
~~~
```
#### Accessing the web interface via nginx
Visit the URL format `https://YourIP/wetty` and you can access `wetty`. This command will generate the correct URL you need to visit.
~~~bash
```bash
echo https://$(curl -s4 icanhazip.com)/wetty
~~~
```
### Configuration reference
`wetty -h` configuration options for reference.
~~~bash
```bash
--help, -h Print help message [boolean]
--version Show version number [boolean]
--sslkey path to SSL key [string]
@ -484,4 +484,4 @@ echo https://$(curl -s4 icanhazip.com)/wetty
--host wetty listen host [string] [default: "0.0.0.0"]
--command, -c command to run in shell [string] [default: "login"]
--bypasshelmet disable helmet from placing security restrictions [boolean] [default: false]
~~~
```

Loading…
Cancel
Save