diff --git a/hugo/content/_index.md b/hugo/content/_index.md index 6089fbb7..e7ffee67 100644 --- a/hugo/content/_index.md +++ b/hugo/content/_index.md @@ -13,5 +13,5 @@ The service API follows the [OGC API for Features Version 1.0](http://docs.openg It extends the API to expose more of the powerful spatial capabilities of PostGIS. This guide walks you through how to install and use `pg_featureserv` for your spatial applications. -The [Usage](./usage) section goes in-depth on how the service works. -It also includes some [basic examples](./examples) of web map applications that source feature data from `pg_featureserv`. +The [Usage](/usage/) section goes in-depth on how the service works. +We'll soon be adding more [basic examples](/examples/) of web map applications that source feature data from `pg_featureserv`. diff --git a/hugo/content/examples/_index.md b/hugo/content/examples/_index.md index 27a159c5..c27b0851 100644 --- a/hugo/content/examples/_index.md +++ b/hugo/content/examples/_index.md @@ -5,4 +5,6 @@ draft: false weight: 40 --- -This section provides examples of using `pg_featureserv`. +We're currently working on adding examples of using `pg_featureserv` in this guide. + +In the meantime, we'd encourage you to check this [Github repository](https://github.com/pramsey/examples-pgsql-full-text) for a heat map demo and an address autocomplete demo. diff --git a/hugo/content/installation/_index.md b/hugo/content/installation/_index.md index bfe86124..62329a75 100644 --- a/hugo/content/installation/_index.md +++ b/hugo/content/installation/_index.md @@ -11,3 +11,7 @@ This section describes how to obtain, install and run `pg_featureserv`. * **PostgreSQL 9.5** or later * **PostGIS 2.4** or later + +You don't need advanced knowledge in Postgres/PostGIS or web mapping to install and deploy `pg_featureserv`. If you are new to functions in Postgres, you might try this [quick interactive course](https://learn.crunchydata.com/postgresql-devel/courses/beyond-basics/basicfunctions/) to better see how you might take advantage of `pg_featureserv`'s capabilities. + +We also link to [further resources](/learn-more/) at the end of this guide, for your reference. diff --git a/hugo/content/installation/deployment.md b/hugo/content/installation/deployment.md index c4ac8396..8a24acda 100644 --- a/hugo/content/installation/deployment.md +++ b/hugo/content/installation/deployment.md @@ -5,28 +5,28 @@ draft: false weight: 300 --- -### Basic Operation +## Basic Operation The service can be run with minimal configuration. Only the database connection information is required. (Even that can be omitted if run with the `--test` option.) The database connection information can be provided in an environment variable -`DATABASE_URL` containing a Postgres [connection string](https://www.postgresql.org/docs/12/libpq-connect.html#LIBPQ-CONNSTRING) +`DATABASE_URL` containing a Postgres [connection string](https://www.postgresql.org/docs/12/libpq-connect.html#LIBPQ-CONNSTRING). -#### Linux or OSX +### Linux or OSX ```sh export DATABASE_URL=postgresql://username:password@host/dbname ./pg_featureserv ``` -#### Windows +### Windows ``` SET DATABASE_URL=postgresql://username:password@host/dbname pg_featureserv.exe ``` -### Command options +## Command options | Option | Description | |-------------|-----------| diff --git a/hugo/content/installation/installation.md b/hugo/content/installation/installing.md similarity index 70% rename from hugo/content/installation/installation.md rename to hugo/content/installation/installing.md index f259134e..bb42d9c7 100644 --- a/hugo/content/installation/installation.md +++ b/hugo/content/installation/installing.md @@ -7,9 +7,9 @@ weight: 200 ## Installation -To install `pg_featureserv`, download the binary file. Alternatively, you may build the executable from source. +To install `pg_featureserv`, download the binary file. Alternatively, you may run a container. These first two options will suit most use cases; needing to build the executable from source is rare. -### A. Download Binaries +### A. Download binaries Builds of the latest code: @@ -19,7 +19,19 @@ Builds of the latest code: Unzip the file, copy the `pg_featureserv` binary wherever you wish, or use it in place. If you move the binary, remember to move the `assets/` directory to the same location, or start the server using the `AssetsDir` configuration option. -### B. Build From Source +### B. Run container + +A Docker image is available on DockerHub: + +* [Docker](https://hub.docker.com/r/pramsey/pg_featureserv/) + +When you run the container, provide the database connection information in the `DATABASE_URL` environment variable and map the default service port (9000). + +```sh +docker run -e DATABASE_URL=postgres://user:pass@host/dbname -p 9000:9000 pramsey/pg_featureserv +``` + +### C. Build from source If not already installed, install the [Go software development environment](https://golang.org/doc/install). Make sure that the [`GOPATH` environment variable](https://github.com/golang/go/wiki/SettingGOPATH) is also set. diff --git a/hugo/content/introduction/_index.md b/hugo/content/introduction/_index.md index 4003dc9d..7db9a465 100644 --- a/hugo/content/introduction/_index.md +++ b/hugo/content/introduction/_index.md @@ -44,7 +44,7 @@ By focussing on the single aspect of serving spatial features, `pg_featureserv` `pg_featureserv` is one component of **PostGIS for the Web** (aka "PostGIS FTW"), a growing family of spatial micro-services. Database-centric applications naturally have a central source of coordinating state, the database, which allows otherwise independent microservices to provide HTTP-level access to the database with minimal middleware complexity. -* [pg_tileserv](https:access.crunchydata.com/documentation/pg_featureserv/latest/) provides MVT tiles for interactive clients and smooth rendering -* [pg_featureserv](.) provides GeoJSON feature services for reading and writing vector and attribute data from tables +* [pg_tileserv](https:access.crunchydata.com/documentation/pg_tileserv/latest/) provides MVT tiles for interactive clients and smooth rendering +* [pg_featureserv](/) provides GeoJSON feature services for reading and writing vector and attribute data from tables _PostGIS for the Web_ makes it possible to stand up a spatial services architecture of stateless microservices surrounding a PostgreSQL/PostGIS database cluster, in a standard container environment, on any cloud platform or internal datacenter. diff --git a/hugo/content/introduction/architecture.md b/hugo/content/introduction/architecture.md index 93c3e5b3..cb104b2e 100644 --- a/hugo/content/introduction/architecture.md +++ b/hugo/content/introduction/architecture.md @@ -28,4 +28,4 @@ to a desktop GIS application such as `QGIS`), or a web proxy mediating access to The context diagram below shows `pg_featureserv` running alongside `pg_tileserv` to provide a PostGIS-centric "platform for the spatial web". -![pg_feaureserv Architecture](../../static/pg_fs_architecture.png) +![pg_feaureserv Architecture](/pg_fs_architecture.png) diff --git a/hugo/content/introduction/definitions.md b/hugo/content/introduction/definitions.md index 9bd135ec..315c4c0f 100644 --- a/hugo/content/introduction/definitions.md +++ b/hugo/content/introduction/definitions.md @@ -17,9 +17,9 @@ A database that includes a "geometry" column type. The PostGIS extension to Post ### Web API An Application Program Interface (API) allows client software to make programmatic requests to a service and retrieve information from it. -A Web API is an API which is founded on the technologies of the Web. +A Web API is an API founded on Web technologies. These include: -* use of the HTTP protocol to provide high-level semantics for operations, as well as efficient mechanisms for querying, security and transporting data to clients -* following the REST paradigm to simplify the model of interacting with data -* using the standard JSON and GeoJSON formats as the primary way of encoding data +* Use of the HTTP protocol to provide high-level semantics for operations, as well as efficient mechanisms for querying, security and transporting data to clients +* Following the REST paradigm to simplify the model of interacting with data +* Using the standard JSON and GeoJSON formats as the primary way of encoding data diff --git a/hugo/content/learn-more/_index.md b/hugo/content/learn-more/_index.md index 806b5ebd..658eaa1f 100644 --- a/hugo/content/learn-more/_index.md +++ b/hugo/content/learn-more/_index.md @@ -5,11 +5,13 @@ draft: false weight: 60 --- -# Where to Learn More (or Next Steps) - -- Point to the reference documentation. -- Point to the relevant parts of the community documentation. -- Mention our award winning support. -- Point to Katacoda scenarios, if available. -- Point to a relevant blog post, if it exists. -- Try not to repeat the exact same links provided in earlier sections (e.g. Definitions). +## GIS + +- QGIS is a free and open source application for editing, visualizing, and analyzing spatial data. Get started with the [QGIS Training Manual](https://docs.qgis.org/3.4/en/docs/training_manual/index.html). +- The [Introduction to PostGIS Workshop](https://postgis.net/workshops/postgis-intro) is a full tutorial on the PostGIS extension. +- Shorter interactive courses on PostGIS are also available on the Crunchy Data [Learning Platform](https://learn.crunchydata.com/postgis). +- Learn more about practical applications of PostGIS with [PostGIS Day 2019 Talks](https://info.crunchydata.com/stl-postgis-day-2019-presentations). + +## Source Code + +- [GitHub](https://github.com/crunchydata/pg_featureserv/) diff --git a/hugo/content/usage/api.md b/hugo/content/usage/api.md index 616e6dbd..95411b50 100644 --- a/hugo/content/usage/api.md +++ b/hugo/content/usage/api.md @@ -1,7 +1,7 @@ --- title: "API" date: -draft: false +draft: true weight: 50 --- diff --git a/hugo/content/usage/functions.md b/hugo/content/usage/functions.md index 8bf052db..5e34e78f 100644 --- a/hugo/content/usage/functions.md +++ b/hugo/content/usage/functions.md @@ -5,16 +5,16 @@ draft: false weight: 200 --- -## Expose Database Functions - - + ## List Functions `/functions` + `/functions.json` ## Describe Function metadata `/functions/{funid}` + `/functions/{funid}.json` diff --git a/hugo/content/usage/security.md b/hugo/content/usage/security.md index c2e87581..3df2d75b 100644 --- a/hugo/content/usage/security.md +++ b/hugo/content/usage/security.md @@ -10,6 +10,7 @@ The basic principle of security is to connect the server to the database with a Start with a new, blank user. A blank user has no select privileges on tables it does not own. It does have execute privileges on functions. However, the user has no select privileges on tables accessed by functions, so effectively the user will still have no access to data. + ```sql CREATE USER featureserver; ``` diff --git a/hugo/content/usage/ui.md b/hugo/content/usage/ui.md index 239766da..6594e4b3 100644 --- a/hugo/content/usage/ui.md +++ b/hugo/content/usage/ui.md @@ -5,14 +5,14 @@ draft: false weight: 500 --- -## Home page +## Home Page The home page shows the service title and description, and provides links to the listings of collections and functions, the OpenAPI definition, and the conformance metadata. ``` -http://localhosst:9000/home.html +http://localhost:9000/home.html ``` ## API User Interface @@ -23,7 +23,7 @@ A user interface for the service API is available at the path `/api.html`. The path `/collections.html` shows a list of the feature collections exposed by the service. -## Show Feature Collection metadata +## Show Feature Collection Metadata The path `/collections/{collid}.html` shows metadata about the specified feature collection. @@ -44,11 +44,11 @@ Any applicable query parameters may be appended to the URL. The path `/functions.html` shows a list of the functions exposed by the service. -## Show function metadata +## Show Function Metadata The path `/functions/{funid}.html` shows metadata about the specified function. -## View function result data on a map +## View Function Result Data on a Map The path `/functions/{funid}/items.html` shows the features returned by a basic function query in a web map interface.