You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A self-hosted sync server designed for individual use and built for single-user setups, keeping your Linkora apps in sync.
2
+
3
+
A self-hosted sync server designed for individual use and built for single-user setups, keeping your Linkora apps in
4
+
sync. Now with built-in HTTPS support and compatibility with the Linkora browser extension for comprehensive syncing.
5
+
6
+
-----
3
7
4
8
## Key Features
5
-
-**Delta-Sync**: Only transfers changed data for efficiency
6
-
-**Two-Way Sync**: Changes flow in both directions between the server and clients
7
-
-**Real-Time Updates**: Live updates via WebSocket connections
8
-
-**Last-Write-Wins**: If multiple devices update the same data, the latest write wins the conflict
9
-
-**Multi-Database Support**: Works with MySQL, PostgreSQL, SQLite, and other SQL databases supported by [JetBrains Exposed](https://github.com/JetBrains/Exposed)
10
-
-**Deployment Options**: Local JAR, Docker containers, or cloud hosting
9
+
10
+
-**Delta-Sync**: Only transfers changed data for efficiency.
11
+
-**Two-Way Sync**: Changes flow in both directions between the server and clients.
12
+
-**Real-Time Updates**: Live updates via WebSocket connections.
13
+
-**Last-Write-Wins**: If multiple devices update the same data, the latest write wins the conflict.
14
+
-**Secure HTTPS**: Secure connections are supported by automatically generating self-signed certificates and keystore
15
+
files.
16
+
-**Browser Extension Support**: Works with the Linkora browser extension for seamless web activity synchronization.
17
+
-**Multi-Database Support**: Works with MySQL, PostgreSQL, SQLite, and other SQL databases supported
18
+
by [JetBrains Exposed](https://github.com/JetBrains/Exposed).
19
+
-**Flexible Deployment**: Local JAR, Docker containers, or cloud hosting.
20
+
21
+
-----
11
22
12
23
## Quick Start
13
24
14
25
### Prerequisites
15
-
**For JAR deployment:**
16
-
- Java 11 or later
17
26
18
-
**For Docker deployment:**
19
-
- Docker (handles all dependencies, no Java installation required)
27
+
For JAR deployment:
28
+
29
+
-**Java 11 or later**
30
+
31
+
For Docker deployment:
32
+
33
+
-**Docker** (handles all dependencies, no Java installation required)
34
+
35
+
Supported Databases:
20
36
21
-
**Supported Databases:**
22
37
-**Tested**: MySQL, PostgreSQL, SQLite
23
38
-**Untested**: Other databases supported by [JetBrains Exposed](https://github.com/JetBrains/Exposed)
24
39
25
-
**Warning**: Untested databases may have compatibility issues. I recommend sticking to MySQL, PostgreSQL, or SQLite for the best experience.
40
+
**Warning**: Untested databases may have compatibility issues. Sticking to MySQL, PostgreSQL, or SQLite is recommended
41
+
for the best experience.
42
+
43
+
### Getting Started with HTTPS
44
+
45
+
The server automatically handles HTTPS setup by generating self-signed certificates and keystore files on its first run.
46
+
This means you get secure connections out-of-the-box without manual certificate configuration. These server-signed
47
+
certificates have a validity period of 365 days. To use these certificates, you may need to import them into your
48
+
system's trust store or directly into your browser, as the browser extension requires the certificate to be recognized.
49
+
Some browsers, like Firefox, may reject self-signed certificates, requiring you to manually add an exception for the
50
+
IPv4 address and port used by HTTPS.
51
+
52
+
To generate new certificates and keystore files, you have two options:
53
+
54
+
1.**Restart the server**: If the existing certificate and keystore files are removed from the server's directory,
55
+
restarting the server will trigger the automatic generation of new ones.
56
+
2.**Use the server's API endpoint**: Navigate to `/generate/certs-and-keystore` in your browser. You will be prompted
57
+
to enter your `serverAuthToken`. Once entered, you will have two options: to *only generate* new certificates and
58
+
keystore files (which will be saved in the same directory where the server JAR is located), or to *generate and
59
+
download* them. If you choose to generate and download, the server will respond with a ZIP file containing all the
60
+
newly generated files. If an incorrect authentication token is provided, the server will reject the request.
61
+
62
+
### Browser Extension
63
+
64
+
Get the **Linkora browser extension** to sync your web-based data. Find detailed setup instructions on
65
+
the [Linkora Browser Extension GitHub repository](https://github.com/LinkoraApp/browser-extension).
66
+
67
+
-----
26
68
27
69
## Configuration
28
-
Choose between configuration file or environment variables:
70
+
71
+
You can configure the server using either a configuration file or environment variables.
Auto-generated on first run - the server will prompt you for required configuration values. The `hostAddress` and `serverPort` fields are automatically set by the server:
74
+
75
+
This file is auto-generated on the first run; the server will prompt you for required values. The `hostAddress` and
76
+
`serverPort` fields are automatically detected and set by the server.
32
77
33
78
```json
34
79
{
@@ -37,12 +82,24 @@ Auto-generated on first run - the server will prompt you for required configurat
37
82
"databasePassword": "your_password",
38
83
"hostAddress": "xxx.xxx.xxx.xxx",
39
84
"serverPort": 45454,
85
+
"httpsPort": 54545,
86
+
"keyStorePassword": "your_keystore_password",
40
87
"serverAuthToken": "your_secure_token"
41
88
}
42
89
```
43
90
91
+
**HTTPS Configuration Details**:
92
+
93
+
-`httpsPort`: This optional field sets the port for HTTPS connections (default: `54545`).
94
+
-`keyStorePassword`: This password for your keystore is **auto-generated by the server**.
95
+
- For HTTPS connections, the server always uses the machine's IPv4 address. The `hostAddress` field in the configuration
96
+
file primarily applies to HTTP connections.
97
+
44
98
### Option 2: Environment Variables
45
-
Set these environment variables for containerized deployments, cloud hosting, or any deployment where you prefer environment variables over config files. The `LINKORA_HOST_ADDRESS` and `LINKORA_SERVER_PORT` are optional as the server will automatically detect/set them:
99
+
100
+
Use these for containerized deployments, cloud hosting, or any scenario where you prefer environment variables over
101
+
configuration files. `LINKORA_HOST_ADDRESS`, `LINKORA_SERVER_PORT`, `LINKORA_HTTPS_PORT`, and
102
+
`LINKORA_KEY_STORE_PASSWORD` are all optional, as the server can auto-detect/set them.
**Authentication Token**: Treat `serverAuthToken` as a password—never share it publicly.
235
+
## Critical Security & Connection Notes
153
236
154
-
**Network Access**: Connect using the server machine's IPv4 address (or the one detected and used by the server) instead of `localhost` when accessing from other devices.
237
+
-**Authentication Token**: Treat `serverAuthToken` as a password—never share it publicly.
238
+
-**Network Access**: When connecting from other devices, use the server machine's IPv4 address (or the one detected and
239
+
used by the server) instead of `localhost`. For HTTPS connections, the server exclusively uses IPv4.
240
+
-**Client-Server Compatibility**: Always verify client-server version compatibility. Mismatched versions may cause sync
241
+
failures.
155
242
156
-
**Client-Server Compatibility**: Always verify client-server version compatibility. Mismatched versions may cause sync failures.
243
+
-----
157
244
158
245
## Troubleshooting
159
246
160
247
### Common Issues
161
248
162
249
**Cannot connect to server from Linkora app**
163
-
- Check if the server port is allowed through your firewall
164
-
- Ensure you're using the server machine's IPv4 address (or the one detected and used by the server) instead of `localhost` when connecting from other devices
165
-
- Verify the `serverAuthToken` matches between server and client
250
+
251
+
- Check if the server port(s) (HTTP: 45454, HTTPS: 54545) are allowed through your firewall.
252
+
- Ensure you're using the server machine's IPv4 address (or the one detected and used by the server) instead of
253
+
`localhost` when connecting from other devices.
254
+
- Verify the `serverAuthToken` matches between the server and client.
166
255
167
256
**Server fails to start**
168
-
- Ensure Java 11+ is installed and accessible
169
-
- Check database connectivity and credentials
170
-
- Verify the database URL format is correct for your database type
171
-
- For JAR deployment, ensure you're running from terminal, not double-clicking
257
+
258
+
- Ensure Java 11+ is installed and accessible.
259
+
- Check database connectivity and credentials.
260
+
- Verify the database URL format is correct for your database type.
261
+
- For JAR deployment, ensure you're running from the terminal, not double-clicking.
172
262
173
263
**Database connection errors**
174
-
- Confirm your database server is running and accessible
175
-
- Verify database URL, username, and password are correct
176
-
- For SQLite, ensure the file path is accessible and the directory exists
264
+
265
+
- Confirm your database server is running and accessible.
266
+
- Verify database URL, username, and password are correct.
267
+
- For SQLite, ensure the file path is accessible and the directory exists.
177
268
178
269
**Configuration issues**
179
-
- Ensure `LINKORA_SERVER_USE_ENV_VAL=true` when using environment variables
180
-
- Verify all required fields are properly set in your chosen configuration method
270
+
271
+
- Ensure `LINKORA_SERVER_USE_ENV_VAL=true` when using environment variables.
272
+
- Verify all required fields are properly set in your chosen configuration method.
For detailed technical information about the synchronization mechanism, read the [technical blog post](https://sakethpathike.github.io/blog/synchronization-in-linkora).
278
+
For detailed technical information about the synchronization mechanism, read
279
+
the [technical blog post](https://sakethpathike.github.io/blog/synchronization-in-linkora).
280
+
281
+
Beyond the core sync logic, the Linkora Sync-Server also handles rendering user interfaces for specific functions. For
282
+
example, the Linkora browser extension's UI is built and served directly by this sync server. The interface for the
283
+
certificate generation endpoint is also handled this way. These UIs are generated using my Kotlin Multiplatform library,
284
+
[Kapsule](https://github.com/sakethpathike/kapsule). Kapsule helps simplify creating static HTML by using a familiar Jetpack Compose-style approach with
285
+
`kotlinx.html`.
286
+
287
+
-----
186
288
187
289
## Important Notes
188
-
-**Single User Design**: Designed exclusively for individual use, not multi-user environments
189
-
-**Configuration File Location**: For JAR deployments, `linkoraConfig.json` is created in the same directory as the JAR file when you first run the server
190
-
-**Database Compatibility**: Linkora supports multiple databases through Exposed. The server has been tested with MySQL, SQLite, and PostgreSQL
191
-
-**Environment Variables**: For local JAR hosting, `linkoraConfig.json` is recommended. For Docker and cloud hosting, use environment variables
192
-
-**Host Address**: The `hostAddress` field automatically defaults to the machine's current network IPv4 address. The server detects this automatically, so no manual configuration is needed. When connecting from Linkora apps, use this address instead of `localhost`
290
+
291
+
-**Single User Design**: Designed exclusively for individual use, not multi-user environments.
292
+
-**Configuration File Location**: For JAR deployments, `linkoraConfig.json` is created in the same directory as the JAR
293
+
file when you first run the server.
294
+
-**Database Compatibility**: Linkora supports multiple databases through Exposed. The server has been tested with
295
+
MySQL, SQLite, and PostgreSQL.
296
+
-**Environment Variables**: For local JAR hosting, `linkoraConfig.json` is recommended. For Docker and cloud hosting,
297
+
use environment variables.
298
+
-**Host Address**: The `hostAddress` field automatically defaults to the machine's current network IPv4 address. The
299
+
server detects this automatically, so no manual configuration is needed for HTTP connections. When connecting from
300
+
Linkora apps, use this address instead of `localhost`.
301
+
-**HTTPS Certificates & Keystore**: The server automatically generates required certificates and keystore files.
0 commit comments