Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions src/app/data-access/local-http-server/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ export const metadata = {
# Local HTTP Server

The Inkdrop client app can open a simple HTTP server so that you can access the data from an external program easily, which gives you a flexible ability to import/export your notes.
Read [this page](/guides/integrate-with-external-programs) to learn how to configure the local HTTP server. {{ className: 'lead' }}


---
Expand Down
59 changes: 3 additions & 56 deletions src/app/guides/access-the-local-database/page.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -50,62 +50,9 @@ console.log('Search result:', docs)

## Accessing via HTTP (Advanced)

![Local REST API endpoint](/images/accessing-the-local-database_local-rest-api-endpoint.png)

The Inkdrop client app can open a simple HTTP server so that you can access the data from an external program easily, which gives you a flexible ability to import/export your notes.

You can configure the HTTP server settings by editing `config.json` in [the user data directory](https://docs.inkdrop.app/manual/basic-usage#user-data-directory).

Quit Inkdrop, then edit it like so:

```json
{
"*": {
"core": {
"server": {
"enabled": true,
"port": 19840,
"bindAddress": "127.0.0.1",
"auth": { "username": "foo", "password": "bar" }
}
}
}
}
```

Now, launch the app.

### Troubleshooting

Check if the local server is running correctly with `curl`:

```sh
curl -v -u foo:bar http://localhost:19840/
# -> {"version":"5.10.0","ok":true}
```

Run the app with `--enable-logging` flag to see the server logs. See [the documentation](https://docs.inkdrop.app/manual/troubleshooting#enable-logging) for more detail.

```sh
/Applications/Inkdrop.app/Contents/MacOS/Inkdrop --enable-logging
```

If the server is running correctly, you should see logs like this:

```
app:info Starting server on 127.0.0.1:19840
```

### Configurations

- `core.server.enabled` - Specify `true` to enable the HTTP server. Default is `false`.
- `core.server.port` - Defines the port number to listen. Default is `19840`.
- `core.server.bindAddress` - Defines the IP address to listen. Default is `127.0.0.1`.
- `core.server.auth.{username,password}` - Defines Basic auth credentials.

### API reference

See [the local HTTP server reference](/data-access/local-http-server) for more details.
<Note>
Moved to the <a href="/guides/integrate-with-external-programs">Integrate with External Programs</a> guide.
</Note>

## Accessing the PouchDB instance (Advanced, not recommended)

Expand Down
69 changes: 69 additions & 0 deletions src/app/guides/integrate-with-external-programs/page.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
import { Resources } from '@/components/Resources'

export const metadata = {
title: 'Integrate with External Programs',
description:
'Learn how to configure the local HTTP server to integrate with external programs'
}

# Integrate with External Programs via Local HTTP Server

If you want to access your notes from external programs, you can use the local HTTP server.
The Inkdrop client app can run a simple HTTP server locally.
It is useful for automating tasks such as generating static sites by exporting notes with a tool like [live-export](https://github.com/inkdropapp/inkdrop-live-export).
It also allows you to integrate with external programs such as [Web clipper](https://docs.inkdrop.app/reference/clip-web-pages-from-browser), launcher apps like [Raycast](https://docs.inkdrop.app/reference/integrate-with-raycast) and [Alfred](https://docs.inkdrop.app/reference/integrate-with-alfred), [the official MCP server](https://github.com/inkdropapp/mcp-server), [static site generators like Astro](https://github.com/inkdropapp/inkdrop-blog-template), etc.{{ className: 'lead' }}

## How it works

![Local REST API endpoint](/images/accessing-the-local-database_local-rest-api-endpoint.png)

By default, the Inkdrop client app declines requests from external networks for security reasons.
It only accepts requests from the loopback network (`localhost` or `127.0.0.1`).
Also, you will set up the authentication credentials to protect unwanted access.

## API reference

See [the local HTTP server reference](/data-access/local-http-server) for more details.

## How to configure the local HTTP server

![Preferences](/images/integrate-with-external-programs_preferences.png)

Open the Preferences window and click the **Local Server** section in the sidebar.

- **Enabled** - Check this box to enable the local HTTP server. Default is unchecked.
- **Port number** - Defines the port number to listen. Default is `19840`.
- **Bind Address** - Defines the IP address to listen. Default is `127.0.0.1`.
- **Username** - Defines username of the Basic auth credentials.
- **Password** - Defines password of the Basic auth credentials.

Click the **Apply** button to apply the changes.
The auth info will be encrypted and stored safely in `config.json` in [the user data directory](https://docs.inkdrop.app/manual/basic-usage#user-data-directory).

![Server logs](/images/integrate-with-external-programs_server-logs.png)

By pressing the **View Server Logs** button, you can check the server access logs updated in real-time.
The path to the log file is `USER_DATA_DIRECTORY/server.log`.


### Troubleshooting

Check if the local server is running correctly with `curl`:

```sh
curl -v -u foo:bar http://localhost:19840/
# -> {"version":"5.10.0","ok":true}
```

Run the app with `--enable-logging` flag to see the server logs. See [the documentation](https://docs.inkdrop.app/manual/troubleshooting#enable-logging) for more detail.

```sh
/Applications/Inkdrop.app/Contents/MacOS/Inkdrop --enable-logging
```

If the server is running correctly, you should see logs like this:

```
app:info Starting server on 127.0.0.1:19840
```

4 changes: 4 additions & 0 deletions src/components/Navigation.jsx
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,10 @@ export const navigation = [
title: 'Access the local database',
href: '/guides/access-the-local-database'
},
{
title: 'Integrate with external programs',
href: '/guides/integrate-with-external-programs'
},
{ title: 'Customize the editor', href: '/guides/customize-the-editor' },
{ title: 'Extend the UI', href: '/guides/extend-the-ui' },
{
Expand Down