Server Configuration
The prestd configuration is via an environment variable or toml file.
Environment variables
var | default | description |
---|---|---|
PREST_CONF | ./prest.conf | |
PREST_MIGRATIONS | ./migrations | |
PREST_QUERIES_LOCATION | ./queries | |
PREST_HTTP_HOST | 0.0.0.0 | |
PREST_HTTP_PORT or PORT | 3000 | PORT is cloud factor, _when declaring this variable overwritten PREST_HTTP_PORT |
PREST_PG_HOST | 127.0.0.1 | |
PREST_PG_USER | ||
PREST_PG_PASS | ||
PREST_PG_DATABASE | ||
PREST_PG_PORT | 5432 | |
PREST_PG_URL or DATABASE_URL | cloud factor, when declaring this variable all the previous connection fields are overwritten | |
PREST_CACHE_ENABLED | false | embedded cache system |
PREST_CACHE_TIME | 10 | TTL in minute (time to live) |
PREST_CACHE_STORAGEPATH | ./ | path where the cache file will be created |
PREST_CACHE_SUFIXFILE | .cache.prestd.db | suffix of the name of the file that is created |
PREST_JWT_KEY | ||
PREST_JWT_ALGO | HS256 | |
PREST_JWT_WHITELIST | [/auth] | |
PREST_AUTH_ENABLED | false | |
PREST_AUTH_ENCRYPT | MD5 | |
PREST_AUTH_TYPE | body | |
PREST_AUTH_SCHEMA | public | |
PREST_AUTH_TABLE | prest_users | |
PREST_AUTH_USERNAME | username | |
PREST_AUTH_PASSWORD | password | |
PREST_SSL_MODE | require | |
PREST_SSL_CERT | ||
PREST_SSL_KEY | ||
PREST_SSL_ROOTCERT | ||
PREST_PLUGINPATH | ./lib | path to plugin storage .so |
TOML
Optionally the prestd can be configured by TOML file.
You can follow this sample and create your own prest.toml
file and put this on the same folder that you run prestd
command.
1migrations = "./migrations"
2
3# debug = true
4# enabling debug mode will disable JWT authorization
5
6[http]
7port = 3000
8
9[jwt]
10key = "secret"
11algo = "HS256"
12
13[auth]
14enabled = true
15type = "body"
16encrypt = "MD5"
17table = "prest_users"
18username = "username"
19password = "password"
20
21[pg]
22host = "127.0.0.1"
23user = "postgres"
24pass = "mypass"
25port = 5432
26database = "prest"
27single = true
28## or used cloud factor
29# URL = "postgresql://user:pass@localhost/mydatabase/?sslmode=disable"
30
31[ssl]
32mode = "disable"
33sslcert = "./PATH"
34sslkey = "./PATH"
35sslrootcert = "./PATH"
Authorization
JWT
JWT middleware is enabled by default. To disable JWT need to set default to false. Enabling debug mode will also disable it.
1[jwt]
2default = false
1Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
The HS256
algorithm is used by default.
The JWT algorithm can be specified by using either the environment variable PREST_JWT_ALGO
or the algo
parameter in the section [jwt]
of the prest.toml
configuration file.
The supported signing algorithms are:
- The HMAC signing method:
HS256
,HS384
,HS512
- The RSA signing method:
RS256
,RS384
,RS512
- The ECDSA signing method:
ES256
,ES384
,ES512
White list
By default the endpoints /auth
do not require JWT, the whitelist option serves to configure which endpoints will not ask for jwt token
1[jwt]
2default = true
3whitelist = ["\/auth", "\/ping", "\/ping\/.*"]
Auth
pREST has support in jwt token generation based on two fields (example user and password), being possible to use an existing table from your database to login configuring some parameters in the configuration file (or environment variable), by default this feature is disabled.
1[auth]
2enabled = true
3type = "body"
4encrypt = "MD5"
5table = "prest_users"
6username = "username"
7password = "password"
Name | Description |
---|---|
enabled | Boolean field that activates or deactivates token generation endpoint support |
type | Type that will receive the login, support for body and http basic authentication |
encrypt | Type of encryption used in password field, support for MD5 and SHA1 |
table | Table name we will consult (query) |
username | User field that will be consulted - if your software uses email just abstract name username (at pREST code level it was necessary to define an internal standard) |
password | Password field that will be consulted |
to validate all endpoints with generated jwt token must be activated jwt option
SSL
There is 4 options to set on ssl mode:
require
- Always SSL (skip verification) by defaultdisable
- SSL offverify-ca
- Always SSL (verify that the certificate presented by the server was signed by a trusted CA)verify-full
- Always SSL (verify that the certification presented by the server was signed by a trusted CA and the server host name matches the one in the certificate)
Debug Mode
Set environment variable PREST_DEBUG
or debug=true
on top of prest.toml file.
1PREST_DEBUG=true
Single mode
While serving multiple databases over the same API with pREST is doable, it's by default a single database setup. This is this way to prevent unwanted behavior that may make prest instable for users, in order to change that It's possible to pass a variable on your toml
file to disable it under the [pg]
tag as shown bellow.
1[pg]
2 single = false
CORS support
Cross-Origin Resource Sharing
Read the specific topic where we talk about CROS here.