{"id":19163301,"url":"https://github.com/oada/server","last_synced_at":"2025-06-12T02:04:19.234Z","repository":{"id":38841989,"uuid":"89021364","full_name":"OADA/server","owner":"OADA","description":"Reference implementation of an OADA-conformant API server","archived":false,"fork":false,"pushed_at":"2025-04-28T17:27:43.000Z","size":25121,"stargazers_count":14,"open_issues_count":23,"forks_count":43,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-28T18:32:54.576Z","etag":null,"topics":["docker","docker-compose","node-js","oada"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OADA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":"support/proxy/Dockerfile","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-04-21T20:31:31.000Z","updated_at":"2025-04-28T17:27:44.000Z","dependencies_parsed_at":"2025-04-20T15:15:48.663Z","dependency_job_id":null,"html_url":"https://github.com/OADA/server","commit_stats":null,"previous_names":[],"tags_count":92,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Fserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Fserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Fserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OADA%2Fserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OADA","download_url":"https://codeload.github.com/OADA/server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252866124,"owners_count":21816397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-compose","node-js","oada"],"created_at":"2024-11-09T09:14:46.264Z","updated_at":"2025-05-07T11:22:07.075Z","avatar_url":"https://github.com/OADA.png","language":"TypeScript","readme":"# OADA Reference API Server\n\n[![CodeFactor](https://www.codefactor.io/repository/github/OADA/server/badge)](https://www.codefactor.io/repository/github/OADA/server)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n[![License](https://img.shields.io/github/license/OADA/server)](LICENSE)\n\nThis project is a reference implementation of an OADA-conformant API server.\nIt can be used to host your own OADA instance,\nor for comparison when creating an OADA-conformant API implementation.\n\nThe repository and releases come with configurations for easily running\nwith [docker-compose].\n\nYou can also theoretically run all the parts without docker or [docker-compose],\nbut you will need [arangodb] and either [redpanda] or [kafka]\nfor the micro-services to use.\n\n## OADA micro-services\n\nFor information on\nthe various micro-services comprising this reference implementation,\nsee [the `oada` folder](oada/).\n\n## Installing\n\n### Kubernetes\n\nThere is a Helm chart of the OADA server.\nIt is the preferred method of using the server now.\n\nSee [charts/oada](charts/oada) for more information.\n\n### docker-compose\n\n#### Running a release in docker-compose\n\nDownload one of our [releases] and start it using [docker-compose].\n\n```shell\ncd folder/containing/release/docker-compose\n# Will pull the corresponding release images from DockerHub\nDOMAIN=yourdomain.com docker-compose up -d\n```\n\n#### Running as localhost with docker-compose\n\nlocalhost doesn't work out of the box because you need to\ncreate a self-signed SSL certificate and map it into your OADA installation.\n\nTo generate a certificate, get [mkcert](https://github.com/FiloSottile/mkcert)\n(works on pretty much every platform).\nThen, install `mkcert` to your machine's local certificate authority\n(so when you make requests to your OADA, it will trust the self-signed certificate)\n\n```shell\n# Only do this if you did not previously have mkcert installed.\nmkcert -install\n```\n\nNow generate a certificate for localhost (in a folder named localhost)\n\n```shell\nmkdir localhost\nmkcert -cert-file ./localhost/fullchain.pem -key-file ./localhost/privkey.pem localhost\n# The certificate is at \"./localhost/fullchain.pem\" and the key at \"./localhost/privkey.pem\"\n```\n\nFinally, tell OADA to use it by mapping it\ninto the docker-compose service definition for the proxy.\nNOTE: if you already have a `docker-compose.override.yml`,\ndo not run this command as it will overwrite it.\n\n```shell\n# Configure docker to map in the new cert as an override:\nprintf \"services:\\n  proxy:\\n    volumes:\\n      - ./localhost:/config/keys/letsencrypt:ro\" \u003e docker-compose.override.yml\n# Re-up the proxy container with the new cert:\nDOMAIN=localhost docker-compose up -d proxy\n```\n\nYour server should now be working on localhost. Time to add a user and a token with which to make requests.\n\n### Add a user\n\nYou will need to add a user and a token to start making requests against your new OADA server. To add a user:\n\n```shell\ndocker-compose run users add -u username -p password -a\n```\n\nreplacing `username` and `password` with the username and password that you want. The `-a` means that the created user will be an admin user with the ability to add other users via the API.0\n\n### Add a token for a user\n\nYou need a token to make a request against an OADA server. While you can get a token via OAuth2, to add a token\nfor a user from the command line:\n\n```shell\ndocker-compose run auth token create -u username -s all:all\n```\n\nThe \"-s\" is the \"scope\" for the token. `all:all` means read/write for all content types. The token will have permission to any resources that the user has permission to.\n\nThat command will print the last line `Successfully wrote token \u003ctoken\u003e`. Copy the `\u003ctoken\u003e` for the authorization header on your requests.\n\n### Running from the git\n\nIf you want to contribute, or do other development type things,\nyou can run the server straight from this codebase.\n\n```shell\ngit clone https://github.com/OADA/server.git\ncd server\n# Running up the first time will automatically build the docker images\nDOMAIN=yourdomain.com docker-compose up -d\n```\n\nNote that running from the git is **not** recommended for production use.\n\n## Configuration\n\nTo modify the docker-compose configuration of your OADA instance,\nyou can simply create a `docker-compose.override.yml`\nin the same directory as the `docker-compose.yml` file.\nAny settings in this [override file] will be merged with ours\nwhen running docker-compose.\n\n### Environment variables\n\nAdditionally, there are various configuration environment variables available.\nSome important ones are:\n\n- DOMAIN: set to the domain name of your API server\n  (e.g., `oada.mydomain.net`)\n- EXTRA_DOMAINS: Additional domains to serve\n  (e.g., `oada.mydomain.org,oada.myotherdomain.net`)\n- DEBUG: set the namespace(s) enabled in [debug]\n  (e.g., `*:info,*:error,*:warn`)\n\nRather than trying to always remember to set your environment variables,\nyou probably want to use a [.env file] for things like `DOMAIN`.\n\n[releases]: https://github.com/OADA/server/releases\n[docker-compose]: https://docs.docker.com/compose/\n[.env file]: https://docs.docker.com/compose/environment-variables/#substitute-environment-variables-in-compose-files\n[arangodb]: https://www.arangodb.com\n[redpanda]: https://vectorized.io/redpanda\n[kafka]: https://kafka.apache.org\n[override file]: https://docs.docker.com/compose/extends/#understanding-multiple-compose-files\n[debug]: https://www.npmjs.com/package/debug#usage\n[`oadadeploy`]: https://github.com/OADA/oadadeploy\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foada%2Fserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foada%2Fserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foada%2Fserver/lists"}