walnut.js/INSTALL.md

311 lines
7.7 KiB
Markdown
Raw Normal View History

2017-08-02 21:18:41 +00:00
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)
2017-08-02 22:06:13 +00:00
* You have compatible software
2017-08-02 21:18:41 +00:00
* 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
```
2017-08-02 21:58:38 +00:00
You can purchase a domain with daplie tools
```
npm install -g git+https://git.daplie.com/Daplie/daplie-tools.git
daplie domains:search -n $my_domain
```
2017-08-02 21:18:41 +00:00
Subodmains
----------
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
```
2017-08-02 21:58:38 +00:00
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
2017-08-02 22:00:52 +00:00
# hostname
my_device=foodevice
2017-08-02 21:58:38 +00:00
# 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
2017-08-02 21:59:59 +00:00
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
2017-08-02 21:58:38 +00:00
```
2017-08-02 22:06:13 +00:00
Goldilocks Configuration
------------------------
Walnut must sit behind a proxy that properly terminates https and sets the `X-Forwarded-Proto` header.
2017-08-02 21:58:38 +00:00
2017-08-02 22:08:34 +00:00
Goldilocks can do this, as well as manage daplie domains, tunneling, etc.
2017-08-02 21:58:38 +00:00
```
2017-08-02 22:06:13 +00:00
curl https://daplie.me/install-scripts | bash
2017-08-02 21:58:38 +00:00
2017-08-02 22:06:13 +00:00
daplie-install-goldilocks
2017-08-02 21:58:38 +00:00
```
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
2017-08-02 22:06:13 +00:00
- provider.example.com
- api.provider.example.com
2017-08-02 21:58:38 +00:00
http:
trust_proxy: true
modules:
- name: proxy
domains:
- '*'
address: '127.0.0.1:3000'
```
2017-08-02 21:18:41 +00:00
Basic Walnut Install
--------------------
2017-08-02 21:36:18 +00:00
```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/
2017-08-03 01:06:02 +00:00
git clone https://git.daplie.com/Daplie/walnut.js.git /srv/walnut/core
2017-08-02 21:36:18 +00:00
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'" }'
```
2017-08-02 22:06:13 +00:00
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.
2017-08-02 21:36:18 +00:00
Reset Permissions
-----------------
2017-08-02 21:18:41 +00:00
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/
2017-08-02 21:36:18 +00:00
sudo chmod -R +s /srv/walnut/
2017-08-02 21:18:41 +00:00
```
2017-08-02 21:36:18 +00:00
Install OAuth3 API Package
2017-08-02 21:18:41 +00:00
--------------
2017-08-02 21:36:18 +00:00
We need to have a local login system.
2017-08-02 21:18:41 +00:00
2017-08-02 21:36:18 +00:00
For the APIs for that we`ll install the `issuer@oauth3.org` API package and enable it for `api.provider.example.com`:
2017-08-02 21:18:41 +00:00
2017-08-02 21:36:18 +00:00
```
# API packaged for walnut
2017-08-03 01:06:02 +00:00
git clone https://git.daplie.com/OAuth3/org.oauth3.provider.git /srv/walnut/packages/rest/issuer@oauth3.org
2017-08-02 21:18:41 +00:00
pushd /srv/walnut/packages/rest/issuer@oauth3.org/
git checkout v1.2
npm install
popd
2017-08-02 21:36:18 +00:00
# Give permission for this package to provider.example.com
# the api. prefix is omitted because it is always assumed for APIs
2017-08-02 21:18:41 +00:00
echo "issuer@oauth3.org" >> /srv/walnut/packages/client-api-grants/provider.$my_domain
```
2017-08-02 21:36:18 +00:00
*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
2017-08-02 21:18:41 +00:00
```
2017-08-02 21:36:18 +00:00
# Frontend
2017-08-03 01:06:02 +00:00
git clone https://git.daplie.com/OAuth3/org.oauth3.git /srv/walnut/packages/pages/issuer@oauth3.org
2017-08-02 21:36:18 +00:00
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
2017-08-02 21:18:41 +00:00
```
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).
```
2017-08-02 21:36:18 +00:00
vim /srv/walnut/var/$my_domain/config.json
2017-08-02 21:18:41 +00:00
```
```
{ "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
2017-08-03 01:06:02 +00:00
git clone https://git.daplie.com/Daplie/com.example.hello.git /srv/walnut/packages/rest/hello@example.com
2017-08-02 21:18:41 +00:00
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
2017-08-02 21:36:18 +00:00
'''
2017-08-02 21:18:41 +00:00
hello@example.com
2017-08-02 21:36:18 +00:00
'''
2017-08-02 21:18:41 +00:00
```
2017-08-02 21:36:18 +00:00
Setup the Seed App (front-end)
------------------------
2017-08-02 21:18:41 +00:00
Get the Seed App
```bash
pushd /srv/walnut/packages/pages/
2017-08-03 01:06:02 +00:00
git clone https://git.daplie.com/Daplie/seed_example.com.git --branch v1 seed@example.com
2017-08-02 21:18:41 +00:00
pushd seed@example.com/
2017-08-03 01:06:02 +00:00
git clone https://git.daplie.com/OAuth3/oauth3.js.git --branch v1.1 assets/oauth3.org
2017-08-02 21:18:41 +00:00
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
```
2017-08-02 21:36:18 +00:00
You will need to change the authenication provider/issuer URL from `oauth3.org` to the domain you've selected (i.e. `provider.example.com`)
2017-08-02 21:18:41 +00:00
```
vim /srv/walnut/packages/pages/seed@example.com/js/config.js
```
```
{ "azp@oauth3.org": { issuer_uri: 'provider.example.com', client_uri: 'example.com' } }
```
2017-08-02 21:36:18 +00:00
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.