Skip to content

A local-first personal finance app

Move HTTPS docs to a separate file and add more information (#104)

Jed Foxba06f4dfaa60
diff --git a/docs/Installing/Configuration.md b/docs/Installing/Configuration.md
index 982018c3ca..6a562776d0 100644
--- a/docs/Installing/Configuration.md
+++ b/docs/Installing/Configuration.md
@@ -16,7 +16,7 @@ If you want to Actual to serve over HTTPS, you can set this key to an object wit
- `cert`: The path to the certificate file. (environment variable: `ACTUAL_HTTPS_CERT`)
- any other options from Node’s [`tls.createServer()`](https://nodejs.org/docs/latest-v16.x/api/tls.html#tlscreateserveroptions-secureconnectionlistener), [`tls.createSecureContext()`](https://nodejs.org/docs/latest-v16.x/api/tls.html#tlscreatesecurecontextoptions), or [`http.createServer()`](https://nodejs.org/docs/latest-v16.x/api/http.html#httpcreateserveroptions-requestlistener) functions (optional, most people won’t need to set any of these).
-The value of `key` and `cert` can either be a file path or a string containing the contents of the file. If you use the environment variables, you can replace newlines with `\n` if you can’t put real newlines in your environment variable.
+See [Activating HTTPS](/Installing/HTTPS/) for more information on how to get HTTPS working.
<!-- ## `mode`
diff --git a/docs/Installing/HTTPS.md b/docs/Installing/HTTPS.md
new file mode 100644
index 0000000000..44a5b8a503
--- /dev/null
+++ b/docs/Installing/HTTPS.md
@@ -0,0 +1,24 @@
+---
+title: Activating HTTPS
+---
+
+You’ll need to enable HTTPS on your home server in order to safely use all of Actual’s features. **You don’t need to follow these steps** if you run the server on your own computer and only access it through `localhost`, or if you’re using a cloud provider that handles HTTPS for you. There are a few different ways to get HTTPS to work, depending on what you’d prefer to do.
+
+1. Use a self-signed certificate. This is the easiest way to get HTTPS working, but it will cause your browser to display a warning that the certificate is invalid. Additionally, if anyone gets access to this certificate, they can intercept most secure traffic on your computer.
+ - A command line tool like [mkcert](https://github.com/FiloSottile/mkcert) can automate this process.
+ - Alternately, you can manually generate the certificates. Install OpenSSL for your operating system, then run `openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout selfhost.key -out selfhost.crt` in a terminal to generate the certificate and private key. You’ll need to enter a two-letter country code to get the `.crt` file to be generated, but you can leave the rest of the fields blank (just hit enter at each prompt). Move the `selfhost.key` and `selfhost.crt` files a location accessible to the Actual server.
+2. Connect your server to a domain you control and make it public to the Internet. You could use a tool like [certbot](https://certbot.eff.org) to generate a valid certificate once you have the domain set up.
+3. Use a service like [Tailscale](https://tailscale.com/kb/1153/enabling-https/) or [Caddy](https://caddyserver.com/docs/automatic-https#dns-challenge) that allows you to create a valid HTTPS certificate without having to expose your server to the wider internet.
+
+Once you have the certificate, you’ll need to configure Actual to use it. There are two ways to do this:
+
+1. **Configuring with `config.json`**: Create a `config.json` file in the same folder where you run Actual (or `/data` if you’re using a Docker container). Put the paths to the `.key` and `.crt` files in the file. Note: if you’re using Docker or a similar container environment, make sure the paths are accessible to the container. For example:
+ ```json
+ {
+ "https": {
+ "keyPath": "/data/selfhost.key",
+ "certPath": "/data/selfhost.crt"
+ }
+ }
+ ```
+2. **Configuring with environment variables**: If you can’t easily create new files, you can also configure HTTPS using environment variables. Set the `ACTUAL_HTTPS_KEY` and `ACTUAL_HTTPS_CERT` environment variables to the contents of the `.key` and `.crt` files, respectively. If you’re unable to include newlines in the environment variable values, you can replace any newlines with `\n` and Actual will automatically convert them back to newlines.
diff --git a/docs/Troubleshooting/SharedArrayBuffer.md b/docs/Troubleshooting/SharedArrayBuffer.md
index d3f8a1a7ef..c89bf9e64f 100644
--- a/docs/Troubleshooting/SharedArrayBuffer.md
+++ b/docs/Troubleshooting/SharedArrayBuffer.md
@@ -6,15 +6,7 @@ Actual requires access to a web technology called [`SharedArrayBuffer`](https://
## HTTPS
-Actual must be served over HTTPS for `SharedArrayBuffer` to be enabled. If you’re using a cloud provider, this will usually be done for you. If you’re running the server locally and only accessing it through `localhost`, this requirement doesn’t apply.
-
-If you’re running a local server and accessing it through a domain name, you’ll need to set up HTTPS yourself. There are a few ways to do this:
-
-1. Use a self-signed certificate. This is the easiest way to get HTTPS working, but it will cause your browser to display a warning that the certificate is invalid. Additionally, if anyone gets access to this certificate, they can intercept most secure traffic on your computer. One tool you could use to make such a certificate is [mkcert](https://github.com/FiloSottile/mkcert).
-2. Connect your server to a domain you control and make it public to the Internet. You could use a tool like [certbot](https://certbot.eff.org) to generate a valid certificate once you have the domain set up.
-3. Use a service like [Tailscale](https://tailscale.com/kb/1153/enabling-https/) or [Caddy](https://caddyserver.com/docs/automatic-https#dns-challenge) that allows you to create a valid HTTPS certificate without having to expose your server to the wider internet.
-
-Once you have the certificate, [pass it to Actual using the config file](/Installing/Configuration/#https).
+Actual must be served over HTTPS for `SharedArrayBuffer` to be enabled. If you’re using a cloud provider, this will usually be done for you. See [Activating HTTPS](/Installing/HTTPS/) for more information.
## HTTP Headers
diff --git a/sidebars.js b/sidebars.js
index b16bf6b07f..8b213d00cf 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -63,9 +63,7 @@ const sidebars = {
type: 'category',
label: 'On Your Own Server',
collapsible: false,
- items: [
- 'Installing/Docker',
- ],
+ items: ['Installing/Docker'],
},
{
type: 'category',
@@ -88,12 +86,20 @@ const sidebars = {
'Installing/fly/Fly-persisting',
],
},
- 'Installing/PikaPods',
+ 'Installing/PikaPods',
],
},
],
},
- 'Installing/Configuration',
+ {
+ type: 'category',
+ label: 'Configuring the Server',
+ link: {
+ type: 'doc',
+ id: 'Installing/Configuration',
+ },
+ items: ['Installing/HTTPS'],
+ },
{
type: 'category',
label: 'A Tour of Actual',
@@ -266,7 +272,7 @@ const sidebars = {
items: [
'Advanced/Experimental-Features/goal-templates',
unavailable('Report Budget'),
- unavailable('Account syncing')
+ unavailable('Account syncing'),
],
},
],