github.com/resonatecoop/user-api@v1.0.0-13.0.20220915120639-05dc9c04014a/README.md (about)

     1  > 🛠 **Status: Maintenance Mode | Stable**
     2  >
     3  > This project is currently in [maintenance mode](https://en.wikipedia.org/wiki/Maintenance_mode) - users should feel free to continue to use this app and expect bug fixes, but not expect many additional features.
     4  
     5  # user-api
     6  
     7  This is a significant evolution of @blushi's [original Golang-based user-api](https://github.com/resonatecoop/user-api-old)
     8  
     9  The changes are so significant a new repo was created, but a lot of code lives on from that repo.
    10  
    11  It builds on that work in several important ways:
    12  
    13  - drops Twirp framework in favour of [GRPC-Gateway](https://grpc-ecosystem.github.io/grpc-gateway/) which has gained significant traction
    14  - implements full OpenAPIV2 workflow - write interfaces in protobufs and generate the code stubs, then implement them.
    15  - exposes full Swagger UI automatically
    16  - implements full RBAC using native Golang Interceptors (arguably better than using Twirp Handlers)
    17  - RBAC is based on User role and interface access config in the config file
    18  - built with Go modules for dependency management
    19  - adds a CLI for database management and for running the server
    20  - replaces `go-pg` with `bun`
    21  - merges in the models from `resonatecoop\id`
    22  
    23  It is WIP, do NOT use this in Production yet!
    24  
    25  ## Running
    26  
    27  Running `go run main.go runserver` starts a web server on https://0.0.0.0:11000/. You can configure
    28  the port used with the `$PORT` environment variable, and to serve on HTTP set
    29  `$SERVE_HTTP=true`.
    30  
    31  ```
    32  $ go run main.go runserver
    33  ```
    34  
    35  An OpenAPI UI is served on https://0.0.0.0:11000/.
    36  
    37  ## Getting started
    38  
    39  After cloning the repo, there are a couple of initial steps;
    40  
    41  1. Ensure that you have [Go](https://go.dev/doc/install) installed on your system.
    42  2. Install the generate dependencies with `make install`.
    43     This will install `buf`, `protoc-gen-go`, `protoc-gen-go-grpc`, `protoc-gen-grpc-gateway`,
    44     `protoc-gen-openapiv2` and `statik` which are necessary for us to generate the Go, swagger and static files.
    45  3. Install the git submodule(s) with `git submodule update --init` from root directory of the cloned repo
    46  4. Finally, generate the files with `make generate`.
    47  5. Now, you'll need to generate a certificate:
    48  ```sh
    49  mkcert -install
    50  mkcert 0.0.0.0 127.0.0.1 localhost ::1
    51  ```
    52  
    53  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).
    54  
    55  Serve the User API at https://127.0.0.1:11000 with this command:
    56  ```sh
    57  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go runserver -env dev -dbdebug true
    58  ```
    59  6. Start the server:
    60  ```sh
    61  pg_ctl -D /usr/local/var/postgres -l logfile start
    62  ```
    63  
    64  ## Dev database setup
    65  
    66  * Create user and database as follows (as found in the local config file in `./conf.local.yaml`):
    67  
    68  username = "resonate_dev_user"
    69  
    70  password = "password"
    71  
    72  dbname = "resonate_dev"
    73  
    74  To get into the Postgres shell, run:
    75  ```
    76  psql
    77  ```
    78  
    79  ```sql
    80  CREATE DATABASE resonate_dev;
    81  CREATE USER resonate_dev_user WITH PASSWORD 'password';
    82  GRANT ALL PRIVILEGES ON DATABASE resonate_dev TO resonate_dev_user;
    83  ```
    84  
    85  * And add the `hstore` and `uuid-ossp` extensions, confirming with the `SELECT` statement.
    86  ```sql
    87  \c resonate_dev;
    88  CREATE EXTENSION hstore;
    89  CREATE EXTENSION "uuid-ossp";
    90  SELECT * FROM pg_extension;
    91  ```
    92  
    93  * Then, run these migrations (from the root of the user-api):
    94  ```sh
    95  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go db -env dev init
    96  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go db -env dev migrate                                                                                                     
    97  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go db -env dev load_default_fixtures
    98  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go db -env dev load_test_fixtures
    99  ```
   100  
   101  * Then, repeat the last two above blocks replacing `dev` with `test`.
   102  
   103  If you need to roll back:
   104  
   105  ```sh
   106  UACERT_DIR="/usr/local/etc/nginx/ssl" go run main.go db -env dev rollback
   107  ```
   108  
   109  ## Tests
   110  
   111  Ongoing WIP atm, but for example, can be run with:
   112  
   113  ```sh
   114  $  go test -timeout 30s -run ^TestDeleteUser$ github.com/resonatecoop/user-api/server/users
   115  ```
   116  
   117  ## Running!
   118  
   119  Now you can run the web server with `go run main.go runserver`.
   120  
   121  This will default to running in dev and without debug output from queries.
   122  
   123  However, there are two flags:
   124  
   125  - `env` (`dev`, `test` or `prod`, defaults to `dev`)
   126  - `dbdebug` (`true` or `false`, defaults to `false`)
   127  
   128  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.
   129  
   130  The PSN connection strings for dev and test are in conf.local.yaml, but for prod this is built from environement variables:
   131  
   132  -	`POSTGRES_NAME` (DB name)
   133  - `POSTGRES_USER` (DB username)
   134  - `POSTGRES_PASS` (DB password)
   135  - `POSTGRES_HOST` (DB host, defaulted `127.0.0.1`)
   136  - `POSTGRES_PORT` (DB port, defaulted `5432`)
   137  - `POSTGRES_SSL` (`enable` or defaulted `disable`)
   138  
   139  ## Docker!
   140  
   141  Build a container with `docker build -t resonateuserapi .`
   142  
   143  (to avoid cache, use `--no-cache` option)
   144  
   145  Run container with `docker run -p 11000:11000 --network=host -tid resonateuserapi`
   146  
   147  Check status with `docker container ls` and `docker logs <image>`
   148  
   149  (use sudo as required)
   150  
   151  ## Working with a reverse-proxy (like nginx)
   152  
   153  You need to register a certificate in a pair of files.
   154  
   155  This prefix of this file is held in the config file as `cert_name`, default value `uaclient`
   156  
   157  The server will then look for two files, suffix's ".pem" and ".key" in the directory provided by 
   158  the environment variable `UACERT_DIR`
   159  
   160  In your reverse proxy you will need to refer to these too in order to be able to proxy the service securely.
   161  
   162  ## Maintenance
   163  
   164  Interfaces are designed in
   165  `proto/` directory. See https://developers.google.com/protocol-buffers/
   166  tutorials and guides on writing protofiles.
   167  
   168  Once that is done, regenerate the files using
   169  `make generate`. This will mean you'll need to implement any functions in
   170  `server/`, or else the build will fail since your struct won't
   171  be implementing the interface defined by the generated file in `proto/example.pb.go`.