diff --git a/docs/install/server.md b/docs/install/server.md index 7dff82727..87d3e5d80 100644 --- a/docs/install/server.md +++ b/docs/install/server.md @@ -2,7 +2,10 @@ ### Installing from Pre-Built Release -The [release page](https://github.com/begriffs/postgrest/releases/latest) has precompiled binaries for Mac OS X and 64-bit Ubuntu. Next extract the tarball and run the binary inside with no arguments to see usage instructions: +The [release page](https://github.com/begriffs/postgrest/releases/latest) +has precompiled binaries for Mac OS X, Windows, and several Linux +distros. Extract the tarball and run the binary inside with no +arguments to see usage instructions: ```sh # Untar the release (available at https://github.com/begriffs/postgrest/releases/latest) @@ -18,22 +21,21 @@ $ ./postgrest

Invitation to Contribute

-

I currently build the binaries manually for each version. We need to set up an automated build matrix for various architectures. It should support 32- and 64-bit versions of +

I currently build the binaries manually for each architecture. + It would be nice to set up an automated build matrix for various + architectures. It should support Mac, Windows and 32- and 64-bit + versions of -

- - Also it would be good to create a package for apt.

+

-We'll learn the meaning of the command line flags later, but here is a minimal example of running the app. It does all operations as user `postgres`, including for unauthenticated requests. - -```sh -$ ./postgrest -d dbname -U postgres -a postgres --v1schema public -``` - ### Building from Source -When a prebuilt binary does not exist for your system you can build the project from source. You'll also need to do this if you want to help with development. [Stack](https://github.com/commercialhaskell/stack) makes it easy. It will install any necessary Haskell dependencies on your system. +When a prebuilt binary does not exist for your system you can build +the project from source. You'll also need to do this if you want +to help with development. +[Stack](https://github.com/commercialhaskell/stack) makes it easy. +It will install any necessary Haskell dependencies on your system. * [Install Stack](https://github.com/commercialhaskell/stack#how-to-install) for your platform ```bash @@ -52,11 +54,58 @@ sudo stack install --install-ghc --local-bin-path /usr/local/bin * Run the server +If you want to run the test suite, stack can do that too: `stack test`. + +### Running the Server + ```bash -postgrest dbconnectionstring arg1 arg2 +postgrest postgres://user:pass@host:port/db [flags] ``` -If you want to run the test suite, stack can do that too: `stack test`. +The user in the connection string is the "authenticator role," i.e. +a role which is used temporarily to switch into other roles depending +on the authentication request JWT. For simple API's you can use the +same role for authenticator and anonymous. + +The possible flags are: + +
+
-p, --port
+
The port on which the server will listen for HTTP requests. + Defaults to 3000.
+ +
-a, --anonymous
+
The database role used to execute commands for those requests + which provide no JWT authorization.
+ +
-s, --schema
+
The db schema which you want to expose as an API. For historical + reasons it defaults to 1, but you're more likely + to want to choose a value of public.
+ +
-j, --jwt-secret
+
The secret passphrase used to encrypt JWT tokens. Defaults to + secret but do not use the default in production! + Load-balanced PostgREST servers should share the same secret.
+ +
-p, --pool
+
Max connections to use in db pool. Defaults to to 10, but you + should find an optimal value for your db by running the SQL + command show max_connections;
+
+ +
+

Hiding Password from Process List

+ +

Passing the database password and JWT secret as naked + parameters might not be a good idea because the parameters are + visible in a ps listing. One solution is to set + environment variables such as PASS and use $PASS + in the connection string. Another is to use a user-specific + .pgpass + file.

+
### Installing PostgreSQL @@ -64,3 +113,4 @@ To use PostgREST you will need an underlying database. You can use something lik * [Instructions for OS X](http://exponential.io/blog/2015/02/21/install-postgresql-on-mac-os-x-via-brew/) * [Instructions for Ubuntu 14.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-postgresql-on-ubuntu-14-04) +* [Installer for Windows](http://www.enterprisedb.com/products-services-training/pgdownload#windows)