walnut.js/INSTALL.md

From 0 to "Hello World"
=======================

Goal:

The purpose of this tutorial is to install Walnut and be able to launch a simple "Hello World" app.

Pre-requisites:

* You have compatible server hardware
  * Daplie Server
  * EspressoBin
  * Raspberry Pi
  * MacBook
  * (pretty much anything, actually)
* You have compatible software
  * Linux of any sort that uses systemd
  * macOS using launchd
* You own a domain
  * through Daplie Domains
  * or you understand domains and DNS and all that stuff

Choose a domain
---------------

For the purpose of this instruction we'll assume that your domain is `example.com`,
but you can use, say, `johndoe.daplie.me` for testing through Daplie Domains.

Anyway, go ahead and set the bash variable `$my_domain` for the purposes of the
rest of this tutorial:

```
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
```

Subdomains
----------

Auth will be loaded with the following domains

```
provider.example.com
api.provider.example.com
```

The Hello World app will be loaded with the following domains

```
example.com
www.example.com
api.example.com
assets.example.com
```

The domains can be setup through the Daplie Desktop App or with daplie-tools

Replace `foodevice` with whatever you like to call this device

```bash
# hostname
my_device=foodevice

# curl https://api.oauth3.org/api/tunnel@oauth3.org/checkip
my_address=127.0.0.1

# set device address and attach primary domain
daplie devices:attach -d $my_device -n $my_domain -a $my_address

# attach all other domains with same device/address
daplie devices:attach -d $my_device -n provider.$my_domain
daplie devices:attach -d $my_device -n api.provider.$my_domain
daplie devices:attach -d $my_device -n www.$my_domain
daplie devices:attach -d $my_device -n api.$my_domain
daplie devices:attach -d $my_device -n assets.$my_domain
daplie devices:attach -d $my_device -n cloud.$my_domain
daplie devices:attach -d $my_device -n api.cloud.$my_domain
```

Goldilocks Configuration
------------------------

Walnut must sit behind a proxy that properly terminates https and sets the `X-Forwarded-Proto` header.

Goldilocks can do this, as well as manage daplie domains, tunneling, etc.

```bash
curl https://daplie.me/install-scripts | bash

daplie-install-goldilocks
```


Example `/etc/goldilocks/goldilocks.yml`:
```yml
tls:
  email: domains@example.com
  servernames:
    - example.com
    - www.example.com
    - api.example.com
    - assets.example.com
    - cloud.example.com
    - api.cloud.example.com
    - provider.example.com
    - api.provider.example.com

http:
  trust_proxy: true
  modules:
    - name: proxy
      domains:
        - '*'
      address: '127.0.0.1:3000'
```

Basic Walnut Install
--------------------

```bash
curl https://daplie.me/install-scripts | bash

daplie-install-walnut
```

You could also, of course, try installing from the repository directly
(especially if you have goldilocks or some similar already installed)

```bash
mkdir -p /srv/walnut/
git clone https://git.daplie.com/Daplie/walnut.js.git /srv/walnut/core
pushd /srv/walnut/core
  git checkout v1
popd
bash /srv/walnut/core/install-helper.sh
```

Initial Configuration
-------------

Once installed and started you can visit <https://localhost.daplie.me:3000> to configure the primary domain.

You could also do this manually via curl:

```bash
curl -X POST http://api.localhost.daplie.me:3000/api/walnut@daplie.com/init \
  -H 'X-Forwarded-Proto: https' \
  -H 'Content-Type: application/json' \
  -d '{ "domain": "'$my_domain'" }'
```

Resetting the Initialization
----------------------------

Once you run the app the initialization files will appear in these locations

```
/srv/walnut/var/com.daplie.walnut.config.sqlite3
/srv/walnut/config/<domain.tld>/config.json
```

Deleting those files and restarting walnut will reset it to its bootstrap state.

Reset Permissions
-----------------

Since the app store and package manager are not built yet,
you should also change the permissions on the walnut directory for the purposes of this tutorial:

```bash
sudo chown -R $(whoami) /srv/walnut/
sudo chmod -R +s /srv/walnut/
```

Install OAuth3 API Package
--------------

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/
    git checkout v1.2
    npm install
popd

# Give permission for this package to provider.example.com
# the api. prefix is omitted because it is always assumed for APIs
echo "issuer@oauth3.org" >> /srv/walnut/packages/client-api-grants/provider.$my_domain
```

*NOTE*: Currently there are some hard-coded values that need to be changed out (TODO use `getSiteConfig()`).
`vim /srv/walnut/packages/rest/issuer@oauth3.org/lib/provide-oauth3.js` and search for the email stuff and change it.


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
  bash ./install.sh
popd

# Tell Walnut to load this site package when provider.example.com is requested
echo "issuer@oauth3.org" >> /srv/walnut/var/sites/provider.$my_domain
```

OAuth3 Secrets
--------------

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"
  , "auth": {
      "user": "robtherobot@example.com"
    , "pass": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    , "api_key": "key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    , "domain": "example.com"
    }
  }
, "issuer@oauth3.org": {
    "mailer": {
      "from": "login@example.com"
    , "subject": "Login code request"
    , "text": ":code\n\nis your login code"
    }
  }
}
```

Install the 'hello@example.com' package
---------------------

```bash
git clone https://git.daplie.com/Daplie/com.example.hello.git /srv/walnut/packages/rest/hello@example.com

echo "hello@example.com" >> /srv/walnut/packages/client-api-grants/provider.$my_domain
```

What it should look like:

```
/srv/walnut/packages/rest/hello@example.com/
  package.json
  api.js
  models.js
  rest.js

/srv/walnut/packages/client-api-grants/example.com
  '''
  hello@example.com
  '''
```

Setup the Seed App (front-end)
------------------------

Get the Seed App

```bash
pushd /srv/walnut/packages/pages/

git clone https://git.daplie.com/Daplie/seed_example.com.git --branch v1 seed@example.com

pushd seed@example.com/
  git clone https://git.daplie.com/OAuth3/oauth3.js.git --branch v1.1 assets/oauth3.org

  mkdir -p .well-known
  ln -sf  ../assets/oauth3.org/.well-known/oauth3 .well-known/oauth3
popd

echo "seed@example.com" >> /srv/walnut/var/sites/$my_domain

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' } }
```

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.