diff --git a/README.md b/README.md index 5dbcb93..30b70fa 100644 --- a/README.md +++ b/README.md @@ -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 git@github.com: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: -Password: -Domain: -``` -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 git@github.com: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