actions-test/README.md

# Outbag Server
Did you know that you can host your own outbag instance? 

This repo contains the official outbag server.

## Setup
**\*Keep in mind that you need a valid SSL certificate for your domain**

### Using docker
[Find docker instructions in the docker repo](https://gitlab.com/outbag/containers)

### Manually
#### Requirements
- `git`
- `nodejs` & `npm`
- a mysql database, we recommend `mariadb`

#### Setting up MariaDB

1. Install `mariadb` using your system's package manager. e.g.:
   ```bash
   sudo apt install mariadb-server
   ```
2. Secure your installation
   ```bash
   sudo mysql_secure_installation
   ```
3. Start the MySQL/MariaDB command line mode (you have to enter the befor given paswsord):
   ```bash
   sudo mysql -u root -p
   ```
4. Then a MariaDB [root]> prompt will appear.
   Create an user and a databse:
   ```sql
   CREATE USER 'outbagUser'@'localhost' IDENTIFIED BY 'aSecurePassword';
   CREATE DATABASE IF NOT EXISTS outbag CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
   GRANT ALL PRIVILEGES ON outbag.* TO 'outbagUser'@'localhost';
   FLUSH PRIVILEGES;
   ```
   To not forget to replace username, password and database name. 
5. You can quit the prompt by entering:
   ```sql
   quit;
   ```
   

#### Install
1. Clone this git repo
   ```bash
   git clone https://gitlab.com/outbag/server/ outbag-server
   cd outbag-server
   ```
2. Download & install the dependecies
   ```bash
   npm install
   ```
#### Setup - with config file
1. Create a config file, e.g. in `/opt/config.juml`, 
   or run the server once, 
   to autogenerate that file.
   ```bash
   node . -c /opt/config.juml
   ```
2. The server will crash.
   Now open the config file with your favourite text editor.
   You have to change the database login details.
3. If you do not proxy your Server from https to http, 
   you have to add the path to your ssl certificate and enable ssl. 
4. After closing the file,
   you can restart the server (It should not crash this time)
   ```bash
   node . -c /opt/config.juml
   ```

#### Setup - with environment variables
1. List of environment variables with default values:
   ```
   OUTBAG_PORT=7223
   OUTBAG_EXPOSED_PORT=7223
   OUTBAG_EXPOSED_PATH=/
   OUTBAG_HOST=localhost
   OUTBAG_CERT_LIVE_SEC=2592000

   OUTBAG_SSL_ENABLED=false
   OUTBAG_SSL_PRIVATE_KEY=privkey.pem
   OUTBAG_SSL_CERT=cert.pem
   OUTBAG_SSL_CHAIN=chain.pem

   OUTBAG_MYSQL_HOST=localhost
   OUTBAG_MYSQL_PORT=3306
   OUTBAG_MYSQL_USER=admin
   OUTBAG_MYSQL_PASSWORD=12346789
   OUTBAG_MYSQL_DATABASE=outbag

   OUTBAG_MAX_USERS=0
   OUTBAG_DEFAULT_MAX_ROOMS=3
   OUTBAG_DEFAULT_MAX_ROOMS_SIZE=10000
   OUTBAG_DEFAULT_MAX_USERS_PER_ROOM=5
   ```
   Only set the environment variables you want to change.
   You have to set the MYSQL varibales.
2. If you do not proxy your Server from https to http, 
   you have to set the path to your ssl certificate and enable ssl. 
3. Start the server
   ```bash
   node .
   ```

### Hosting the UI
As of writing,
there is no official method of having the backend host the UI yet 
(we are working on it).

For the time being,
just follow the [manual guide](https://gitlab.com/outbag/app/)

### Setting up and using a proxy
**NOTE: This is for advanced users only**

If you do not want to expose multiple ports,
you can use a proxy to expose both the app and the server on the same port.

1. Download `nginx` 
(or your favourite `nginx` alternative, e.g. `apache`) 
using your system's package manager. 
e.g.:
   ```bash
   sudo apt install nginx
   ```
2. Open the config file using your favourite text editor.
   _NOTE: The nginx config file is probably located at /etc/nginx/http.d/default.conf_
   You probably want something similar to this in your config file:
   ```conf
   location /api {
      if ($request_uri ~* "/api(/.*$)") {
         set  $path_remainder  $1;
      }
      proxy_pass http://127.0.0.1:7223/$path_remainder;
      proxy_set_header Host $http_host;
      proxy_buffering off;
   }
   location /.well-known/outbag/server {
      proxy_pass http://127.0.0.1:7223/.well-known/outbag/server;
      proxy_set_header Host $http_host;
      proxy_buffering off;
   }
   location / {
      proxy_pass http://127.0.0.1:8080$request_uri;
      proxy_set_header Host $http_host;
      proxy_buffering off;
   }
   ```
3. Next up enable and start the system service 
   (e.g. `systemctl enable nginx` and `systemctl start nginx`; 
   or `rc-update add nginx` and `rc-service nginx start`)
4. Now open `127.0.0.1` or `<your.domain.com>` (when using https)
   in your browser and you should be prompted with the webapp 
   (in case you enabled it)
5. To be able to use the server properly, 
   you should go back to the `docker-compose.yml` file 
   and change the `OUTBAG_EXPOSED_PATH` variable to point to `/api`.
6. To finish of, 
   restart the containers:
   ```bash
   docker-compose down
   docker-compose up -d
   ```
## API
[API docu](https://gitlab.com/outbag/server/-/blob/main/docs/api.md)