Skip to content

A local-first personal finance app

fix: mention ACTUAL_DATA_DIR is now dataDar in config (#758)

fritz6ae701b38984
diff --git a/docs/actual-server-repo-move.md b/docs/actual-server-repo-move.md
index 8e3367cbce..9d713c3402 100644
--- a/docs/actual-server-repo-move.md
+++ b/docs/actual-server-repo-move.md
@@ -1,6 +1,6 @@
# Actual Server repository move
-In February 2025 the actual-server repository will be merged into the Actual repository.
+In February 2025 the actual-server repository was merged into the Actual repository.
The reasons for this change are as follows:
@@ -10,47 +10,54 @@ The reasons for this change are as follows:
- Ensures code consistency and reduces the maintenance burden.
- Simplifies the release process
-### Questions:
+### Questions
- **Q.** _I use Docker Hub/Github's container registry, how do I stay up to date?_
**A.** We will continue to push images to [Docker Hub](https://hub.docker.com/r/actualbudget/actual-server) and [Github's container registry](https://ghcr.io/actualbudget/actual) as usual.
-
- **Q.** _I build the docker image locally, can I still do that?_
- **A.** All of the docker files are still available. To build the sync server locally you can use the ``` sync-server.Dockerfile``` located in the root of the repository. The ``` docker-compose.yml ``` is located in the ```/packages/sync-server``` directory.
-
+ **A.** All of the docker files are still available. To build the sync server locally you can use the `sync-server.Dockerfile` located in the root of the repository. The `docker-compose.yml` is located in the `/packages/sync-server` directory.
- **Q.** _I [Build from source](https://actualbudget.org/docs/install/build-from-source). How do I keep up to date?_
**A.** Below are steps to clone the updated setup and then migrate your existing data:
-
+
(If you are on Windows, you'll need to install [Git Bash](https://git-scm.com/download).)
1. Open Bash, then Clone the [Actual repository](https://github.com/actualbudget/actual). You can use the following command:
+
```
git clone https://github.com/actualbudget/actual.git
```
+
2. Navigate to the Actual project root directory:
+
```
cd actual
```
+
3. Install the required dependencies for the server:
+
```
yarn install
```
+
4. Build the server:
+
```
yarn build:server
```
- 5. If you have a [config.json](https://actualbudget.com/docs/config/) file you will need to copy it into the following directory:
+
+ 5. If you have a [config.json](docs/config/) file you will need to copy it into the following directory:
+
```
packages/sync-server
```
- 6. Copy over the data from your `actual-server` directory (`user-files`, `server-files`, and `.migrate`) into the `packages/sync-server` directory.
- 7. Run the server with:
+
+ You may need to make some adjustments (e.g., `ACTUAL_DATA_DIR` becomes `dataDir`), please refer to [troubleshooting the server](docs/troubleshooting/server.md) for some help 6. Copy over the data from your `actual-server` directory (`user-files`, `server-files`, and `.migrate`) into the `packages/sync-server` directory. 7. Run the server with:
+
```
yarn start:server
```
-
diff --git a/docs/config/https.md b/docs/config/https.md
index 81490d2bff..427e31011d 100644
--- a/docs/config/https.md
+++ b/docs/config/https.md
@@ -11,33 +11,38 @@ There are two methods to do this and both refer to not exposing Actual on the in
### Use a self-signed certificate
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 to a location accessible to the Actual server.
+
+- 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 to a location accessible to the Actual server.
### Obtain a certificate without exposing to the internet
+
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.
## 2. Configure Actual to use the certificate
+
Once you have the certificate, you’ll need to configure Actual to use it. There are two methods to do this:
-### Configuring with `config.json`:
-Create a `config.json` file in the same folder where you run the Actual Sync Server. If you are [building from source](https://actualbudget.com/docs/install/build-from-source) this will be in ```packages/sync-server/```. Put the paths to the `.key` and `.crt` files in the config file. Note: if you’re using Docker or a similar container environment, make sure the paths are accessible to the container.
+### Configuring with `config.json`
+
+Create a `config.json` file in the same folder where you run the Actual Sync Server. If you are [building from source](docs/install/build-from-source) this will be in `packages/sync-server/`. Put the paths to the `.key` and `.crt` files in the config file. Note: if you’re using Docker or a similar container environment, make sure the paths are accessible to the container.
If using a Docker container, this folder is `/data` within the container. If you mounted a volume for the container, the folder on the host where `/data` is mounted is where you can place the `config.json` file.
`config.json`:
- ```json
- {
- "https": {
- "key": "/data/selfhost.key",
- "cert": "/data/selfhost.crt"
- }
- }
- ```
+```json
+{
+ "https": {
+ "key": "/data/selfhost.key",
+ "cert": "/data/selfhost.crt"
+ }
+}
+```
-If using MacOS/*nix based systems
+If using MacOS/\*nix based systems
in terminal paste the following. This will create the `config.json` in the current directory
+
```zsh
cat <<"EOF" | tee config.json
{
@@ -48,19 +53,24 @@ cat <<"EOF" | tee config.json
}
EOF
```
-### Configuring with environment variables:
+
+### 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.
-### Configuring the Desktop App:
+### Configuring the Desktop App
+
To configure the desktop app, follow these steps on the _Where's the server?_ screen.
1. Enter your server URL and click OK.
2. If you see an error message asking you to select your certificate, choose the appropriate certificate and try again.
**Note:** If you have generated your certificate using [mkcert](https://github.com/FiloSottile/mkcert), specify the root CA certificate - not the certificate your server is pointing to. To do this:
-1. Run the command ```mkcert -CAROOT``` to find the directory of the root certificate.
-2. Navigate to that directory to locate the ```rootCA.pem``` certificate
-3. Specify the ```rootCA.pem``` certificate in the desktop app.
-## 3. Test HTTPS!
+1. Run the command `mkcert -CAROOT` to find the directory of the root certificate.
+2. Navigate to that directory to locate the `rootCA.pem` certificate
+3. Specify the `rootCA.pem` certificate in the desktop app.
+
+## 3. Test HTTPS
+
Once you have acquired a certificate and configured Actual to use it, attempt to access your instance ensuring you are using `https`. It is recommended to also either re-enter the URL to your server or make a new tab/window instead of refreshing the page where you saw the error.
diff --git a/docs/config/index.md b/docs/config/index.md
index 841b170fd9..0dfdbbac62 100644
--- a/docs/config/index.md
+++ b/docs/config/index.md
@@ -2,15 +2,19 @@
title: Configuring the Server
---
-When it starts up, Actual looks for an optional `config.json` file in the same directory as the sync-server's `package.json`. If you are [building from source](https://actualbudget.com/docs/install/build-from-source) this will be in ```packages/sync-server/```. If present, any keys you define there will override the default values. All values can also be specified as environment variables, which will override the values in the `config.json` file.
+When it starts up, Actual looks for an optional `config.json` file in the same directory as the sync-server's `package.json`. If you are [building from source](docs/install/build-from-source) this will be in `packages/sync-server/`. If present, any keys you define there will override the default values. All values can also be specified as environment variables, which will override the values in the `config.json` file.
+
+:::caution
+Observe that the environmental variables do not map 1:1 to keys in the config.json file. In case of doubt, check the source schema at [/packages/sync-server/src/load-config.js](https://github.com/actualbudget/actual/blob/45530638feaacf74c28fddb846ae91170a99d94e/packages/sync-server/src/load-config.js#L43)
+:::
:::info
-Running into issues with your configuration not being interpreted correctly? Check out our documentation for [troubleshooting the server](../troubleshooting/server.md) for information on how to enable debug logging to track down the issue.
+Running into issues with your configuration not being interpreted correctly? Check out our documentation for [troubleshooting the server](docs/troubleshooting/server.md) for information on how to enable debug logging to track down the issue.
:::
-## `ACTUAL_DATA_DIR`
+## `ACTUAL_DATA_DIR` (config.json: `dataDir`)
This is where the server stores the budget data files (and configurations unless `ACTUAL_CONFIG_PATH` is set).
@@ -18,7 +22,6 @@ By default, the server will use the `/data` directory if it exists, or the curre
See also sections on `userFiles` and `serverFiles`.
-
## `ACTUAL_CONFIG_PATH`
This is the path to the config file. If not specified, the server will look for a `config.json` file in the
@@ -74,7 +77,6 @@ The server will put an `account.sqlite` file in this directory, which will conta
See the `ACTUAL_DATA_DIR` section above to override the data folder location.
-
## `userFiles`
The server will put all the budget files in this directory as binary blobs. If not specified, the server will use either `/data/user-files` (if `/data` exists) or the `user-files` directory in the same directory as the `package.json`. (environment variable: `ACTUAL_USER_FILES`)
@@ -89,10 +91,11 @@ If you’re providing a custom frontend, make sure you provide an `index.html` i
## `loginMethod`
-Change the default authentication method for Actual (environment variable: `ACTUAL_LOGIN_METHOD`). The valid values are:
-* `"password"` (default) - This is standard password authentication
-* `"header"` - Use the HTTP header `x-actual-password` to automatically login. This is for advanced use and if not done correctly could have security implications.
-* `"openid"` - OpenId auth (in preview)
+Change the default authentication method for Actual (environment variable: `ACTUAL_LOGIN_METHOD`). The valid values are:
+
+- `"password"` (default) - This is standard password authentication
+- `"header"` - Use the HTTP header `x-actual-password` to automatically login. This is for advanced use and if not done correctly could have security implications.
+- `"openid"` - OpenId auth (in preview)
## `allowedLoginMethods`
@@ -102,7 +105,7 @@ If you wish to restrict the server from accepting certain login methods, you sho
## `trustedProxies`
-Updates the servers request forwarding trust to remove known proxy IPs from the client IP list. This helps identify the client IP for things like rate limiting. This defaults to known internal IP ranges: `[10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7, ::1/128]` (environment variable: `ACTUAL_TRUSTED_PROXIES`, comma separated string).
+Updates the servers request forwarding trust to remove known proxy IPs from the client IP list. This helps identify the client IP for things like rate limiting. This defaults to known internal IP ranges: `[10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7, ::1/128]` (environment variable: `ACTUAL_TRUSTED_PROXIES`, comma separated string).
## `trustedAuthProxies`
diff --git a/docs/config/oauth-auth.md b/docs/config/oauth-auth.md
index 3ce6a1fe96..4486bef627 100644
--- a/docs/config/oauth-auth.md
+++ b/docs/config/oauth-auth.md
@@ -1,13 +1,14 @@
# Authenticating With an OpenID Provider
## Setup
+
:::info
This feature requires use of [Actual Server](../config/)
:::
If you require a more robust authentication method than a server password, it is recommended to use an OpenID provider. Most OpenID providers support multi-factor authentication, enhancing your application's security. Additionally, if you need support for multiple users, you must enable this feature.
-To enable this feature, you can use a [configuration file](https://actualbudget.com/docs/config/) `config.json` on the Actual server, or use the UI.
+To enable this feature, you can use a [configuration file](docs/config/) `config.json` on the Actual server, or use the UI.
### Configuration Using a Configuration File
@@ -71,6 +72,7 @@ Navigate into any Budget file, then in the Settings, click on _Start using OpenI
Once you click _Start using OpenID_ a modal will be presented.
##### Instructions
+
Fill all the required field for the selected provider.
![Configuration from options](/static/img/oauth/modal.png)
@@ -90,6 +92,7 @@ When configuring your OpenID provider, be sure to register the following **redir
:::
#### Tested Providers
+
- Auth0
- Authentik
- GitHub
@@ -105,7 +108,7 @@ Each provider has different requirements. For example, for Auth0, the URL will b
![](/static/img/oauth/provider-requirement.png)
:::
-#### After Setup:
+#### After Setup
When setup is done, you will be redirected to the _login_ page:
@@ -114,52 +117,61 @@ When setup is done, you will be redirected to the _login_ page:
### Environment Variables
#### `ACTUAL_OPENID_DISCOVERY_URL`
-- **Purpose:** If your OpenID provider supports discovery, this is the URL where discovery metadata can be found.
-**Example Value:** `https://provider.tld/.well-known/openid-configuration`
+
+- **Purpose:** If your OpenID provider supports discovery, this is the URL where discovery metadata can be found.
+ **Example Value:** `https://provider.tld/.well-known/openid-configuration`
#### `ACTUAL_OPENID_CLIENT_ID`
-- **Purpose:** The client ID issued by your OpenID provider.
-**Example Value:** `my-actual-app`
+
+- **Purpose:** The client ID issued by your OpenID provider.
+ **Example Value:** `my-actual-app`
#### `ACTUAL_OPENID_CLIENT_SECRET`
-- **Purpose:** The client secret issued by your OpenID provider.
-**Example Value:** `super-secret-value`
+
+- **Purpose:** The client secret issued by your OpenID provider.
+ **Example Value:** `super-secret-value`
#### `ACTUAL_OPENID_SERVER_HOSTNAME`
-- **Purpose:** The public URL of your Actual Server, which the provider redirects to after authentication.
-**Example Value:** `https://actual.myserver.com`
+
+- **Purpose:** The public URL of your Actual Server, which the provider redirects to after authentication.
+ **Example Value:** `https://actual.myserver.com`
#### `ACTUAL_OPENID_AUTHORIZATION_ENDPOINT`
-- **Purpose:** Provider’s authorization endpoint (for providers that don’t support discovery).
-**Example Value:** `https://provider.com/oauth2/authorize`
+
+- **Purpose:** Provider’s authorization endpoint (for providers that don’t support discovery).
+ **Example Value:** `https://provider.com/oauth2/authorize`
#### `ACTUAL_OPENID_TOKEN_ENDPOINT`
-- **Purpose:** Provider’s token endpoint (for providers that don’t support discovery).
-**Example Value:** `https://provider.com/oauth2/token`
+
+- **Purpose:** Provider’s token endpoint (for providers that don’t support discovery).
+ **Example Value:** `https://provider.com/oauth2/token`
#### `ACTUAL_OPENID_USERINFO_ENDPOINT`
-- **Purpose:** Provider’s user-info endpoint (for providers that don’t support discovery).
-**Example Value:** `https://provider.com/oauth2/userinfo`
+
+- **Purpose:** Provider’s user-info endpoint (for providers that don’t support discovery).
+ **Example Value:** `https://provider.com/oauth2/userinfo`
#### `ACTUAL_OPENID_AUTH_METHOD`
-- **Purpose:** Tells the server whether it should use the OpenID (OIDC) or a more general OAuth2 flow.
-**Possible Values:**
- - `openid` (default)
- - `oauth2`
+
+- **Purpose:** Tells the server whether it should use the OpenID (OIDC) or a more general OAuth2 flow.
+ **Possible Values:**
+ - `openid` (default)
+ - `oauth2`
**Tip:** Use `oauth2` for providers like GitHub that don’t fully support OpenID discovery.
#### `ACTUAL_OPENID_ENFORCE`
-- **Purpose:** Forces OpenID/OAuth2 authentication as the only allowed login method when set to `true`.
-**Example Value:** `true` or `false` (default is `false`)
+
+- **Purpose:** Forces OpenID/OAuth2 authentication as the only allowed login method when set to `true`.
+ **Example Value:** `true` or `false` (default is `false`)
#### `ACTUAL_TOKEN_EXPIRATION`
-- **Purpose:** Controls how access tokens expire.
-**Possible Values:**
- - `"never"` (tokens never expire - **current default**)
- - `"openid-provider"` (tokens follow the expiration time from the OpenID provider)
- - A numeric value in seconds (e.g., `3600` for 1 hour)
+- **Purpose:** Controls how access tokens expire.
+ **Possible Values:**
+ - `"never"` (tokens never expire - **current default**)
+ - `"openid-provider"` (tokens follow the expiration time from the OpenID provider)
+ - A numeric value in seconds (e.g., `3600` for 1 hour)
:::tip
Configuring the OpenID provider from options supports discovery; otherwise, use [file configuration](oauth-auth#config-using-configuration-file)
diff --git a/docs/troubleshooting/server.md b/docs/troubleshooting/server.md
index 635a031803..185e55c31a 100644
--- a/docs/troubleshooting/server.md
+++ b/docs/troubleshooting/server.md
@@ -3,3 +3,5 @@
Actual uses the standard Node.js `debug` module to optionally log helpful debugging information to the console.
If your configuration options (set either in the config file or as environment variables) are not being applied, you can enable debug logging by adding an environment variable named `DEBUG` with the value `actual:config`. If you’re seeing issues with your HTTPS configuration, you can instead set the value to `actual:config,actual-sensitive:config` to log the actual values of the HTTPS secrets (which are obscured by default so they don’t get leaked unintentionally).
+
+It may be useful to compare your configuration file with the configuration schema. The schema can be found at [/packages/sync-server/src/load-config.js](https://github.com/actualbudget/actual/blob/45530638feaacf74c28fddb846ae91170a99d94e/packages/sync-server/src/load-config.js#L43)