Dapp Deployment Guide DEPRECATED

THIS IS STALE

Please see Beta Getting Started

---

Prerequisites

You must have tested your Dapp (dapp-encouragement in this guide) locally to ensure it will work as you expect.

You will need experience deploying web-based services using a TLS/WebSocket reverse proxy (we use Nginx in these instructions).

Deployment steps

1. Set up a Linux server as described in the Validator Guide. This won't be an actual validator, but it has many of the same system dependencies. Ensure you follow the steps to check out and build the Agoric SDK within the user account in the following step.
2. Create the user account for this Dapp:

sudo adduser dappapi
# Now check out and configure the Agoric SDK.
sudo su dappapi
git clone ...

3. Copy and set up your Dapp's project directory to the user account, such as:

sudo su dappapi
git clone git://github.com/Agoric/dapp-encouragement dapp
cd dapp
agoric install

4. Create /home/dappapi/dapp/start.sh:

cat > start.sh <<\EOF
#! /bin/sh
# Start the Agoric Testnet deployment.
exec agoric start testnet ${1+"$@"}
EOF
# Make executable.
chmod +x start.sh

5. As root, create the systemd service file, /etc/systemd/system/agoric-dapp-api.service:

cat > /etc/systemd/system/agoric-dapp-api.service <<\EOF
[Unit]
Description=Agoric Dapp API server
Requires=network-online.target
After=network-online.target

[Service]
WorkingDirectory=/home/dappapi/dapp
Environment=PATH=/usr/local/bin/:/usr/bin:/bin:/snap/bin:/home/dappapi/go/bin
Restart=on-failure
User=dappapi
Group=dappapi
PermissionsStartOnly=true
ExecStart=/home/dappapi/dapp/start.sh
ExecReload=/bin/kill -HUP $MAINPID
KillSignal=SIGTERM

[Install]
WantedBy=multi-user.target
EOF
# Reload systemd to notice the new file:
systemctl daemon-reload

6. Start the Dapp API service (as root):

systemctl start agoric-dapp-api
# Watch the program start (interrupt after you get `swingset started`):
journalctl -fu agoric-dapp-api

7. Install and instantiate the contract on-chain. Use the public URL for this API server (such as https://mydapp.example.net):

API_PUBLIC_URL=<public URL> API_HOST=127.0.0.1 API_PORT=5000 agoric deploy --allow-unsafe-plugins contract/deploy.js api/deploy.js

8. Test the local API address http://127.0.0.1:5000:

curl http://127.0.0.1:5000

9. Install the TLS certificates for your public URL as /etc/ssl/dapp.{key,pem}:

# Protect the key file.
touch /etc/ssl/dapp.key
chmod 0600 /etc/ssl/dapp.key
cat > /etc/ssl/dapp.key
# Paste your SSL key file here (Control-D to finish)
cat > /etc/ssl/dapp.pem
# Paste your SSL certificate here (Control-D to finish)

9. Set up a reverse proxy, such as Nginx (apt install nginx) from your public TLS URL to http://127.0.0.1:5000 with the following /home/dappapi/dapp.nginx config file (edited to taste):

# Install Nginx.
apt-get install nginx
# Write the config file.
cat > /home/dappapi/dapp.nginx <<\EOF
# this section is needed to proxy web-socket connections
map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
}
# HTTP
server {
  listen 80;
  return 301 https://$host$request_uri;
}
server {
        listen 443 ssl;
        server_name _; # encouragement.testnet.agoric.com;

        ssl_certificate /etc/ssl/dapp.pem;
        ssl_certificate_key /etc/ssl/dapp.key;
        ssl_session_cache  builtin:1000  shared:SSL:10m;
        ssl_protocols  TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
        ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
        ssl_prefer_server_ciphers on;

        location / {
            root /home/dappapi/dapp/ui/dist;
        }
        
        location /api {
            # Use the following if you enabled a separate web server plugin:
            # proxy_pass http://127.0.0.1:5000;
            proxy_pass http://127.0.0.1:8000;
            proxy_http_version 1.1;
            proxy_ssl_server_name on;
            proxy_set_header Upgrade $http_upgrade; #for websockets
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header Host $host;
        }
}
EOF
# Override NGINX configuration
mv /etc/nginx/sites-enabled /etc/nginx/sites-enabled.orig
mkdir /etc/nginx/sites-enabled
ln -s /home/dappapi/dapp.nginx /etc/nginx/sites-enabled/
# Restart NGINX.
systemctl restart nginx

10. Test your Dapp: navigate to your public URL and see what you get!