[ToC]

# What is ready?
:heavy_check_mark: VPN API module is almost ready for production use.
:heavy_check_mark: All language bridge routes are ready
:heavy_check_mark: All auth api routes are ready
:heavy_check_mark: Authentication bridge is implemented and working (`/vpn/api/<api>?code=xxxxxx`)
:heavy_check_mark: Trial user registration is working (`/vpn/api/register/<source>`)
:heavy_check_mark: OpenVPN API route is implemented. All certificate data is generated and returned properly
:heavy_check_mark: GeoIP2 API is integrated and working (databases need to be put to the project manually)

Missing:
:x: Sync-softether users script is not implemented/integrated (`script/sync-softether-users.pl`).
That is the post-update OpenVPN is not complete.
AND that means the VPN **softether** servers won't get new users to serve.
:x: Localization implementation
:x: Payment is not integrated for paid users (actually this is not part of VPN API but the Xhoer's bussiness logic)
:x: Cookie session is not integrated

---
# Dependencies and Requirements
#### Ubuntu packages
- `cpanm >= 1.7044` (cpan minus) or `cpan >= 1.62`
- `perl >= v5.30.0`
- `python >= 3.8`
- `mariadb >= 10.3.32`

---
# How to deploy
## 1. Prepare environment
1. Get the repository.
`git clone <repository_url>`
`cd whoer-web`
1. Change directory to project root:
`cd whoer-web`
2. Then create python virtual environment:
`python3 -m venv venv`
3. Activate environment:
`. venv/bin/activate`
4. Install packages:
`pip install -r requirements.txt`

5. Install CPAN dependencies:
The next block is not necessary to read:
> CPAN is perl's package manager.
CPANM (cpan minus) is also perl's package manager, but it is not distributed along with perl itself and it is not officially supported.
CPANM is a reduced version of CPANP (cpan plus).

> You can install packages either with cpan or cpanm.
The difference is that the cpanm allows you to specify custom directory for installation.
CPAN does not.
But if you have system root access (which is probably the case :)) then you can use it to install packages system-wide (globally for system).

The list of Perl's additional packages for new project to work properly:
- `File::Slurp`
- `JSON`
- `Try::Tiny`

Use `cpan install <package_name>` or `cpanm install <package_name>` to install those packages.

## 2. Prepare database:
1. Create database (if not exists) and user:
`./manager.py database init`

* default database and user credentials will be replaced from `.env` file.
* refer `settings.py` in root of project for configuration names.
2. Update database structure:
`alembic upgrade head`

This is the list of variables and their defaults for database configuration:
- `MYSQL_HOST` = 127.0.0.1
- `MYSQL_PORT` = 3306
- `MYSQL_USER` = whdevel
- `MYSQL_PASSWORD` = zua6Gohxai
- `MYSQL_DATABASE_NAME` = whdevel
- `MYSQL_SCHEME_FILE` = whoer-web/misc/scheme.sql (to load scheme from old project)

Futher are used to setup database from scratch, that is if you don't have user setup.
- `MYSQL_ROOT_USER` = MYSQL_USER
- `MYSQL_ROOT_PASS` = MYSQL_PASSWORD

## 3. Prepare configs and data
The new project does store all the major configuration, such as vpn servers list, in the database.
That is said we need to migrate all the records from the old project's configuration files to new project's database tables.

This can be done more or less automatically.

### !!!!! BEWARE !!!!!:
> When you run commands from step 2 below.
You need to be sure to set proper **SERVER_MODE** value.
By default its `dev`.
But if you set a `prod` value, ensure twice this is really you want to do.
If you run in production mode, all the configs will be parsed from production configs of old project and thus all request and data manipulations will be done on the objects from your production evironment.
For example: the requests on updating users data will be made to your remote **production** servers.

1. Firstly prepare your `.env` and specify all the needed and required options, such as database configuration, specify needed paths (such as root of old xhoer project). Some of the required options are described below:

2. To migrate automatically, use the CLI tool created specially for this purpose:
`./manager.py parse all` - this command will convert perl configuration to JSON.
`./manager.py database load all` - this will load all the data from parsed configs into database

3. Set proper values for next environment variables:
- WHOERCA_PATH - root for WHOER Certificate Authority repository
- XHOER_DIR - root for Xhoer project repository

## 5. Setting up GEOIP2
In general you only need to copy your `*.mmdb` files to the `whoer-web/var/mmd` and set GeoIP2 credentials for your account.
For know account is not used, but futher the GeoIP2 databases will be deployed and updated automatically from your GeoIP2 account.

Environment variables to set in `.env`:
- MMDB_PATH_PREFIX = whoer-web/var/mmdb - specify the path where all the `*.mmdb` files are placed
- GEOIP2_ACCOUNT_ID
- GEOIP2_LICENSE_KEY
- GEOIP2_HOST

## 4. Starting server
**!!! WARN !!!**:
Before starting server ensure you set proper `SERVER_MODE` environment variable.
By default its `dev`

1. Run the server:
`./manager.py site server run --host 127.0.0.1 --port 8888`

## 5. Redirect api routes from old project to new project:
Inside of your nginx config for old Xhoer server set rules to redirect `/en/vpn/api` to the new project.
Where `en` is 2alpha language code

location ~^/\w{2}\/vpn\/api/.*/ {
  proxy_pass  http://localhost:8000/vpn/api; # new project url
  ...
}