Skip to content

Commit

Permalink
Updating INSTALLING.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@questionlp
questionlp committed Aug 19, 2022
1 parent 066e32e commit ec034d1
Showing 1 changed file with 23 additions and 78 deletions.
101 changes: 23 additions & 78 deletions INSTALLING.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,8 @@
# INSTALLING

The following instructions target Ubuntu 20.04 LTS but should also apply to any
system that uses `systemd` to install and manage services. Python 3.8 or newer
is required and the system must already have a working installation available.
The following instructions target Ubuntu 20.04 LTS and Ubuntu 22.04 LTS; but, with some minor changes, should also apply to Linux distribution that uses `systemd` to manage services. Python 3.8 or newer is required and the system must already have a working installation available.

This document provides instructions on how to serve the application through
[Gunicorn](https://gunicorn.org) and use [NGINX](https://nginx.org/) as a
front-end HTTP server. Other options are available for serving up FastAPI
applications, but those options will not be covered here.
This document provides instructions on how to serve the application through [Gunicorn](https://gunicorn.org) and use [NGINX](https://nginx.org/) as a front-end HTTP server. Other options are available for serving up FastAPI applications, but those options will not be covered here.

## Installing the Application

Expand All @@ -17,8 +12,7 @@ Clone a copy of this repository to a location of your choosing by running:
git clone https://github.com/questionlp/api.wwdt.me_v2.git
```

Within the new local copy of the repository, create a new virtual environment
and install the required packages by running the following commands:
Within the new local copy of the repository, create a new virtual environment and install the required packages by running the following commands:

```bash
python3 -m venv venv
Expand All @@ -27,98 +21,58 @@ pip install -U pip setuptools wheel
pip install -r requirements.txt
```

Next, make a copy of the `config.json.dist` file and name it `config.json`.
Edit the `config.json` file and fill in the required database connection
information and any other settings that are specific to your environment.
Next, make a copy of the `config.json.dist` file and name it `config.json`. Edit the `config.json` file and fill in the required database connection information and any other settings that are specific to your environment.

To validate the installation, start up `uvicorn` using the following command
while in the application root directory and with the virtual environment
activated:
To validate the installation, start up `uvicorn` using the following command while in the application root directory and with the virtual environment activated:

```bash
uvicorn app.main:app --reload
```

Once started, open a browser and go to <http://127.0.0.1:8000/docs>. This
should bring up the Swagger UI interface. Use the interface to test the
various endpoints provided.
Once started, open a browser and go to <http://127.0.0.1:8000/docs>. This should bring up the Swagger UI interface. Use the interface to test the various endpoints provided.

## MySQL sql_mode Flags

The Stats Page includes SQL queries that were written to target MySQL 5.5 and
MariaDB 10.x. Some of the queries may throw errors due to violation of the
`sql_mode` flag `ONLY_FULL_GROUP_BY` on newer versions of MySQL.
Earlier versions of the Stats API application included SQL queries that were written to target MySQL 5.5 and MariaDB 10.x. Some of the queries may throw errors due to violation of the `sql_mode` flag `ONLY_FULL_GROUP_BY` on newer versions of MySQL. These SQL queries should already be updated to resolve such errors.

To remove the `ONLY_FULL_GROUP_BY` flag from the global `sql_mode` variable,
you will first need to query the current value of `sql_mode` by running:
In case these errors persist when running older versions of the Stats API application, the `ONLY_FULL_GROUP_BY` flag needs to be removed from the global `sql_mode` variable. To verify which flags are currently set, you will first need to query the current value of `sql_mode` by running:

```sql
select @@sql_mode;
```

Copy the result and remove the `ONLY_FULL_GROUP_BY` flag from the string and
run the following command to unset the flag globally until the MySQL service
is restarted:

```sql
set global sql_mode='<flags>';
```

In order for the flag to be set on MySQL service startup, you will need to
update the `mysqld.cnf` file on the server with the following configuration
line:
In order for the flag to be set on MySQL service startup, you will need to update the `mysqld.cnf` file on the server with the following configuration line and then restart the service.

```text
sql-mode = <flags>
```

## Configuring Gunicorn

Gunicorn can take configuration options either as command line arguments or it
can load configuration options from a `gunicorn.conf.py` file located in the
same directory that Gunicorn is launched from.
Gunicorn can take configuration options either as command line arguments or it can load configuration options from a `gunicorn.conf.py` file located in the same directory that Gunicorn is launched from.

A template configuration file is included in the repository called
`gunicorn.conf.py.dist`. A copy of that file should be made and named
`gunicorn.conf.py` and the configuration options reviewed. The following
options may need to be changed depending on the environment in which the
application is being deployed:
A template configuration file is included in the repository called `gunicorn.conf.py.dist`. A copy of that file should be made and named `gunicorn.conf.py` and the configuration options reviewed. The following options may need to be changed depending on the environment in which the application is being deployed:

* `bind`: The template defaults to using a UNIX socket file at
`/tmp/gunicorn-wwdtmapi.sock` as the listener. If TCP socket is preferred,
change the value to `IP:PORT` (replacing `IP` and `PORT` with the
appropriate IP address of the interface and TCP port to listen to)
* `bind`: The template defaults to using a UNIX socket file at `/tmp/gunicorn-wwdtmapi.sock` as the listener. If TCP socket is preferred, change the value to `IP:PORT` (replacing `IP` and `PORT` with the appropriate IP address of the interface and TCP port to listen to)
* `workers`: The number of processes that are created to handle requests.
* `accesslog`: The file that will be used to write access log entries to.
Change the value from a string to `None` to disable access logging if that'll
be handled by NGINX or a front-end HTTP server.
* `errorlog`: The file that will be used to write error log entries to.
Change the value from a string to `None` to disable error logging (not
recommended).
* `accesslog`: The file that will be used to write access log entries to. Change the value from a string to `None` to disable access logging if that'll be handled by NGINX or a front-end HTTP server.
* `errorlog`: The file that will be used to write error log entries to. Change the value from a string to `None` to disable error logging (not recommended).

For more information on the above configuration options and other configuration
options avaiable, check out the [Gunicorn documentation site](https://docs.gunicorn.org/en/stable/settings.html).
For more information on the above configuration options and other configuration options avaiable, check out the [Gunicorn documentation site](https://docs.gunicorn.org/en/stable/settings.html).

## Setting up a Gunicorn systemd Service

A template `systemd` service file is included in the repository named
`gunicorn-wwdtmapi.service.dist`. That service file provides the commands and
arguments used to start a Gunicorn instance to serve up the application. A copy
of that template file can be modified and installed under `/etc/systemd/system`.
A template `systemd` service file is included in the repository named `gunicorn-wwdtmapi.service.dist`. That service file provides the commands and arguments used to start a Gunicorn instance to serve up the application. A copy of that template file can be modified and installed under `/etc/systemd/system`.

For this document, the service file will be installed as `gunicorn-wwdtmapi.service`
and the service name will be `gunicorn-wwdtmapi`. The service file name, thus the
service name, can be changed to meet your needs and requirements.
For this document, the service file will be installed as `gunicorn-wwdtmapi.service` and the service name will be `gunicorn-wwdtmapi`. The service file name, thus the service name, can be changed to meet your needs and requirements.

You will need to modify the following items in the new service file:

* `User`: The user which the service will run under
* `Group`: The group which the service will run under
* `WorkingDirectory`: Provide the full path to the application root directory.
**Do not** include the `app` directory in the path
* `WorkingDirectory`: Provide the full path to the application root directory. **Do not** include the `app` directory in the path
* `Environment`: Add the full path to the `venv/bin` directory
* `ExecStart`: Include the full path to the `venv/bin` directory and insert
that between `ExecStart=` and `gunicorn`
* `ExecStart`: Include the full path to the `venv/bin` directory and insert that between `ExecStart=` and `gunicorn`

Save the file and run the following commands to enable and start the new service:

Expand All @@ -135,13 +89,9 @@ sudo systemctl status gunicorn-wwdtmapi

## Serving the Application Through NGINX

Once the service is up and running, NGINX can be configured to proxy requests
to Gunicorn. NGINX can also be set up to cache responses and provide additional
access controls that may not be feasible with Gunicorn.
Once the service is up and running, NGINX can be configured to proxy requests to Gunicorn. NGINX can also be set up to cache responses and provide additional access controls that may not be feasible with Gunicorn.

Add the following NGINX configuration snippet either to your base `nginx.conf`
or to a virtual site configuration file. The configuration settings provides a
starting point for serving up the application.
Add the following NGINX configuration snippet either to your base `nginx.conf` or to a virtual site configuration file. The configuration settings provides a starting point for serving up the application.

```nginx
upstream gunicorn-wwdtmapi {
Expand All @@ -160,11 +110,6 @@ server {
}
```

The application will handle all of the core URL routing needs, including:
the `/v2.0` base for all endpoints, `/v2.0/docs` for Redoc API documentation
and `/v2.0/openapi` for Swagger UI.
The application will handle all of the core URL routing needs, including: the `/v2.0` base for all endpoints, `/v2.0/docs` for Redoc API documentation and `/v2.0/openapi` for Swagger UI.

NGINX can also be configured to cache API responses. NGINX has documentation
on configuring and enable proxy caching in their
[ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html)
module documentation.
NGINX can also be configured to cache API responses. NGINX has documentation on configuring and enable proxy caching in their [ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html) module documentation.

0 comments on commit ec034d1

Please sign in to comment.