diff --git a/API.md b/API.md index 3d55f9b..9601ae5 100644 --- a/API.md +++ b/API.md @@ -9,7 +9,7 @@ Bootstrap Initialization Before walnut is configured it starts up in a bootstrap mode with a single API exposed to set its primary domain. -``` +```bash # Set up with example.com as the primary domain curl -X POST http://api.localhost.daplie.me:3000/api/walnut@daplie.com/init \ -H 'X-Forwarded-Proto: https' \ @@ -51,6 +51,7 @@ where more information about a package can be found. Template variables ``` :package_name +:package_version ``` ```json @@ -133,13 +134,13 @@ a matter of not putting ourselves in a box and finding out later that it's very, very, very hard to open the box back up. `rest.js`: -``` +```js module.exports.create = function (conf, deps, app) { var API = require('./api.js'); var REST = { hello: function (req, res/*, next*/) { var promise = API.hello(deps, req.Models, req.oauth3/*, opts*/); - + app.handlePromise(req, res, promise, "[hello@example.com]"); } } @@ -148,7 +149,7 @@ module.exports.create = function (conf, deps, app) { ### Special methods for `app`: -``` +```js app.handlePromise(request, response, promise, message); ``` @@ -166,24 +167,24 @@ req.apiUrlPrefix // This represents the full package path wit // This is particularly useful when constructing webhook URLs // i.e. https://api.example.com/api/pkg@domain.tld // (of https://api.example.com/api/pkg@domain.tld/public/foo) - + req.experienceId // The instance name of an app as a whole, where an app is mounted // i.e. the 'example.com' part of https://example.com/foo // OR 'example.com#foo' if '/foo' is part of the app's mount point - + req.clientApiUri // The api URL for the instance of an app // i.e. the 'api.example.com' part of https://api.example.com/api/hello@example.com/kv/foo - + req.pkgId // The name of the package being accessed // i.e. the 'hello@example.com' part of https://api.example.com/api/hello@example.com/kv/foo - + req.oauth3.accountIdx // The system id of the account represented by the token // i.e. this is the user ``` Internal (and/or deprecated) APIs that you will very likely encounter -``` +```js req.getSiteStore().then(function (models) { req.Models = models; }); @@ -240,4 +241,4 @@ Bare and www domains are DISALLOWED from being served by Walnut. This enables scalability of static sites as the static assets are never on the same domain as generic APIs or authenticated assets. -It also enforces security by disallowing 1990s web vulnerabilities by default. \ No newline at end of file +It also enforces security by disallowing 1990s web vulnerabilities by default. diff --git a/INSTALL.md b/INSTALL.md index 64e6bdf..7d55447 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -35,7 +35,7 @@ my_domain=example.com You can purchase a domain with daplie tools -``` +```bash npm install -g git+https://git.daplie.com/Daplie/daplie-tools.git daplie domains:search -n $my_domain @@ -91,7 +91,7 @@ Walnut must sit behind a proxy that properly terminates https and sets the `X-Fo Goldilocks can do this, as well as manage daplie domains, tunneling, etc. -``` +```bash curl https://daplie.me/install-scripts | bash daplie-install-goldilocks @@ -186,7 +186,7 @@ We need to have a local login system. For the APIs for that we`ll install the `issuer@oauth3.org` API package and enable it for `api.provider.example.com`: -``` +```bash # API packaged for walnut git clone https://git.daplie.com/OAuth3/org.oauth3.provider.git /srv/walnut/packages/rest/issuer@oauth3.org pushd /srv/walnut/packages/rest/issuer@oauth3.org/ @@ -205,7 +205,7 @@ echo "issuer@oauth3.org" >> /srv/walnut/packages/client-api-grants/provider.$my_ For the user interface for that we'll install the `issuer@oauth3.org` site package and enable it -``` +```bash # Frontend git clone https://git.daplie.com/OAuth3/org.oauth3.git /srv/walnut/packages/pages/issuer@oauth3.org pushd /srv/walnut/packages/pages/issuer@oauth3.org @@ -223,11 +223,11 @@ OAuth3 is currently configured to use mailgun for sending verification emails. It is intended to provide a way to use various mail services in the future, just bear with us for the time being (or open a Merge Request). -``` +```bash vim /srv/walnut/var/$my_domain/config.json ``` -``` +```json { "mailgun.org": { "apiKey": "key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" , "apiPublicKey": "pubkey-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" @@ -296,11 +296,11 @@ popd You will need to change the authenication provider/issuer URL from `oauth3.org` to the domain you've selected (i.e. `provider.example.com`) -``` +```bash vim /srv/walnut/packages/pages/seed@example.com/js/config.js ``` -``` +```js { "azp@oauth3.org": { issuer_uri: 'provider.example.com', client_uri: 'example.com' } } ``` @@ -308,4 +308,4 @@ See Hello World --------------- Now visit your site (i.e. https://example.com) and you will be able to login -and access the hello world data. \ No newline at end of file +and access the hello world data. diff --git a/README.md b/README.md index f59a68a..a9d1172 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Security Features * disallows cookies, except for protected static assets * api.* subdomain for apis * assets.* subdomain for protected assets -* *must* sit behind a trusted https proxy (such as [Goldilocks](https://git.daplie.com/Daplie/goldilocks.js) +* *must* sit behind a trusted https proxy (such as [Goldilocks](https://git.daplie.com/Daplie/goldilocks.js)) * HTTPS-only (checks for X-Forwarded-For) * AES, RSA, and ECDSA encryption and signing * Safe against CSRF, XSS, and SQL injection @@ -53,14 +53,14 @@ Installation We're still in a stage where the installation generally requires many manual steps. -See [INSTALL.md](https://git.daplie.com/Daplie/walnut.js/blob/master/INSTALL.md) +See [INSTALL.md](/INSTALL.md) API --- The API is still in flux, but you can take a peek anyway. -See [API.md](https://git.daplie.com/Daplie/walnut.js/blob/master/API.md) +See [API.md](/API.md) Understanding Walnut ==================== @@ -77,8 +77,8 @@ Understanding Walnut ├── node_modules ├── packages │ ├── apis -| ├── pages -| ├── rest +│ ├── pages +│ ├── rest │ └── services └── var └── sites @@ -250,7 +250,7 @@ The packages: ''' - + ``` The permissions: @@ -271,4 +271,4 @@ The permissions: ''' seed@example.com # refers to /srv/walnut/packages/pages/seed@example.com ''' -``` \ No newline at end of file +```