walnut.js/INSTALL.md

312 lines
7.7 KiB
Markdown

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.