Skip to content

Commit

Permalink
Doc review
Browse files Browse the repository at this point in the history
  • Loading branch information
dr-jts committed Feb 27, 2020
1 parent 3fa42c2 commit 9ae77d0
Show file tree
Hide file tree
Showing 13 changed files with 56 additions and 35 deletions.
4 changes: 2 additions & 2 deletions hugo/content/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
4 changes: 3 additions & 1 deletion hugo/content/examples/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 4 additions & 0 deletions hugo/content/installation/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
10 changes: 5 additions & 5 deletions hugo/content/installation/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|-------------|-----------|
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions hugo/content/introduction/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion hugo/content/introduction/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
8 changes: 4 additions & 4 deletions hugo/content/introduction/definitions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
18 changes: 10 additions & 8 deletions hugo/content/learn-more/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
2 changes: 1 addition & 1 deletion hugo/content/usage/api.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "API"
date:
draft: false
draft: true
weight: 50
---

Expand Down
6 changes: 3 additions & 3 deletions hugo/content/usage/functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,16 @@ draft: false
weight: 200
---

## Expose Database Functions


<!-- ## Expose Database Functions -->

## List Functions

`/functions`

`/functions.json`

## Describe Function metadata

`/functions/{funid}`

`/functions/{funid}.json`
1 change: 1 addition & 0 deletions hugo/content/usage/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
```
Expand Down
10 changes: 5 additions & 5 deletions hugo/content/usage/ui.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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.
Expand Down

0 comments on commit 9ae77d0

Please sign in to comment.