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