Easy-to-administer "pinning" server for Dat. Keeps your dats online while your personal computer is off.

• Easy. Designed for fast setup on linux-based servers and VPSes.
• Useful. Provides the same features as Hashbase but easier to self-host.
• Accessible. Integrates with Beaker and the Dat CLI to add/remove Dats using the Pinning Service API.
• Automatic subdomains.
  • You setup Homebase at a base domain (eg yourdomain.com) and point a wildcard DNS entry to the server.
  • You give your dats a name when you upload them (eg mysite).
  • Homebase gives the dat a subdomain (eg dat://mysite.yourdomain.com).
• Custom domains. Any dat can be given additional custom domain names.
• HTTPS mirroring (optional). Any dat site can be accessed over https at the same domain.
• Let's Encrypt (optional). SSL certificates are fetched automatically.
• Metrics dashboard (optional). Track the stats on your dats.

• Installation (Ubuntu)
• Command Line Flags
• Env Vars
• Guides
  • Setup
  • Port setup
  • DNS records
  • Metrics Dashboard
  • Running Homebase behind Apache or Nginx
• Configuration file
  • directory
  • domain
  • httpMirror
  • webapi
    • webapi.username
    • webapi.password
  • letsencrypt
    • letsencrypt.email
    • letsencrypt.agreeTos
  • ports
    • ports.http
    • ports.https
  • dashboard
    • dashboard.port
  • dats
    • dats.*.url
    • dats.*.name
    • dats.*.otherDomains
  • proxies
    • proxies.*.from
    • proxies.*.to
  • redirects
    • redirects.*.from
    • redirects.*.to

You will need nodejs version 4.9.1 or greater. (Consider using nvm to get setup.)

You'll need to install some build dependencies:

# install build dependencies
sudo apt-get install libtool m4 automake libcap2-bin build-essential

Then install Homebase globally. See this guide if you run into permissions problems.

# install homebase
npm install -g @beaker/homebase

Because Homebase will use privileged ports 80 and 443, you'll need to give nodejs permission to use them. (It's not recommended to run Homebase as super-user.)

# give node perms to use ports 80 and 443
sudo setcap cap_net_bind_service=+ep `readlink -f \`which node\``

If you want to run Homebase manually, you can invoke the command homebase. However, for keeping the daemon running, we recommend pm2.

# install pm2
npm install -g pm2

Next, setup your daemon.

• --config <path> use the config file at the given path instead of the default ~/.homebase.yml. Overrides the value of the HOMEBASE_CONFIG env var.

• HOMEBASE_CONFIG=cfg_file_path specify an alternative path to the config than ~/.homebase.yml
• NODE_ENV=debug|staging|production set to debug or staging to use the lets-encrypt testing servers.

To configure your instance, edit ~/.homebase.yml. You can edit this even if the homebase daemon is running, and it will automatically restart after changes to adopt the new config.

# configure
emacs ~/.homebase.yml

Here is an example config file:

directory: ~/.homebase # where your data will be stored
domain:                # enter your homebase instance's domain here
httpMirror: true       # enables http mirrors of the dats
ports:
  http: 80             # HTTP port for redirects or non-SSL serving
  https: 443           # HTTPS port for serving mirrored content & DNS data
letsencrypt:           # set to false to disable lets-encrypt
  email:               # you must provide your email to LE for admin
  agreeTos: true       # you must agree to the LE terms (set to true)
dashboard:             # set to false to disable
  port: 8089           # port for accessing the metrics dashboard

# enable publishing to Homebase from Beaker & Dat-CLI
webapi:                # set to false to disable
  username:            # the username for publishing from Beaker/Dat-CLI
  password:            # the password for publishing from Beaker/Dat-CLI

# enter your pinned dats here
dats:
  - url:               # URL of the dat to be pinned
    name:              # the name of the dat (sets the subdomain)
    otherDomains:      # (optional) the additional domains

# enter any proxied routes here
proxies:
  - from:              # the domain to accept requests from
    to:                # the domain (& port) to target

# enter any redirect routes here
redirects:
  - from:              # the domain to accept requests from
    to:                # the domain to redirect to

You'll want to configure the following items:

• Domain. Set the domain: field to the top-level domain name of your Homebase instance. New archives will be hosted under its subdomains.
• Web API. Set a username and password on the Web API if you want to publish to your Homebase using Beaker or the Dat CLI.
• Let's Encrypt. This is required for accessing your archives with domain names. You'll need to provide your email address so that Let's Encrypt can warn you about expiring certs, or other issues. (Set this to false if you are running Homebase behind a proxy like Apache or Nginx.)
• Dats. Add the archives that you want hosted. Each one will be kept online and made available at dat://{name}.yourdomain.com. The otherDomains field is optional, and can take 1 or more additional domains for hosting the archive at. You can also add & remove archives using Beaker or the Dat CLI via the Web API.

Here's an example dat with multiple domains. If the Homebase instance is hosted at yourdomain.com, then this dat would be available at dat://mysite.yourdomain.com, dat://mysite.com, and dat://my-site.com. (Don't forget to setup the DNS records!)

dats:
  - url: dat://1f968afe867f06b0d344c11efc23591c7f8c5fb3b4ac938d6000f330f6ee2a03/
    name: mysite
    otherDomains:
      - mysite.com
      - my-site.com

If your Homebase is running on ports 80/443, and you have other Web servers running on your server, you might need Homebase to proxy to those other servers. You can do that with the proxies config. Here's an example proxy rule:

proxies:
  - from: my-proxy.com
    to: http://localhost:8080

Sometimes you need to redirect from old domains to new ones. You can do that with the redirects rule. Here's an example redirect rule:

redirects:
  - from: my-old-site.com
    to: https://my-site.com

Now you're ready to start Homebase! If you want to run Homebase manually, you can invoke the command homebase. However, for keeping the daemon running, we recommend pm2.

# start homebase
pm2 start homebase

To stop the daemon, run

# stop homebase
pm2 stop homebase

For Homebase to work correctly, you need to be able to access port 80 (http), 443 (https), and 3282 (dat). Your firewall should be configured to allow traffic on those ports.

If you get an EACCES error on startup, you either have a process using the port already, or you lack permission to use the port. Try lsof -i tcp:80 or lsof -i tcp:443 to see if there are any processes bound to the ports you need.

If the ports are not in use, then it's probably a permissions problem. We recommend using the following command to solve that:

# give node perms to use ports 80 and 443
sudo setcap cap_net_bind_service=+ep `readlink -f \`which node\``

This will give nodejs the rights to use ports 80 and 443. This is preferable to running homebase as root, because that carries some risk of a bug in homebase allowing somebody to control your server.

You will need to create A records for all of the domains you use. For the subdomains, you can use a wildcard domain.

Homebase has built-in support for Prometheus, which can be visualized by Grafana.

Homebase exposes its metrics at port 8089. Prometheus periodically scrapes the metrics, and stores them in a database. Grafana provides a nice dashboard. It's a little daunting at first, but setup should be relatively painless.

Follow these steps:

1. Install Prometheus on your server.
2. Install Grafana on your server.
3. Update the prometheus.yml config.
4. Start prometheus and grafana.
5. Login to grafana.
6. Add prometheus as a data source to grafana. (It should be running at localhost:9090.)
7. Import this grafana dashboard.

Your prometheus.yml config should include have the scrape_configs set like this:

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
  - job_name: 'homebase'
    static_configs:
      - targets: ['localhost:8089']

If you are running Homebase on a server that uses Apache or Nginx, you may need to change your config to disable HTTPS. For instance, if you're using nginx and proxying to port 8080, update your config to disable Let's Encrypt and to set the http port:

letsencrypt: false
ports:
  http: 8080

You will need to add all domains to your Nginx/Apache config.

The fields in detail.

The directory where homebase will store your Dat archive's files. Defaults to ~/.homebase.

The DNS domain of your homebase instance.

Set to true to provide https mirroring of your Dat archives. Defaults to true.

Set to false to disable the Pinning Service API which enables publishing to Homebase with Beaker and the Dat CLI. Defaults to false.

# enable publishing to Homebase from Beaker & Dat-CLI
webapi:                # set to false to disable
  username:            # the username for publishing from Beaker/Dat-CLI
  password:            # the password for publishing from Beaker/Dat-CLI

Sets the username for your pinning service API.

Sets the password for your pinning service API.

Set to false to disable Lets Encrypt's automatic SSL certificate provisioning. Defaults to false.

letsencrypt:           # set to false to disable lets-encrypt
  email:               # you must provide your email to LE for admin
  agreeTos: true       # you must agree to the LE terms (set to true)

The email to send Lets Encrypt notices to.

Do you agree to the terms of service of Lets Encrypt? (Required, must be true)

Contains the ports for http and https.

ports:
  http: 80             # HTTP port for redirects or non-SSL serving
  https: 443           # HTTPS port for serving mirrored content & DNS data

The port to serve the HTTP sites. Defaults to 80.

HTTP automatically redirects to HTTPS.

The port to serve the HTTPS sites. Defaults to 443.

Set to false to disable the prometheus metrics dashboard. Defaults to false.

dashboard:             # set to false to disable
  port: 8089           # port for accessing the metrics dashboard

The port to serve the prometheus metrics dashboard. Defaults to 8089.

A listing of the Dat archives to host.

You'll need to configure the DNS entry for the hostname to point to the server. For instance, if using site.yourhostname.com, you'll need a DNS entry pointing site.yourhostname.com to the server.

dats:
  - url: dat://1f968afe867f06b0d344c11efc23591c7f8c5fb3b4ac938d6000f330f6ee2a03/
    name: mysite
    otherDomains:
      - mysite.com
      - my-site.com

The Dat URL of the site to host. Should be a 'raw' dat url (no DNS hostname). Example values:

868d6000f330f6967f06b3ee2a03811efc23591afe0d344cc7f8c5fb3b4ac91f
dat://1f968afe867f06b0d344c11efc23591c7f8c5fb3b4ac938d6000f330f6ee2a03/

The name of the Dat archive. Must be unique on the Homebase instance. The archive will be hosted at {name}.yourhostname.com. You'll need to configure the DNS entry for the hostname to point to the server.

Additional domains of the Dat archive. Can be a string or a list of strings. Each string should be a domain name. Example values:

mysite.com
foo.bar.edu
best-site-ever.link

A listing of domains to proxy. Useful when your server has other services running that you need available.

proxies:
  - from: my-proxy.com
    to: http://localhost:8080

The domain to proxy from. Should be a domain name. Example values:

mysite.com
foo.bar.edu
best-site-ever.link

The protocol, domain, and port to proxy to. Should be an origin (scheme / hostname / port). Example values:

https://mysite.com/
http://localhost:8080/
http://127.0.0.1:123/

A listing of domains to redirect.

redirects:
  - from: my-old-site.com
    to: https://my-site.com

The domain to redirect from. Should be a domain name. Example values:

mysite.com
foo.bar.edu
best-site-ever.link

The base URL to redirect to. Should be an origin (scheme / hostname / port). Example values:

https://mysite.com/
http://localhost:8080/
http://127.0.0.1:123/