[add] added readme
This commit is contained in:
100
README.md
100
README.md
@@ -1,24 +1,98 @@
|
|||||||
# README
|
<h1 align="center">rynDNS</h1>
|
||||||
|
|
||||||
This README would normally document whatever steps are necessary to get the
|
<h4 align="center">
|
||||||
application up and running.
|
A simplistic Dynamic DNS-ish server.
|
||||||
|
</h4>
|
||||||
|
|
||||||
Things you may want to cover:
|
`rynDNS` is a simple REST-API for `name` to `ip` resolving in the spirit of Dynamic DNS. Clients can `PUT` their `ipv4` address up to be read by other clients. Access is controlled via `api_key` and permissions (`read`, `write`, `admin`).
|
||||||
|
|
||||||
* Ruby version
|
<p align="center">
|
||||||
|
<strong>
|
||||||
|
<a href="https://demo.api.pdev.dev">Demo</a>
|
||||||
|
• <a href="#getting-started">Getting started</a>
|
||||||
|
• <a href="#rest-api">Rest API</a>
|
||||||
|
• <a href="#configuration">Configuration</a>
|
||||||
|
</strong>
|
||||||
|
</p>
|
||||||
|
|
||||||
* System dependencies
|
## Getting Started
|
||||||
|
|
||||||
* Configuration
|
This repo includes a [`Dockerfile`](Dockerfile) with an accompanying [`docker-compose.yml`](docker-compose.yml). To build and launch the container simply run:
|
||||||
|
```bash
|
||||||
|
docker-compose up
|
||||||
|
```
|
||||||
|
Once the container is build and running it will create a default admin account and post its randomly generated api key to the console:
|
||||||
|
```
|
||||||
|
ryndns | No admin accounts in Database, adding default: admin
|
||||||
|
ryndns | Created default admin with api_key: 3NJbP4tS.39b92576.062...
|
||||||
|
```
|
||||||
|
The API is now accessible at http://localhost:3000/rynDNS.
|
||||||
|
```bash
|
||||||
|
# using httpie
|
||||||
|
API_SERVER=http://localhost:3000/rynDNS
|
||||||
|
API_KEY=X-API-Key:3NJbP4tS.39b92576.062142e6451df545d5034ca8f6050b80ff3e9689f20d5e45d72d160fa7e1cf32
|
||||||
|
|
||||||
* Database creation
|
# list all clients
|
||||||
|
http get $API_SERVER/admin/clients $API_KEY
|
||||||
|
|
||||||
* Database initialization
|
# creating a client
|
||||||
|
JSON_REQUEST_BODY='{
|
||||||
|
"name": "clientA",
|
||||||
|
"description": "Client across the river",
|
||||||
|
"permission": "rw",
|
||||||
|
"public_ip": false
|
||||||
|
}'
|
||||||
|
http post $API_SERVER/admin/client $API_KEY <<< $JSON_REQUEST_BODY
|
||||||
|
```
|
||||||
|
## REST API
|
||||||
|
A detailed and interactive specification can be found in the [demo](https://demo.api.pdev.dev) which is a render of the OpenAPI specification [api.yml](api.yml) with `swager-ui`.
|
||||||
|
|
||||||
* How to run the test suite
|
All requests except for `/public/*` require a valid `X-API-Key` header with appropriate permission.
|
||||||
|
|
||||||
* Services (job queues, cache servers, search engines, etc.)
|
The following is a quick overview of the available commands.
|
||||||
|
|
||||||
* Deployment instructions
|
### Admin
|
||||||
|
Permission `x`
|
||||||
|
|
||||||
* ...
|
* [`POST /admin/client`](https://demo.api.pdev.dev/#/admin/create_client) - Create or update a client and retrieve a new API key
|
||||||
|
* [`PUT /admin/client`](https://demo.api.pdev.dev/#/admin/update_client) - Update an existing client
|
||||||
|
* [`GET /admin/clients`](https://demo.api.pdev.dev/#/admin/get_all_client) - Retrieve all clients information
|
||||||
|
* [`GET /admin/clients/{client_name}`](https://demo.api.pdev.dev/#/admin/get_client) - Retrieve client information
|
||||||
|
* [`DELETE /admin/clients/{client_name}`](https://demo.api.pdev.dev/#/admin/delete_client) - Delete an existing client
|
||||||
|
|
||||||
|
### Client (write)
|
||||||
|
Permission `w`
|
||||||
|
|
||||||
|
* [`PUT /client`](https://demo.api.pdev.dev/#/client%20(write)/update_client_ip) - Update ipv4 client information based on request IP or body if present
|
||||||
|
* [`DELETE /client`](https://demo.api.pdev.dev/#/client%20(write)/delete_client_ip) - Delete the requesting client's ipv4 information
|
||||||
|
|
||||||
|
### Client (read)
|
||||||
|
Permission `r`
|
||||||
|
|
||||||
|
* [`GET /clients/{client_name}`](https://demo.api.pdev.dev/#/client%20(read)/get_client_ip) - Get ipv4 client information
|
||||||
|
|
||||||
|
### Public
|
||||||
|
Client attribute `public_ip: true`
|
||||||
|
|
||||||
|
* [`GET /public/{client_name}`](https://demo.api.pdev.dev/#/public/get_public_client_ip) - Get ipv4 client information
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
The `rynDNS` server can be configured with environment variables, these can also be set in the docker environment:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# set to run app in subdirectory [default: /]
|
||||||
|
RAILS_RELATIVE_URL_ROOT: /rynDNS
|
||||||
|
# set maximum number of clients in db [default: 250]
|
||||||
|
RAILS_MAX_CLIENTS: 250
|
||||||
|
# set custom api key prefix [default: randomly generated (saved and restored if using docker)]
|
||||||
|
API_KEY_PREFIX: zW3If4s5
|
||||||
|
# set custom header name for api key [default: X-API-Key]
|
||||||
|
API_KEY_HEADER: X-API-Key
|
||||||
|
# set to reset the admin account, this will output a new api key on the console when starting the server [default: 0]
|
||||||
|
RAILS_RESET_ADMIN: 1
|
||||||
|
# set app to run as demo [default: 0]
|
||||||
|
RAILS_API_DEMO: 1
|
||||||
|
# [DOCKER only] set cycle to reset demo data [default: 60m]
|
||||||
|
RAILS_DEMO_RESET: 60m
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user