github.com/litesolutions/justifay-api@v1.0.0-2.0.20220707114139-46f28a909481/README.md (about)

     1  # Justifay API
     2  
     3  ## Running
     4  
     5  Running `go run main.go runserver` starts a web server on https://0.0.0.0:11000/. You can configure
     6  the port used with the `$PORT` environment variable, and to serve on HTTP set
     7  `$SERVE_HTTP=true`.
     8  
     9  ```
    10  $ go run main.go runserver
    11  ```
    12  
    13  An OpenAPI UI is served on https://0.0.0.0:11000/.
    14  
    15  ## Getting started
    16  
    17  After cloning the repo, there are a couple of initial steps;
    18  
    19  1. Ensure that you have [Go](https://go.dev/doc/install) installed on your system.
    20  2. Install the generate dependencies with `make install`.
    21     This will install `buf`, `protoc-gen-go`, `protoc-gen-go-grpc`, `protoc-gen-grpc-gateway`,
    22     `protoc-gen-openapiv2` and `statik` which are necessary for us to generate the Go, swagger and static files.
    23  3. Install the git submodule(s) with `git submodule update --init` from root directory of the cloned repo
    24  4. Finally, generate the files with `make generate`.
    25  5. Now, you'll need to generate a certificate:
    26  ```sh
    27  mkcert -install
    28  mkcert 0.0.0.0 127.0.0.1 localhost ::1
    29  ```
    30  
    31  The certificate is in the directory you ran the above command from. Rename the key file (something like `./0.0.0.0+3-key.pem`) to `uaclient.key` and the certificate file (something like `./0.0.0.0+3.pem`) to `uaclient.pem`. Copy both of the renamed files to `/usr/local/etc/nginx/ssl` (if you don't have an `ssl` folder in your nginx directory, create one).
    32  
    33  Serve the User API at https://127.0.0.1:11000 with this command:
    34  ```sh
    35  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go runserver -env dev -dbdebug true
    36  ```
    37  6. Start the server:
    38  ```sh
    39  pg_ctl -D /usr/local/var/postgres -l logfile start
    40  ```
    41  
    42  ## Dev database setup
    43  
    44  * Create user and database as follows (as found in the local config file in `./conf.local.yaml`):
    45  
    46  username = "justifay_dev_user"
    47  
    48  password = "password"
    49  
    50  dbname = "justifay_dev"
    51  
    52  To get into the Postgres shell, run:
    53  ```
    54  psql
    55  ```
    56  
    57  ```sql
    58  CREATE DATABASE justifay_dev;
    59  CREATE USER justifay_dev_user WITH PASSWORD 'password';
    60  GRANT ALL PRIVILEGES ON DATABASE justifay_dev TO justifay_dev_user;
    61  ```
    62  
    63  * And add the `hstore` and `uuid-ossp` extensions, confirming with the `SELECT` statement.
    64  ```sql
    65  \c justifay_dev;
    66  CREATE EXTENSION hstore;
    67  CREATE EXTENSION "uuid-ossp";
    68  SELECT * FROM pg_extension;
    69  ```
    70  
    71  * Then, run these migrations (from the root of the user-api):
    72  ```sh
    73  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go db -env dev init
    74  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go db -env dev migrate                                                                                                     
    75  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go db -env dev load_default_fixtures
    76  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go db -env dev load_test_fixtures
    77  ```
    78  
    79  * Then, repeat the last two above blocks replacing `dev` with `test`.
    80  
    81  If you need to roll back:
    82  
    83  ```sh
    84  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go db -env dev rollback
    85  ```
    86  
    87  ## Tests
    88  
    89  Ongoing WIP atm, but for example, can be run with:
    90  
    91  ```sh
    92  $  go test -timeout 30s -run ^TestDeleteUser$ github.com/litesolutions/justifay-api/server/users
    93  ```
    94  
    95  ## Running!
    96  
    97  Now you can run the web server with `go run main.go runserver`.
    98  
    99  This will default to running in dev and without debug output from queries.
   100  
   101  However, there are two flags:
   102  
   103  - `env` (`dev`, `test` or `prod`, defaults to `dev`)
   104  - `dbdebug` (`true` or `false`, defaults to `false`)
   105  
   106  So e.g. `go run main.go runserver -env test -dbdebug true` will run the server on the test DB (defined in the config) with db query debug output on.
   107  
   108  The PSN connection strings for dev and test are in conf.local.yaml, but for prod this is built from environement variables:
   109  
   110  -	`POSTGRES_NAME` (DB name)
   111  - `POSTGRES_USER` (DB username)
   112  - `POSTGRES_PASS` (DB password)
   113  - `POSTGRES_HOST` (DB host, defaulted `127.0.0.1`)
   114  - `POSTGRES_PORT` (DB port, defaulted `5432`)
   115  - `POSTGRES_SSL` (`enable` or defaulted `disable`)
   116  
   117  ## Docker!
   118  
   119  Build a container with `docker build -t userapi .`
   120  
   121  (to avoid cache, use `--no-cache` option)
   122  
   123  Run container with `docker run -p 11000:11000 --network=host -tid userapi`
   124  
   125  Check status with `docker container ls` and `docker logs <image>`
   126  
   127  (use sudo as required)
   128  
   129  ## Working with a reverse-proxy (like nginx)
   130  
   131  You need to register a certificate in a pair of files.
   132  
   133  This prefix of this file is held in the config file as `cert_name`, default value `uaclient`
   134  
   135  The server will then look for two files, suffix's ".pem" and ".key" in the directory provided by 
   136  the environment variable `UACERT_DIR`
   137  
   138  In your reverse proxy you will need to refer to these too in order to be able to proxy the service securely.
   139  
   140  ## Maintenance
   141  
   142  Interfaces are designed in
   143  `proto/` directory. See https://developers.google.com/protocol-buffers/
   144  tutorials and guides on writing protofiles.
   145  
   146  Once that is done, regenerate the files using
   147  `make generate`. This will mean you'll need to implement any functions in
   148  `server/`, or else the build will fail since your struct won't
   149  be implementing the interface defined by the generated file in `proto/example.pb.go`.