Skip to content

A local-first personal finance app

Docs for new sync-server npm package (#680)

Michael Clark0bc8db4ed5fa
diff --git a/docs-sidebar.js b/docs-sidebar.js
index 3ecb16bf00..39f7266b57 100644
--- a/docs-sidebar.js
+++ b/docs-sidebar.js
@@ -67,6 +67,7 @@ const sidebars = {
collapsible: false,
items: [
'install/docker',
+ 'install/cli-tool',
{ type: 'link', label: 'Desktop app', href: '/download' },
'install/build-from-source',
],
diff --git a/docs/config/index.md b/docs/config/index.md
index e6cb176dac..841b170fd9 100644
--- a/docs/config/index.md
+++ b/docs/config/index.md
@@ -12,17 +12,17 @@ Running into issues with your configuration not being interpreted correctly? Che
## `ACTUAL_DATA_DIR`
-This is where the server stores the budget data files (and configurations unless `ACTUAL_CONFIG_PATH`is set).
+This is where the server stores the budget data files (and configurations unless `ACTUAL_CONFIG_PATH` is set).
-The default value is `/data`.
+By default, the server will use the `/data` directory if it exists, or the current directory (`/`) if not.
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 either in the
-`/data` folder if it is present or in the same directory as the sync-server's `package.json` if `/data` is absent.
+This is the path to the config file. If not specified, the server will look for a `config.json` file in the
+`/data` folder if it is present or in the sync-server's root directory if `/data` is absent.
See the `ACTUAL_DATA_DIR` section above to override the data folder location.
diff --git a/docs/contributing/releasing.md b/docs/contributing/releasing.md
index d0a1cd214c..ded2710e34 100644
--- a/docs/contributing/releasing.md
+++ b/docs/contributing/releasing.md
@@ -1,10 +1,14 @@
# How to Cut a Release
-In the open-source version of Actual, all updates go through NPM. There is one npm package:
+In the open-source version of Actual, there are 3 NPM packages:
-`@actual-app/api`: The API for the underlying functionality. This includes the entire backend of Actual, meant to be used with Node.
+[@actual-app/api](https://www.npmjs.com/package/@actual-app/api): The API for the underlying functionality. This includes the entire backend of Actual, meant to be used with Node.
-Both the API and the main Actual release are versioned together. That makes it clear which version of the API should be used with the version of Actual.
+[@actual-app/web](https://www.npmjs.com/package/@actual-app/web): A web build that will serve the app with a web frontend. This includes both the frontend and backend of Actual. It includes the backend as well because it's built to be used as a Web Worker.
+
+[@actual-app/sync-server](https://www.npmjs.com/package/@actual-app/sync-server): The entire sync-server and underlying web client in one package. This includes a CLI tool, meant to be used with Node.
+
+All packages and the main Actual release are versioned together. That makes it clear which version of the package should be used with the version of Actual.
### Versioning Strategy
@@ -38,20 +42,9 @@ This automation will also delete all the outdated release note files from the `u
### docs
After the release notes workflows in the actual PR has been run, copy the collated notes into a new blog post using a previous release as a template. The release notes will also need adding to the `docs/releases.md` file.
-## Building and Publishing to NPM
-Once the Actual repository PR has been approved, the new version of the API package needs to be published to NPM. If you haven't done this before, another maintainer will need to give you access.
-
-### @actual-app/api
-
-```bash
-cd packages/api
-yarn build
-yarn npm publish --access public
-```
-
## GitHub Tags and Releases
-Once the release has been merged, it need to be tagged. When the tag is pushed to `actual` it will trigger the Docker stable image to be built and published.
+Once the release has been merged, it needs to be tagged. When the tag is pushed to `actual` it will trigger the Docker stable image and all NPM packages to be built and published.
Run the below in each repository, or use the GitHub UI.
```bash
@@ -59,6 +52,11 @@ git tag vX.Y.Z
git push vX.Y.Z
```
+All NPM packages should be automatically released and pushed to the NPM registry. Check them here:
+- [@actual-app/api](https://www.npmjs.com/package/@actual-app/api)
+- [@actual-app/web](https://www.npmjs.com/package/@actual-app/web)
+- [@actual-app/sync-server](https://www.npmjs.com/package/@actual-app/sync-server)
+
A GitHub release should be automatically generated on push in [actual](https://github.com/actualbudget/actual). Un-mark it as a draft and change the text to the below
```markdown
diff --git a/docs/install/cli-tool.md b/docs/install/cli-tool.md
new file mode 100644
index 0000000000..28eef47dcd
--- /dev/null
+++ b/docs/install/cli-tool.md
@@ -0,0 +1,70 @@
+---
+title: 'CLI tool'
+---
+
+## Hosting Actual with the CLI tool
+
+The Actual sync-server is available as an NPM package. The package is designed to make running the sync-server as easy as possible and is published to the official NPM registry under [@@actual-app/sync-server](https://www.npmjs.com/package/@actual-app/sync-server).
+
+### Installing the CLI tool
+
+Node.js v18 or higher is required for the `@actual-app/sync-server` npm package
+
+**Install globally with npm:**
+
+```bash
+npm install --location=global @actual-app/sync-server
+```
+
+Once installed, you can execute commands directly from your terminal using `actual-server`.
+
+### Usage
+
+> Before running the tool, navigate to the directory that you wish your files to be located.
+
+Run the CLI tool with the following syntax:
+
+```bash
+actual-server [options]
+```
+
+**Available options**
+
+| Command | Description |
+| ------------------- | ---------------------------- |
+| `-h` or `--help` | Print this list and exit. |
+| `-v` or `--version` | Print this version and exit. |
+| `--config` | Path to the config file. |
+
+**Default values**
+
+If no `--config` option is set, Actual will search for a `config.json` file in the current directory. If it exists it will be used. If it doesn't exist, Actual will set a [Default Configuration](../config/index.md).
+
+
+### Examples
+
+Run with [Default Configuration](../config/index.md):
+
+```bash
+actual-server
+```
+
+Run with [JSON Configuration](../config/index.md):
+
+```bash
+actual-server --config ./custom-config.json
+```
+
+Run with [Environment Variable Configuration](../config/index.md):
+
+```bash
+ACTUAL_DATA_DIR=./custom-directory actual-server --config ./config.json
+```
+
+### Updating the CLI tool
+
+The sync server can be updated with a simple command.
+
+```bash
+npm update -g @actual-app/sync-server
+```
diff --git a/docs/install/index.md b/docs/install/index.md
index 898cf95cf6..e5a157465b 100644
--- a/docs/install/index.md
+++ b/docs/install/index.md
@@ -46,6 +46,7 @@ While running a server can be a complicated endeavor, we’ve tried to make it f
- If you’re not comfortable with the command line and are willing to pay a small amount of money to have your version of Actual hosted on the cloud for you, we recommend [PikaPods](pikapods.md).[^2]
- If you’re willing to run a few commands in the terminal:
+ - You can run the server with a simple command using the [CLI tool](cli-tool.md)
- [Fly.io](fly.md) also offers cloud hosting for a similar amount of money.
- If you want to use Docker, we have instructions for [using our provided Docker containers](docker.md).
- You could [build Actual from source](build-from-source.md) on macOS, Windows, or Linux if you don’t want to use a tool like Docker. (This method is the best option if you want to contribute to Actual's development!)