thallada/BazaarRealmAPI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Better readme instructions for docker and tls

Browse Source
This commit is contained in:
Tyler Hallada 2020-11-12 21:01:29 -05:00
parent 9949c537a0
commit a1107b7100
1 changed files with 70 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
README.md
View File

@ -16,16 +16,31 @@ are (all prefixed under `/v1`, the API version):
- `/merchandise_lists`: Lists of in-game Forms that are in the merchant chest
of individual shops. When a user visits a shop, these forms are loaded
onto the shop's shelves and are purchasable.
- `/transactions`: Allows posting a new buy or sell between an owner and a
shop's merchandise.
Bazaar Realm was designed to allow users to change the API they are using the
mod under, if they wish. The API can run on a small server with minimal
resources, which should be suitable for a small group of friends to share
shops with each other.
resources, which should be suitable for a group of friends to share shops
with each other.
It uses the [`warp`](https://crates.io/crates/warp) web server framework and
[`sqlx`](https://crates.io/crates/sqlx) for database queries to a [PostgreSQL
database](https://www.postgresql.org).
The API was designed with performance as a high priority. When it serves a
response, it also caches that response so future queries for the same data
can be returned in less than 1ms. To reduce data sent over the network,
clients can use the
[ETag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)
headers to indicate to the server what version of the data they have cached
so the server can send a 304 response with no data if the resource hasn't
changed since the client last requested. Using the
[Accept](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept)
header, clients can also opt for the more space-efficient and faster to
deserialize [bincode](https://github.com/servo/bincode) format instead of the
JSON default.
Related projects:
- [`BazaarRealmClient`](https://github.com/thallada/BazaarRealmClient): DLL that
@ -41,31 +56,27 @@ Related projects:
The easiest way to get the server up and running is using Docker.
1. Download and install [Docker Desktop](https://www.docker.com/get-started)
2. Run `docker pull postgres:alpine` then `docker pull thallada/bazaarrealm:latest`
3. Run `docker run -d --name postgres --network=host --env POSTGRES_DB=bazaarrealm --env POSTGRES_USER=bazaarrealm --env POSTGRES_PASSWORD=<password>`
(replacing `<password>` with a secure generated password)
4. Run `docker run -d --name bazaarrealm --network=host --env DATABASE_URL=postgresql://bazaarrealm:<password>@localhost/bazaarrealm`
(replacing `<password>` with what you generated in previous step)
2. In PowerShell, cmd.exe, or a terminal run `docker pull postgres:alpine` then `docker pull thallada/bazaarrealm:latest`
3. Run (replacing `<password>` with a secure generated password):
```
docker run -d --name postgres --network=bazaarrealm --network-alias=db --env POSTGRES_DB=bazaarrealm --env POSTGRES_USER=bazaarrealm --env POSTGRES_PASSWORD=<password> postgres:alpine
```
4. Run (replacing `<password>` with what you generated in previous step):
```
docker run -d --name bazaarrealm -p 3030:3030 --network=bazaarrealm --network-alias=api --env DATABASE_URL=postgresql://bazaarrealm:<password>@db/bazaarrealm --env HOST=http://localhost:3030 thallada/bazaarrealm:latest
```
5. The server should now be available at `http://localhost:3030`.
### TLS setup
If you would like to access the server over HTTPS, you can use [Let's
Encrypt](https://letsencrypt.org/) to generate a SSL certificate and key and
provide it to the API. Once you use [certbot](https://certbot.eff.org/) to
generate the certificate and key for your domain in
`/etc/letsencrypt/live/<domain>/`, run the api server with:
```
docker run -d --name bazaarrealm --network=host --env DATABASE_URL=postgresql://bazaarrealm:<password>@localhost/bazaarrealm --env PORT=443 --HOST=https://<domain> --env TLS_CERT=/etc/letsencrypt/live/<domain>/fullchain.pem --env TLS_KEY=/etc/letsencrypt/live/<domain>/privkey.pem -v /etc/letsencrypt/:/etc/letsencrypt/ thallada/bazaarrealm:latest
```
The server should be accessible at your domain: `https://<domain>`.
## Docker-Compose Setup
An alternative way to set up the API, is to use `docker-compose` which can
orchestrate setting up the database and web server containers.
orchestrate setting up the database and web server containers for you. This
method is more useful if you would like to make changes to the API code and
test them out.
1. Download and install [Docker Desktop](https://www.docker.com/get-started)
2. Git clone this repo into a folder of your choosing: `git clone https://github.com/thallada/BazaarRealmAPI.git`
@ -130,7 +141,27 @@ PORT=3030
6. Run `sqlx migrate run` which will run all the database migrations.
7. `cd ..` to return to the top-level directory of this repo.
8. Run `./devserver.sh` to run the dev server (by default it listens at
`127.0.0.1:3030`).
`127.0.0.1:3030`). Note that this runs the server in debug mode and shouldn't
be used to serve requests from the mod. You can build the release version of
the server with `cargo build --release`.
## TLS setup
If you would like to access the server over HTTPS, you can use [Let's
Encrypt](https://letsencrypt.org/) to generate a SSL certificate and key and
provide it to the API. Once you use [certbot](https://certbot.eff.org/) to
generate the certificate and key for your domain in
`/etc/letsencrypt/live/<domain>/`, run the api server with:
```
docker run -d --name bazaarrealm --network=host --env DATABASE_URL=postgresql://bazaarrealm:<password>@localhost/bazaarrealm --env PORT=443 --HOST=https://<domain> --env TLS_CERT=/etc/letsencrypt/live/<domain>/fullchain.pem --env TLS_KEY=/etc/letsencrypt/live/<domain>/privkey.pem -v /etc/letsencrypt/:/etc/letsencrypt/ thallada/bazaarrealm:latest
```
This command assumes that you are on Linux and you have a running postgres
database already set up outside of docker. See Manual Development Setup for
database setup instructions.
The server should be accessible at your domain: `https://<domain>`.
## Testing Data
@ -153,6 +184,19 @@ http GET "http://localhost:3030/v1/interior_ref_lists"
http GET "http://localhost:3030/v1/merchandise_lists"
```
## Database Migrations
Migrations are handled by `sqlx`. When the server initially starts, it will
connect to the database and check if there are any migrations in
`db/migrations` that have not yet been applied. It will apply any at that
time and then continue starting the server.
A new migration can be created by running: `sqlx migrate add <name>`.
To allow the docker container for the API to get built in CI without a
database, the `sqlx-data.json` file needs to be re-generated every time the
database schema changes. It can be generated with `cargo sqlx prepare`.
## Authentication
I don't want to require users of Bazaar Realm to have to remember a password,
@ -162,14 +206,6 @@ unique UUID identifier instead. This is the api key that the
The api key is stored in the save game files for the player character and is
required to be sent with any API request that modifies data.
Yes, it's not most secure solution, but I'm not convinced security is a huge
concern here. As long as users don't share their API key or the save game
files that contain it, their data should be secure.
## Todo
- Add update endpoints.
- Add endpoints for the other models.
- Make self-contained docker container that can run the app without any setup.
- Add rate-limiting per IP address. The `tower` crate has a service that might
be useful for this.
Yes, it's not the most secure solution, but I'm not convinced security is a
huge concern here. As long as users don't share their API key or the save
game files that contain it, their data should be secure.