riposo

README

Riposo Server

Riposo is a JSON document store written in Go, based on the design of Kinto. It implements v1.22 of the Kinto API and aims to be fully compatible with the client libraries kinto-http.js, kinto-http.py as well as higher-level, offline-first abstraction kinto.js.

Getting Started

The easiest way to deploy Riposo is via Docker.

To launch a test instance (on port 8888):

docker run --rm -p 8888:8888 riposo/riposo server

You can use environment variables to configure all aspects of your instance, including persistence. For more information, please see the Configuration section.

docker run --rm \
    -e RIPOSO_STORAGE_URL=postgres://postgres:postgres@database/riposo?timezone=UTC \
    -e RIPOSO_PERMISSION_URL=postgres://postgres:postgres@database/riposo?timezone=UTC \
    -e RIPOSO_CACHE_URL=postgres://postgres:postgres@database/riposo?timezone=UTC \
    riposo/riposo:0.1.0 server

Plugins can also be loaded dynamically by referencing the plugin ID. In order to enable a plugin, the server binary must have been built with it. For more information, please see the Plugins section.

# list plugins
docker run --rm riposo/riposo plugins

# run server with plugins
docker run --rm \
    -v $(pwd):/data
    -e RIPOSO_PLUGINS=accounts,default-bucket \
    -e RIPOSO_BUCKET_CREATE_PRINCIPALS=system.Authenticated \
    -e RIPOSO_ACCOUNT_CREATE_PRINCIPALS=system.Everyone \
    riposo/riposo server

Configuration

The following environment variable can be used to configure your server instance:

Variable	Description	Default
RIPOSO_PROJECT_NAME	Project name, as reported by GET /v1/	riposo
RIPOSO_PROJECT_VERSION	Project version, as reported by GET /v1/	none
RIPOSO_PROJECT_DOCS	Project documentation URL	https://github.com/riposo/riposo/
RIPOSO_ID_FACTORY	ID generator, see ID Factories	nanoid
RIPOSO_STORAGE_URL	Storage backend URL, see Data Backends	:memory:
RIPOSO_PERMISSION_URL	Permission backend URL	:memory:
RIPOSO_CACHE_URL	Cache backend URL	:memory:
RIPOSO_BATCH_MAX_REQUESTS	Maximum permitted number of requests per batch	25
RIPOSO_AUTH_METHODS	Comma-separated list of auth methods, see Authentication	basic
RIPOSO_AUTH_HASH	Hash method used for password hashing, argon2id or bcrypt	argon2id
RIPOSO_CORS_ORIGINS	Permitted CORS origins	*
RIPOSO_CORS_MAX_AGE	Indicates how long the results of a preflight CORS request can be cached	1h
RIPOSO_PAGINATION_TOKEN_VALIDITY	Pagination token TTL	10m
RIPOSO_PAGINATION_MAX_LIMIT	Maximum number of records that can be requested per page	10000
RIPOSO_SERVER_ADDR	Server address to listen for requests	:8888
RIPOSO_SERVER_READ_TIMEOUT	Read timeout for server requests	60s
RIPOSO_SERVER_WRITE_TIMEOUT	Write timeout for server responses	60s
RIPOSO_SERVER_SHUTDOWN_TIMEOUT	Grace time to wait for active connections to close before shutdown	5s
RIPOSO_PLUGINS	Comma-separated list of plugins to enable, see Plugins	none
RIPOSO_TEMP_DIR	Directory path for storing temporary files	none (= the OS temp dir)
RIPOSO_EOS_TIME	End-of-service timestamp	none
RIPOSO_EOS_MESSAGE	End-of-service message	none
RIPOSO_EOS_URL	End-of-service details URL	none

Additionally, you can use extra variables to grant permissions globally. These will take precedence over those stored permanently in the permission backend. The format of these special variables is RIPOSO_<permission>_PRINCIPALS=comma,separated,principals. Examples:

# Allow authenticated users to create buckets
RIPOSO_BUCKET_CREATE_PRINCIPALS=system.Authenticated

# Allow all users to create new accounts
RIPOSO_ACCOUNT_CREATE_PRINCIPALS=system.Everyone

# Allow admin user to read all buckets
RIPOSO_BUCKET_READ_PRINCIPALS=account:admin

# Grant admin user full access
RIPOSO_WRITE_PRINCIPALS=account:admin

ID Factories

ID factories are used to generate random, non-colliding, human-readable IDs for records in the system. The two built-in methods are:

• nanoid - tiny, secure, URL-friendly, unique, see Nano ID
• uuid - v4 of the universally unique identifier, see Wikipedia

Data Backends

Backends can be configured through URLs By default, your server comes with support for two data backends:

• :memory: - purely in-memory, only use this for testing
• postgres:// - PostgreSQL support, use this for production

Additional backends are available as plugins.

Authentication

Authentication methods are available as plugins. By default only basic auth is supported but additional methods are available as plugins.

Plugins

Plugins can be loaded at runtime by referencing them via RIPOSO_PLUGINS environment variable. To see a list of bundled plugins, please run riposo plugins. By default, the following plugins are available:

• accounts
• default-bucket
• flush

To build a custom release with additional plugins, please see instructions on the cmd page. More plugins are available on GitHub.

License

Copyright 2021 Black Square Media Ltd

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this material except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.