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`.