Verified Commit d8fc54e3 authored by Aral Balkan's avatar Aral Balkan
Browse files

Restructure Hallo.gent section and add Magic Web Site factory details

  * API
  * Indie Site Deployment requirements
parent 3cff5789
onboarding
Hallobot
Nederlands
...@@ -5,7 +5,7 @@ weight: 20 ...@@ -5,7 +5,7 @@ weight: 20
<style>h1 { text-indent: -9999px; white-space: nowrap; overflow: hidden; height: 0;}</style> <style>h1 { text-indent: -9999px; white-space: nowrap; overflow: hidden; height: 0;}</style>
<a href='https://source.ind.ie/indienet/hallo-gent'><img src='/images/hallo.gent-colour.png' alt='Hallo.gent logo' style='width: 20vmax;'></a> <a href='https://source.ind.ie/indienet/hallo-gent'><img src='/images/hallo.gent-circular.svg' alt='Hallo.gent logo' style='width: 20vmax;'></a>
<h2 style='color: black; font-size: 3vmax;'>Say hello to your friends, the city, and to the world.</h2> <h2 style='color: black; font-size: 3vmax;'>Say hello to your friends, the city, and to the world.</h2>
...@@ -314,7 +314,7 @@ First two steps are the same as A. ...@@ -314,7 +314,7 @@ First two steps are the same as A.
### C. Geofenced ### C. Geofenced
Authorisation for a free Indie Site with a free .gent domain may also use geographical location as the criteria. This would also include people whom the city calls “users” (anyone who uses the City and its services). It could also provide a turism advantage (e.g., “take a little piece of the city with you…”, etc.) Authorisation for a free Indie Site with a free .gent domain may also use geographical location as the criteria. This would also include people whom the city calls “users” (anyone who uses the City and its services). It could also provide a tourism advantage (e.g., “take a little piece of the city with you…”, etc.)
## Welcome/setup experience on the site itself ## Welcome/setup experience on the site itself
......
The Magic Website Factory is used to query for .Gent domain availability and to request domain registration and Indie Site setup.
The Magic Website Factory is being developed in conjunction with [Combell](http://combell.gent), patrons of the .Gent top-level domain, and this specific instance is hosted by them on their infrastructure. The API presented here forms the public interface between Hallo.gent and Combell.
There is a development-time version of the Magic Website Factory used for local testing at https://source.ind.ie/indienet/magic-website-factory
All API calls require the passing of a secret that authenticates them. For the test server, this secret is hardcoded.
`secret=ethical-design`
## API versioning
The API endpoints should be versioned, starting with the current version at `/v1`. All locations, below, should be prefixed with the version identifier.
e.g., https://magicwebsitefactory.gent/v1/domain
## Domain service
Location: `/domain`
### GET
Check if the domain is available. Returns a JSON object with a boolean status.
#### Parameters
`/domain/<domain>?secret=ethical-design`
Where the following known values for `domain` returns the following responses:
#### Responses
* available.gent: `{"status": true}`
* unavailable.gent: `{"status": false}`
* error.gent: triggers the 503 service unavailable error.
On error, the server should return a valid error message.
Valid errors:
* 503: Service unavailable. The domain check/registration service is unavailable.
## Site service
Location: `/site`
### POST
Asks for the passed domain to be registered and for an Indie Site to be set up at it.
#### Parameters
* `domain=<domain>`: the domain to register
* `callback=<callback-url>`: the callback URL to inform when the domain is ready
* `secret=ethical-design`
#### Responses
* Registration request received and process successfully started: 201 Created
* Domain not available: 409 Conflict
* Domain registration service is unavailable: 503 Service Unavailable
## Callback
On successful registration of the domain and creation of the Indie Site, the Magic Website Factory carries out a PATCH request to the `callback` URL passed in the Site service’s POST method with the following arguments:
### PATCH
Location: `<callback-url>/site/`
#### Parameters
* `<callback-url>/site/<domain>`: domain to update the status for
* `?status=<code>`: 201 = created, 409 = conflict (domain not available), 500 = internal server error (the site setup process failed and will not be retried)
* `&secret=ethical-design`
#### Responses
The Magic Website Factory expects the following responses to its callback request:
* 200 OK: Response successfully received
* Error code (depending on error): callback failed. Log the error and queue the callback to be tried again (exponential falloff).
\ No newline at end of file
---
title: "Magic Website Factory"
weight: 10
---
The Magic Website Factory is used to query for .Gent domain availability and to request domain registration and Indie Site setup.
The Magic Website Factory is being developed in conjunction with [Combell](http://combell.gent), patrons of the .Gent top-level domain, and this specific instance is hosted by them on their infrastructure.
The [API](api/) presented here forms the public interface between Hallo.gent and Combell.
There is a development-time version of the Magic Website Factory used for local testing at [source.ind.ie/indienet/magic-website-factory](https://source.ind.ie/indienet/magic-website-factory).
## Sections
{{% children %}}
\ No newline at end of file
---
title: "API"
weight: 10
---
All API calls require the passing of a secret that authenticates them. For the test server, this secret is hardcoded.
`secret = "<secret>"`
## API versioning
The API endpoints should be versioned, starting with the current version at `/v1`. All locations, below, should be prefixed with the version identifier.
e.g., https://live.magicwebsitefactory.gent/v1/domain
## Live and test subdomains
- Live: https://live.magicwebsitefactory.gent
- Test: https://test.magicwebsitefactory.gent
## Domain service
Location: `/domain`
### GET
Check if the domain is available. Returns a JSON object with a boolean status.
#### Parameters
`/domain/<domain>?secret=<secret>`
Where the following known values for `domain` returns the following responses:
#### Responses
* available.gent: `{"status": true}`
* unavailable.gent: `{"status": false}`
* error.gent: triggers the 503 service unavailable error.
On error, the server should return a valid error message.
Valid errors:
* 503: Service unavailable. The domain check/registration service is unavailable.
## Site service
Location: `/site`
### POST
Asks for the passed domain to be registered and for an Indie Site to be set up at it.
#### Parameters
```json
{
"domain": "<the domain to register (string)>",
"callback": "<callback URL>",
"owner-settings": {
// Object with owner settings, to be copied
// into the ~/indie/v1/owner-settings.json file
// at deployment time.
},
"secret": "<secret>"
}
```
#### Responses
* Registration request received and process successfully started: 201 Created
* Domain not available: 409 Conflict
* Domain registration service is unavailable: 503 Service Unavailable
## Callback
On successful registration of the domain and creation of the Indie Site, the Magic Website Factory carries out a PATCH request to the `callback` URL passed in the Site service’s POST method with the following arguments:
### PATCH
Location: `<callback-url>/site/`
#### Parameters
* `<callback-url>/site/<domain>`: domain to update the status for
* `?status=<code>`: 201 = created, 409 = conflict (domain not available), 500 = internal server error (the site setup process failed and will not be retried)
* `&secret=<secret>`
#### Responses
The Magic Website Factory expects the following responses to its callback request:
* 200 OK: Response successfully received
* Error code (depending on error): callback failed. Log the error and queue the callback to be tried again (exponential falloff).
\ No newline at end of file
---
title: "Indie Site Deployment"
weight: 20
---
When called with a valid and authenticated [POST request to the Site Service](../api/#site-service), the Magic Website Factory:
1. Registers the requested domain.
2. Configures an [Indie Site](/site) instance with the passed owner settings details.
3. When ready, calls the passed callback URL to inform Hallo.gent.
[The relevant API call](../api/#site-service) is detailed on the API page.
Here, we present the requirements for Indie Site configuration.
## Application details
[Indie Site](/site) ([source](https://source.ind.ie/indienet/site)):
* Is a pure Node.js application
* Is single process (uses an in-process LevelDB database)
* Only has node module dependencies (`npm install`)
## Configuration
Indie Site expects its configuration data to be accessible from the following directory, which must be set up by the Magic Website Factory.
`~/indie/v1/`
Inside that directory, it expects the following file:
`owner-settings.json`: the owner settings that were passed to the [Magic Website Factory Site Service (POST) method](../api/#site-service)
## Running
To run Indie Site in production:
```bash
npm start
```
---
title: "Meeting notes"
weight: 10
---
Notes from meetings in Ghent.
{{% children %}}
<?xml version="1.0" encoding="UTF-8"?>
<svg width="640px" height="640px" viewBox="0 0 640 640" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<!-- Generator: Sketch 49.1 (51147) - http://www.bohemiancoding.com/sketch -->
<title>hallo.gent-circular</title>
<desc>Created with Sketch.</desc>
<defs></defs>
<g id="hallo.gent-circular" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
<g id="hallo.gent-logo,-outlines">
<circle id="Background" fill="#009DE0" cx="320" cy="320" r="320"></circle>
<path d="M223.2832,460.561067 C228.061867,460.561067 231.645867,464.264533 231.645867,468.804267 C231.645867,473.463467 228.061867,477.166933 223.2832,477.166933 C218.624,477.166933 215.04,473.463467 215.04,468.804267 C215.04,464.264533 218.624,460.561067 223.2832,460.561067 Z M295.441067,405.725867 L298.666667,415.6416 C293.410133,417.314133 287.4368,417.553067 280.2688,417.553067 C287.675733,420.898133 291.3792,426.154667 291.3792,433.442133 C291.3792,445.866667 282.4192,454.826667 267.3664,454.826667 C264.4992,454.826667 261.9904,454.468267 259.362133,453.632 C257.570133,454.946133 256.256,457.216 256.256,459.485867 C256.256,462.353067 258.048,464.622933 264.4992,464.622933 L274.5344,464.622933 C287.4368,464.622933 296.0384,472.029867 296.0384,482.065067 C296.0384,494.250667 286.0032,501.179733 266.530133,501.179733 C245.981867,501.179733 239.530667,494.848 239.530667,482.065067 L249.4464,482.065067 C249.4464,489.233067 252.672,492.578133 266.530133,492.578133 C280.149333,492.578133 284.928,489.1136 284.928,482.781867 C284.928,476.808533 280.149333,473.821867 272.264533,473.821867 L262.3488,473.821867 C251.118933,473.821867 246.101333,468.206933 246.101333,461.8752 C246.101333,457.813333 248.490667,453.751467 253.0304,450.7648 C245.742933,446.941867 242.397867,441.4464 242.397867,433.322667 C242.397867,420.420267 252.791467,411.3408 266.6496,411.3408 C282.299733,411.6992 288.034133,409.070933 295.441067,405.725867 Z M266.6496,419.2256 C258.167467,419.2256 253.627733,425.079467 253.627733,433.322667 C253.627733,441.685333 258.286933,447.5392 266.888533,447.5392 C275.490133,447.5392 280.149333,442.282667 280.149333,433.2032 C280.149333,424.004267 275.6096,419.2256 266.6496,419.2256 Z M355.652267,442.402133 C355.652267,444.552533 355.5328,446.583467 355.413333,448.017067 L315.272533,448.017067 C316.347733,462.592 323.157333,468.206933 332.2368,468.206933 C338.449067,468.206933 343.108267,466.5344 348.603733,462.711467 L353.3824,469.282133 C347.170133,474.180267 340.1216,477.166933 331.400533,477.166933 C313.838933,477.166933 303.5648,464.861867 303.5648,444.910933 C303.5648,425.3184 313.480533,411.3408 329.728,411.3408 C346.692267,411.3408 355.652267,423.168 355.652267,442.402133 Z M344.7808,439.893333 L344.7808,439.176533 C344.7808,426.871467 339.882667,420.061867 329.966933,420.061867 C321.604267,420.061867 316.1088,425.915733 315.272533,439.893333 L344.7808,439.893333 Z M402.8416,411.3408 C414.429867,411.3408 421.12,418.628267 421.12,430.574933 L421.12,475.733333 L410.129067,475.733333 L410.129067,432.128 C410.129067,422.690133 406.306133,419.9424 400.213333,419.9424 C393.1648,419.9424 388.386133,424.362667 384.2048,431.0528 L384.2048,475.733333 L373.213867,475.733333 L373.213867,412.7744 L382.651733,412.7744 L383.607467,422.0928 C387.908267,415.6416 394.5984,411.3408 402.8416,411.3408 Z M470.818133,465.578667 L474.999467,472.866133 C470.818133,475.733333 466.2784,477.166933 460.9024,477.166933 C450.269867,477.166933 443.938133,470.954667 443.938133,459.246933 L443.938133,421.256533 L432.9472,421.256533 L432.9472,412.7744 L443.938133,412.7744 L443.938133,398.557867 L454.929067,397.243733 L454.929067,412.7744 L469.8624,412.7744 L468.667733,421.256533 L454.929067,421.256533 L454.929067,458.769067 C454.929067,465.1008 456.96,468.087467 462.455467,468.087467 C465.2032,468.087467 467.712,467.2512 470.818133,465.578667 Z" id=".gent" fill="#FFFFFF"></path>
<path d="M139.221333,249.472 C160.810667,249.472 173.952,263.552 173.952,287.018667 L173.952,377.6 L140.629333,377.6 L140.629333,292.650667 C140.629333,278.336 135.232,274.346667 127.018667,274.346667 C117.632,274.346667 109.888,280.682667 103.082667,291.477333 L103.082667,377.6 L69.76,377.6 L69.76,203.712 L103.082667,200.192 L103.082667,267.306667 C112.938667,255.808 124.202667,249.472 139.221333,249.472 Z M300.672,343.104 C300.672,353.194667 303.722667,356.714667 309.824,358.826667 L302.784,380.885333 C288.704,379.712 279.317333,375.018667 274.154667,362.581333 C265.237333,376.192 251.626667,381.354667 236.842667,381.354667 C211.968,381.354667 196.48,365.397333 196.48,342.869333 C196.48,315.648 216.896,300.864 253.738667,300.864 L268.053333,300.864 L268.053333,294.762667 C268.053333,279.274667 261.482667,274.346667 245.76,274.346667 C237.546667,274.346667 225.578667,276.693333 212.906667,280.917333 L205.397333,258.624 C220.885333,252.522667 237.312,249.472 251.392,249.472 C285.888,249.472 300.672,264.725333 300.672,292.885333 L300.672,343.104 Z M245.994667,357.418667 C255.616,357.418667 262.890667,352.490667 268.053333,343.573333 L268.053333,319.872 L257.024,319.872 C238.954667,319.872 230.037333,326.442667 230.037333,340.053333 C230.037333,351.082667 235.669333,357.418667 245.994667,357.418667 Z M362.624,381.354667 C342.442667,381.354667 330.474667,369.152 330.474667,347.562667 L330.474667,203.712 L363.797333,199.957333 L363.797333,346.624 C363.797333,352.021333 365.909333,354.837333 370.602667,354.837333 C373.184,354.837333 375.296,354.368 377.173333,353.429333 L383.978667,377.130667 C378.581333,379.477333 371.072,381.354667 362.624,381.354667 Z M432.085333,381.354667 C411.904,381.354667 399.936,369.152 399.936,347.562667 L399.936,203.712 L433.258667,199.957333 L433.258667,346.624 C433.258667,352.021333 435.370667,354.837333 440.064,354.837333 C442.645333,354.837333 444.757333,354.368 446.634667,353.429333 L453.44,377.130667 C448.042667,379.477333 440.533333,381.354667 432.085333,381.354667 Z M521.728,249.472 C558.805333,249.472 581.098667,274.112 581.098667,315.413333 C581.098667,354.837333 558.805333,381.354667 521.493333,381.354667 C484.416,381.354667 461.888,356.714667 461.888,315.413333 C461.888,275.754667 484.181333,249.472 521.728,249.472 Z M521.728,274.346667 C505.066667,274.346667 496.618667,287.018667 496.618667,315.413333 C496.618667,344.042667 505.066667,356.48 521.493333,356.48 C537.92,356.48 546.368,343.808 546.368,315.413333 C546.368,286.784 537.92,274.346667 521.728,274.346667 Z" id="hallo" fill="#FFFFFF"></path>
<path d="M458.042801,402.536078 C462.513339,399.89921 463.86597,399.024495 464.101279,398.892574 C467.451039,397.014618 470.550705,394.611474 473.285162,391.733226 C480.561422,384.074344 484.656334,373.681222 484.452126,362.832393 C484.465023,373.676923 488.557785,384.070045 495.836195,391.728927 C498.602426,394.64062 501.742403,397.066413 505.136832,398.954102 C505.358203,399.077209 507.550028,400.438881 508.352583,400.974913 C509.155138,401.510945 453.572263,405.172947 458.042801,402.536078 Z" id="Stad-Gent-“Accolade”;-speech-bubble-pointer-Copy" fill="#FFFFFF" transform="translate(483.074020, 383.156735) rotate(-146.000000) translate(-483.074020, -383.156735) "></path>
</g>
</g>
</svg>
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment