-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updated documentation to point to oada/server.
- Loading branch information
Showing
1 changed file
with
24 additions
and
109 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -29,39 +29,25 @@ you may find it helpful to familiarize yourself with docker and docker-compose. | |
|
|
||
| ## Getting Started | ||
| -------------------------------------- | ||
| The best way to get familiar with the OADA API is to use it. Do this: | ||
| The best way to get familiar with the OADA API is to use it. Latest instructions for installing and running the reference OADA implementation can be found at https://github.com/oada/server. This will get you setup with a locally running instance of OADA and a token you can use to make API requests. | ||
|
|
||
| 1. Install the OADA server code: | ||
| ```git clone [email protected]:OADA/oada-srvc-docker.git``` | ||
|
|
||
| 2. Install the OADA helper script and get bash completion for services: | ||
| ```bash | ||
| cd oada-srvc-docker | ||
| oada --install-self | ||
| ``` | ||
|
|
||
| 2. Bring up the server (it runs on localhost at port 80 and 443). Include a set of dummy users and tokens | ||
| to simplify getting started (don't worry, these are easily removed later by simply omiting the `--dev` flag): | ||
| ``` | ||
| oada --dev up -d | ||
| ``` | ||
| Note that the "up -d" part is passed to docker compose, just like `docker-compose up -d`. | ||
|
|
||
| 3. Learn about your server and make sure it's up. Open a browser and go to | ||
| 1. Learn about your server and make sure it's up. Open a browser and go to | ||
| [https://localhost/.well-known/oada-configuration](https://localhost/.well-known/oada-configuration). | ||
| Look for `oada_base_uri` (where the data is), and | ||
| `authorization_endpoint` (where to ask for a token). | ||
| *IMPORTANT NOTE*: the local SSL certificate is self-signed. You have to manually approve it in your browser. | ||
| *IMPORTANT NOTE*: if you did not use `mkcert` to setup your SSL certificate, then your browser will not trust it. | ||
| You will have to manually approve it in your browser to see the configuration page. | ||
|
|
||
| 4. Get an API tool like [Insomnia](https://insomnia.rest/) or [Postman](https://www.postman.com/) | ||
| 2. Get an API tool like [Insomnia](https://insomnia.rest/) or [Postman](https://www.postman.com/) | ||
|
|
||
| 5. Discover what data is on your server for a token. In Insomnia, | ||
| 5. Discover what data is on your server for your token. In Insomnia, | ||
| do a `GET` to `https://localhost/bookmarks`. Without an `Authorization:` header | ||
| it will fail. Add it using one of the dummy tokens (`def`) created with the `--dev` flag earlier: | ||
| it will fail. Add it the token you created when you setup your instance: | ||
| ``` | ||
| Authorization: Bearer def | ||
| Authorization: Bearer the_token | ||
| ``` | ||
| Now you should get back some JSON listing the data that's available. | ||
| Now you should get back some JSON listing the data that's available, which in this case is likely just an | ||
| empty JSON object if you just setup your server. | ||
|
|
||
| 6. Add some data to your server. In Insomnia, with the same `Authorization:` header, | ||
| do a `PUT` to `https://localhost/bookmarks/theknights` with the body: | ||
|
|
@@ -124,110 +110,39 @@ Read up on the [Rest API Spec](rest-specs/README.md) with examples to learn how | |
| create resources, link them between documents, track changes, add services or | ||
| custom modules, and more. | ||
|
|
||
| ### Create Users | ||
|
|
||
| There is a script in the admin container for adding users. If a user is an admin user, | ||
| they can also add users via the `/users` part of the OADA API. | ||
|
|
||
| To add an admin user: | ||
| ```bash | ||
| $ oada run --rm admin ./useradd -a | ||
| Username: <username> | ||
| Password: <password> | ||
| Domain: <domain for this user> | ||
| ``` | ||
| Once the initial admin user is made, they can hand out tokens with permission to create users via the API: | ||
| ```http | ||
| POST /users | ||
| { "username": "username", "password": "password" } | ||
| ``` | ||
|
|
||
| NOTE: the password is hashed and salted properly for login before inserting in the database. | ||
|
|
||
| To create another admin user via the API, include the appropriate scope in the POST body: | ||
| ```http | ||
| POST /users | ||
| { "username": "username", "password": "password", "scope": [ "oada.admin.user:all" ] | ||
| ``` | ||
| IMPORTANT NOTE: API-driven user creation has 2 extra failsafes built-in. Both the user and the token must have `oada.admin.user:all` scope in order to be able to create users. When getting a token via `client.oada-dev.com`, this means that you have to remember to include that scope in the request: normally you could ask for scope of `all:all`, but for the token to also be able to create users, you need to ask for scope of `all:all oada.admin.user:all`. | ||
|
|
||
| ### Services and Modules | ||
|
|
||
| You can override or augment core components of your OADA installation by enabling additional | ||
| services inside [oada-srvc-docker](https://github.com/oada/oada-srvc-docker). For example, if you want to | ||
| use your own authentication mechanism to login, you can override `auth` with your own container. | ||
| If you want to enable backups, install the [oada-backups](https://github.com/oada/oada-backups) service | ||
| and enable it. Let's install backups to see how it works: | ||
|
|
||
| ```bash | ||
| cd path/to/oada-srvc-docker | ||
| cd services-available | ||
| git clone [email protected]:OADA/oada-backups.git | ||
| cd ../services-enabled | ||
| ln -s ../serivces-available/oada-backups . | ||
| ``` | ||
|
|
||
| [oada-backups](https://github.com/oada/oada-backups) has a docker-compose file inside that defines its service | ||
| and augments the core services. Once symlinked to services-enabled, the `oada` command will pickup that | ||
| compose file and add it to all the others. Now an `oada up -d` will start the oada-backups services as well. | ||
| In this case, it keeps a rolling set of backups of the internal `arangodb` database in a docker volume. | ||
|
|
||
| As a side note, you can also define a suite of cooperating services in a single folder that share a single | ||
| docker-compose file. | ||
| To see an example of how to solve a particular problem using the OADA API, please refer to the | ||
| documentation from the Pork Hackathon: [PorkHack21](https://github.com/porkhack/porkhack21-part1shipping). | ||
|
|
||
|
|
||
| ### An Overview of OADA Repos | ||
|
|
||
| #### The core: | ||
| * [oada-docs](https://github.com/oada/oada-docs) The core API spec and associated documentation. | ||
|
|
||
| * [oada-srvc-docker](https://github.com/oada/oada-srvc-docker) The installable reference implementation of the OADA API. | ||
| * [oada/oada-docs](https://github.com/oada/oada-docs) The core API spec and associated documentation. | ||
|
|
||
| * [oada-formats](https://github.com/oada/oada-formats) Sets of schemas and examples for various OADA content types. | ||
| * [oada/server](https://github.com/oada/server) The Docker-based reference implementation of the OADA API. | ||
|
|
||
| #### Installable services or modules: | ||
| * [oada-backups](https://github.com/oada/oada-backups) An OADA installable service that creates a rolling backup of the internal | ||
| ArangoDB database every night. | ||
|
|
||
| * [oada-ensure](https://github.com/oada/oada-ensre) An OADA installable services intended to one day allow configurable | ||
| integrity checks against a tree: i.e. when a write happens, it will `ensure` that other things happen too like making | ||
| like linking back to a parent anytime a child is made. | ||
| * [oada/formats](https://github.com/oada/formats) Sets of schemas and examples for various OADA content types. | ||
|
|
||
| #### Authorization and Signatures | ||
|
|
||
| * [oada-certs](https://github.com/oada/oada-certs) A command line tool and javascript library for signing things and validating | ||
| * [oada/oada-certs](https://github.com/oada/oada-certs) A command line tool and javascript library for signing things and validating | ||
| those signatures. It contains most of the core signature logic used by [trellisfw-signatures](https://github.com/trellisfw/trellisfw-signatures). | ||
| You can use it in the `admin` container to setup a new domain on your `oada-srvc-docker` installation (to sign the developer certificate), | ||
| You can use it in the `admin` container to setup a new domain on your `oada` installation (to sign the developer certificate), | ||
| or you can use it to generate signing key pairs and convert them to JWK's. | ||
|
|
||
| * [oada-trusted-lists](https://github.com/oada/oada-trusted-lists) The list of trusted signing keys for OADA developer certificates. | ||
|
|
||
| * [oada-id-client-js](https://github.com/oada/oada-id-client-js) A javascript library that simplifies performing authorization with | ||
| * [oada/oada-id-client-js](https://github.com/oada/oada-id-client-js) A javascript library that simplifies performing authorization with | ||
| an OADA server. It handles initiating OAuth2 requests and returning the resulting authorization tokens. | ||
|
|
||
| #### Javascript libraries | ||
|
|
||
| * [oada-cache](https://github.com/oada/oada-cache) A Vanilla Javascript library for Node and the Browser that handles much of the interaction | ||
| with an OADA cloud: connecting, keeping an open websocket for changes, setting watches, caching data locally with automatic updates from | ||
| the change feeds, resuming watches where you left off, and concurrency-protected "tree"-based PUTs that ensure a given path exists properly prior to | ||
| executing a PUT. | ||
|
|
||
| * [oada-jobs](https://github.com/oada/oada-jobs) A javascript library that simplifies creating a microservice which listens to a | ||
| job queue for things to appear that it should do. | ||
|
|
||
| * [cerebral-provider](https//github.com/oada/cerebral-provider) A `Provider` wrapper for OADA, used when making web apps that use | ||
| the [Cerebral-js](https://cerebraljs.com) framework. | ||
|
|
||
| * [cerebral-module](https://github.com/oada/cerebral-module) A state management module for the [Cerebral-js](https://cerebraljs.com) app | ||
| development framework. Including this module in your project will replicate a given subtree from an OADA installation in your React.js | ||
| state tree, keeping it in sync automatically via the change feed. | ||
| * [oada/client](https://github.com/oada/client) A Typescript/JS library for Node and the Browser that handles much of the interaction | ||
| with an OADA cloud: connecting, keeping an open websocket for changes, setting watches, and concurrency-protected "tree"-based PUTs that ensure a given path exists properly when executing a PUT. | ||
|
|
||
| * [type](https://github.com/oada/types) A wrapper for [oada-formats](https://github.com/oada/oada-formats) that creates typescript types | ||
| from `oada-formats` schemas. | ||
| * [oada/jobs](https://github.com/oada/jobs) A Typescript/javascript library that simplifies creating a microservice which listens to a | ||
| job queue for things that it should do. | ||
|
|
||
| * [oada-cache-overmind](https://github.com/oada/oada-cache-overmind) A state management module for the [Overmind-js](https://overmindjs.org) | ||
| app development framework. Much like [cerebral-module](https://github.com/oada/cerebral-module), this will keep a subtree from an | ||
| OADA service in your React.js state tree and keep it up to date in real-time via the change feed. | ||
| * [oada/types](https://github.com/oada/types) A wrapper for [oada/formats](https://github.com/oada/formats) that creates and publishes typescript types | ||
| from `formats` json schemas. | ||
|
|
||
|
|
||
| ## Frequently Asked Questions | ||
|
|
||