[{"_1":2,"_175":-5,"_176":-5},"loaderData",{"_3":4,"_17":18,"_25":26,"_150":151},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","routes/_layout",{"_19":-5,"_20":21,"_22":21,"_23":11,"_24":21},"username","isAskGordonEnabled",true,"isUsingNewTemplate","showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_27":28,"_29":-5,"_30":11,"_31":11,"_32":33,"_34":35,"_36":-5,"_37":11,"_38":39,"_88":-5,"_89":90,"_139":-5,"_140":11,"_141":21,"_142":11,"_143":-5,"_144":11,"_145":-5,"_146":147,"_148":91,"_149":-7},"canonicalUrl","https://hub.docker.com/r/telyn/homebase/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","telyn","reponame","homebase","cloudBuildSource","isAutobuildsAvailable","repo",{"_40":41,"_42":43,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":55,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":74,"_79":11,"_80":81,"_85":33,"_86":87},"categories",[],"content_types",[44],"image","date_registered","2019-04-24T18:40:10.161452Z","description","beaker homebase - Self-deployable tool for seeding dat:// websites","is_private","last_updated","2020-03-23T16:17:45.305351Z","last_modified","2024-10-16T13:48:34.145251Z","media_types",[56],"application/vnd.docker.container.image.v1+json","name","pull_count",546,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","# homebase\n\n`homebase` is a self-deployable tool for managing websites published with the [Dat protocol](https://datprotocol.com).\n\n`homebase` is for you if:\n\n- You're comfortable with some server administration (or want to learn!)\n- You want to keep your dat:// website/s online\n- You want to publish your dat:// website/s to a domain name\n\nDon't want to run `homebase` yourself? You can still make sure your dat:// website stays online by using a service like [Hashbase](https://hashbase.io). Or maybe you can convince a generous friend to run an instance of `homebase` using its built-in [Pinning Service APIs](#example-seed-multiple-websites-enable-web-api).\n\n## Table of contents\n\n- [Features](#features)\n- [Install](#install)\n- [Running homebase](#running-homebase)\n- [Examples](#examples)\n- [Configuration](#configuration)\n- [Advanced examples](#advanced-examples)\n- [Troubleshooting](#troubleshooting)\n- [Support](#support)\n- [Web API Clients](#web-api-clients)\n- [Changelog](#changelog)\n\n## Features\n\n- Keeps dat:// websites online\n- Publishes dat:// websites to DNS shortnames\n- Mirrors dat:// websites to https://\n- Provisions and manages HTTPS with [Let's Encrypt](https://letsencrypt.org)\n- Provides optional [Pinning Service API](https://www.datprotocol.com/deps/0003-http-pinning-service-api/) endpoints\n\n## Install\n\nIf you already have [Node.js](https://nodejs.org) (8.0+) and [npm](https://npmjs.com) installed on your server, get started by installing Homebase with npm or [npx](https://github.com/zkat/npx).\n\n```bash\nnpm install -g @beaker/homebase\n```\n\nOtherwise, install Node.js and npm first:\n\n- [Install Node.js](https://nodejs.org/en/download/)\n- [nvm](https://github.com/creationix/nvm) for managing Node versions\n- [Fixing npm permissions problems](https://docs.npmjs.com/getting-started/fixing-npm-permissions)\n\nHaving trouble installing? See [Troubleshooting](#troubleshooting).\n\n## Running homebase\n\nTo run `homebase` manually, simply invoke the `homebase` command:\n\n```bash\nhomebase\n```\n\nTo keep `homebase` running, you'll need to daemonize it. We like using [pm2](https://www.npmjs.com/package/pm2).\n\n```bash\n# install pm2\nnpm i -g pm2\n\n# start homebase with pm2\npm2 start homebase\n```\n\nTo stop the daemon, run:\n\n```\n# stop homebase\npm2 stop homebase\n```\n\n### Command line flags\n\n- `--config `\n - Use the config file at the given path instead of the default `~/.homebase.yml`. Overrides the value of the HOMEBASE_CONFIG env var.\n\n### Environment variables\n\n- `HOMEBASE_CONFIG=cfg_file_path`\n - Specify an alternative path to the config than `~/.homebase.yml`\n- `NODE_ENV=debug|staging|production`\n - Set to debug or staging to use the Let's Encrypt testing servers.\n\n## Examples\n\n`homebase` uses a [configuration file](#configuration-file) (`~/.homebase.yml` by default) for managing its behavior. These examples show various configurations.\n\n[See all configuration options](#configuration)\n\n### Example: set up a website with a domain name and HTTP mirroring\n\nThis configuration file will \"seed\" or \"pin\" the files at `dat://123...456`, publish those files to `dat://alice.com`, and mirror them to `https://alice.com`.\n\nThis example uses a domain name, so in order for the domain name to resolve correctly, you'll need to update your DNS configuration first. In this case, you could set an `A` record that points to the `homebase` server's IP address.\n\n```yaml\ndats:\n - url: dat://123...456\n domains:\n - alice.com\nhttpMirror: true\nletsencrypt:\n email: alice@mail.com\n agreeTos: true\n\n```\n\n### Example: seed multiple websites, with no domain names\n\nThis configuration simply \"seeds\" or \"pins\" the files at `dat://123...456` and `dat:///456...789`. No domain name is required for this configuration.\n\n```yaml\ndats:\n - url: dat://123...456\n - url: dat://456...789\n```\n\n### Example: seed multiple websites, enable Web API\n\nIn addition to being used to manage a website, `homebase` can be used with more specific configurations, like providing a mini-pinning service for a group of friends.\n\nThis example enables the [Pinning Service API](https://www.datprotocol.com/deps/0003-http-pinning-service-api/), which makes it possible for you (and maybe a few friends!) to publish to your `homebase` instance with the [Dat CLI](https://npm.im/dat), or any client that supports the Pinning Service API. There are plans to support publishing from within [Beaker](https://beakerbrowser.com) in the future.\n\nIf you choose to use a domain name for your API endpoint, be sure to configure your DNS to point to your `homebase` server.\n\n[See full `webapi` reference](#webapi)\n\n```yaml\n# enable publishing to `homebase` from Beaker and the Dat CLI\nwebapi: # set to false to disable\n domain: # the domain name for the web API (optional)\n username: # the username for publishing from Beaker or the Dat CLI\n password: # the password for publishing from Beaker or the Dat CLI\n```\n\n## Configuration\n\n- [Configuration file](#configuration-file)\n- [dashboard](#dashboard)\n - [dashboard.port](#dashboardport)\n- [dats](#dats)\n - [dats.*.url](#datsurl)\n - [dats.*.domains](#datsdomains)\n - [dats.*.name](#datsname)\n - [dats.*.otherDomains](#datsotherdomains)\n- [directory](#directory)\n- [domain](#domain)\n- [httpMirror](#httpmirror)\n- [letsencrypt](#letsencrypt)\n - [letsencrypt.email](#letsencryptemail)\n - [letsencrypt.agreeTos](#letsencryptagreetos)\n- [ports](#ports)\n - [ports.http](#portshttp)\n - [ports.https](#portshttps)\n- [proxies](#proxies)\n - [proxies.*.from](#proxiesfrom)\n - [proxies.*.to](#proxiesto)\n- [redirects](#redirects)\n - [redirects.*.from](#redirectsfrom)\n - [redirects.*.to](#redirectsto)\n- [webapi](#webapi)\n - [webapi.username](#webapiusername)\n - [webapi.password](#webapipassword)\n - [webapi.domain](#webapidomain)\n\n### Configuration file\n\n`homebase` uses `~/.homebase.yml` as its default configuration file. You can specify an alternative config file using a [command line flag](#command-line-flags) or an [environment variable](#environment-variables).\n\n\n```yaml\ndirectory: ~/.homebase # where your data will be stored\nhttpMirror: true # enables HTTP mirroring\nports:\n http: 80 # HTTP port for redirects or non-TLS serving\n https: 443 # HTTPS port for serving mirrored content and DNS data\nletsencrypt: # set to false to disable Let's Encrypt\n email: # you must provide your email to LE for admin\n agreeTos: true # you must agree to the LE terms (set to true)\ndashboard: # set to false to disable\n port: 8089 # port for accessing the metrics dashboard\n\n# enable publishing to homebase from Beaker and the Dat CLI\nwebapi: # set to false to disable\n domain: # enter your web API's domain here (optional, unless Let's Encrypt TLS is wanted on the web API)\n username: # the username for publishing from Beaker or the Dat CLI\n password: # the password for publishing from Beaker or the Dat CLI\n\n# enter your pinned dats here\ndats:\n - url: # URL of the dat to be pinned\n domains: # (optional) the domains of the dat\n\n# enter any proxied routes here\nproxies:\n - from: # the domain to accept requests from\n to: # the domain (& port) to target\n\n# enter any redirect routes here\nredirects:\n - from: # the domain to accept requests from\n to: # the domain to redirect to\n```\n\n### dashboard\n\nDefault `false`\n\nSet to `true` to enable the [Prometheus metrics dashboard](#example-using-a-metrics-dashboard).\n\n```yaml\ndashboard: # set to false to disable\n port: 8089 # port for accessing the metrics dashboard\n```\n\n#### dashboard.port\n\nDefault: `8089`\n\nThe port to serve the [Prometheus metrics dashboard](#example-using-a-metrics-dashboard).\n\n### dats\n\nA listing of the Dat archives to seed.\n\n```yaml\ndats:\n - url: dat://1f968afe867f06b0d344c11efc23591c7f8c5fb3b4ac938d6000f330f6ee2a03/\n domains:\n - mysite.com\n - my-site.com\n```\n\n#### dats.*.url\n\nThe Dat URL of the site to host. Should be a 'raw' dat url (no DNS hostname).\n\nExample values:\n\n```\n# raw key\n1f968afe867f06b0d344c11efc23591c7f8c5fb3b4ac938d6000f330f6ee2a03\n\n# URL with trailing slash\ndat://1f968afe867f06b0d344c11efc23591c7f8c5fb3b4ac938d6000f330f6ee2a03/\n\n# URL with no trailing slash\ndat://1f968afe867f06b0d344c11efc23591c7f8c5fb3b4ac938d6000f330f6ee2a03\n```\n\n#### dats.*.domains\n\nAdditional domains of the Dat archive. Can be a string or a list of strings. Each string should be a domain name.\n\nTo use `dats.*.domains`, you'll first need to configure the DNS entry for your domain name to point to your server. For instance, to point `alice.com` with `homebase`, you'll need to update your DNS configuration to point `alice.com` to your homebase server's IP address.\n\nExample values:\n\n```\nmysite.com\nfoo.bar.edu\nbest-site-ever.link\n```\n\n#### dats.*.name\n\n**DEPRECATED**. See the [v2.0.0 migration guide](#migrating-to-v2-0-0).\n\nThe name of the Dat archive. Sets a subdomain relative to the Web API domain, similar to the way that [Hashbase](https://hashbase.io) does. Must be unique on the `homebase` instance.\n\n#### dats.*.otherDomains\n\n**DEPRECATED**. Use the [domains field](#dats-domains) instead.\n\nAdditional domains of the Dat archive. Can be a string or a list of strings. Each string should be a domain name. Example values:\n\n```\nmysite.com\nfoo.bar.edu\nbest-site-ever.link\n```\n\n### directory\n\nDefault: `~/.homebase`\n\nThe directory where `homebase` will store your Dat archive's files.\n\n### domain\n\n**DEPRECATED**. See the [v2.0.0 migration guide](#migrating-to-v2-0-0).\n\nThe DNS domain of your homebase instance.\n\n### httpMirror\n\nDefault: `false`\n\nSet to `true` to provide https mirroring of your Dat archives.\n\n### letsencrypt\n\nDefault: `false`\n\nSet to `true` to enable Lets Encrypt's automatic TLS certificate provisioning.\n\n```yaml\nletsencrypt: # set to false to disable Let's Encrypt\n email: # you must provide your email to LE for admin\n agreeTos: true # you must agree to the LE terms (set to true)\n```\n\n#### letsencrypt.email\n\nThe email to send Let's Encrypt notices to.\n\n#### letsencrypt.agreeTos\n\nDo you agree to the [terms of service of Lets Encrypt](https://letsencrypt.org/repository/)? Required, must be true.\n\n### ports\n\nThe ports for HTTP and HTTPS.\n\n```yaml\nports:\n http: 80 # HTTP port for redirects or non-TLS serving\n https: 443 # HTTPS port for serving mirrored content and DNS data\n```\n\n#### ports.http\n\nDefault: `80`\n\nThe port for serving HTTP sites.\n\nHTTP automatically redirects to HTTPS.\n\n#### ports.https\n\nDefault: `443`\n\nThe port for serving HTTPS sites.\n\n### proxies\n\nA listing of domains to proxy. Useful when your server has other services running that you need available.\n\n```yaml\nproxies:\n - from: my-proxy.com\n to: http://localhost:8080\n```\n\n#### proxies.*.from\n\nThe domain to proxy from. Should be a domain name.\n\nExample values:\n\n```\nmysite.com\nfoo.bar.edu\nbest-site-ever.link\n```\n\n#### proxies.*.to\n\nThe protocol, domain, and port to proxy to. Should be an [origin](https://en.wikipedia.org/wiki/Same-origin_policy#Origin_determination_rules).\n\nExample values:\n\n```\nhttps://mysite.com/\nhttp://localhost:8080/\nhttp://127.0.0.1:123/\n```\n\n### redirects\n\nA listing of domains to redirect.\n\n```yaml\nredirects:\n - from: my-old-site.com\n to: https://my-site.com\n```\n\n#### redirects.*.from\n\nThe domain to redirect from. Should be a domain name.\n\nExample values:\n\n```\nmysite.com\nfoo.bar.edu\nbest-site-ever.link\n```\n\n#### redirects.*.to\n\nThe base URL to redirect to. Should be an [origin](https://en.wikipedia.org/wiki/Same-origin_policy#Origin_determination_rules).\n\nExample values:\n\n```\nhttps://mysite.com/\nhttp://localhost:8080/\nhttp://127.0.0.1:123/\n```\n\n### webapi\n\nDefault: `false`\n\nSet to `true` to enable the [Pinning Service API](https://www.datprotocol.com/deps/0003-http-pinning-service-api/), which enables publishing to Homebase with [Beaker](https://beakerbrowser.com), the [Dat CLI](https://npm.im/dat), or any other client that supports the Pinning Service API.\n\n```yaml\n# enable publishing to `homebase` from Beaker and the Dat CLI\nwebapi: # set to false to disable\n domain: # the domain of the web api (optional)\n username: # the username for publishing from Beaker or the Dat CLI\n password: # the password for publishing from Beaker or the Dat CLI\n```\n\n#### webapi.username\n\nThe username for your pinning service API.\n\n#### webapi.password\n\nThe password for your pinning service API.\n\n#### webapi.domain\n\nThe DNS domain of your homebase Web API. Optional, but required if you want Let's Encrypt to provide your Web API with a TLS certificate.\n\n## Advanced examples\n\n### Example: proxies\n\nIf your `homebase` instance 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:\n\n[See full `proxies` reference](#proxies)\n\n```yaml\nproxies:\n - from: my-proxy.com\n to: http://localhost:8080\n```\n\n### Example: redirecting requests\n\nSometimes you need to redirect old domains to new ones. You can do that with the `redirects` rule. Here's an example redirect rule:\n\n[See full `redirects` reference](#redirects)\n\n```yaml\nredirects:\n - from: my-old-site.com\n to: https://my-site.com\n```\n\n### Example: using a metrics dashboard\n\n`homebase` has built-in support for [Prometheus](https://prometheus.io), which can be visualized with [Grafana](http://grafana.org/).\n\n![./grafana-screenshot.png](./grafana-screenshot.png)\n\nHomebase exposes its metrics at port 8089. Prometheus periodically scrapes the metrics and stores them in a database. Grafana uses those metrics and provides a provides a nice dashboard visualization. It's a little daunting at first, but setup should be relatively painless.\n\nSteps:\n\n 1. [Install Prometheus](https://prometheus.io/download/) on your server\n 2. [Install Grafana](http://grafana.org/download/) on your server\n 3. Update the `prometheus.yml` config\n 4. Start Prometheus and Grafana\n 5. Login to Grafana\n 6. Add Prometheus as a data source to Grafana (it should be running at `localhost:9090`\n 7. Import [this Grafana dashboard](./grafana-dashboard.json)\n\nYour `prometheus.yml` config should include have the `scrape_configs` option set like this:\n\n```yaml\nscrape_configs:\n - job_name: 'prometheus'\n static_configs:\n - targets: ['localhost:9090']\n - job_name: 'homebase'\n static_configs:\n - targets: ['localhost:8089']\n```\n\n### Example: running homebase behind Apache or Nginx\n\nIf you're 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:\n\n```yaml\nletsencrypt: false\nports:\n http: 8080\n```\n\nYou will need to add all domains to your Nginx/Apache config.\n\n### Example: running homebase in a docker container\n\n1. Install [Docker](http://docker.com/). If you're on Linux, remember to [configure Docker to start on boot](https://docs.docker.com/install/linux/linux-postinstall/). Don't know of the equivalent for other systems.\n\n2. Clone the project. Edit `.homebase.yml` according to your needs. Most importantly: **Change username and password**. \nIf you don't want to think of a username and a password, just use [this](https://stackoverflow.com/a/1349426/6690391) but **increase the length**.\n\n3. In the project root, run this command:\n\n```\ndocker build -t homebase:latest . && docker run -d --name=homebase --restart=always -p 80:80 -p 443:443 -p 3282:3282 homebase:latest\n```\n\n**Notes:** \n1. Not an expert in Docker security or configuration. \n2. if you have Beaker on the same machine, you may want to change the dat port `-p 3282:3282` to something like `-p 9999:3282`. \n3. To debug the running container:\n - Run `docker ps -a` to see the container running status. \n - Run `docker logs homebase` to see the logs.\n - Run `docker exec -it homebase sh` to get into a terminal.\n4. Didn't think about how you'd install a newer version of homebase while keeping the old configuration and data.\n\n## Troubleshooting\n\n### Installing build dependencies\n\nWhen installing `homebase`, you may need to install additional build dependencies:\n\n```\nsudo apt-get install libtool m4 automake libcap2-bin build-essential\n```\n\n### Port setup (EACCES error)\n\nFor `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.\n\nIf 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.\n\nIf the ports are not in use, then it's probably a permissions problem. We recommend using the following command to solve that:\n\n```\n# give node perms to use ports 80 and 443\nsudo setcap cap_net_bind_service=+ep `readlink -f \\`which node\\``\n```\n\nThis 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.\n\n## Support\n\n`homebase` is built by the [Beaker Browser team](https://beakerbrowser.com/about). Become a backer and help support the development of an open, friendly, and fun Web. You can help us continue our work on Beaker, [hashbase.io](https://hashbase.io), `homebase`, and more. Thank you!\n\n[Become a backer](https://opencollective.com/beaker)\n\n

telyn/homebase

Tags for telyn/homebase