Skip to content

Commit 25e2f20

Browse files
sakethpathikesakethpathike
committed
update README.md
1 parent 3c9f588 commit 25e2f20

1 file changed

Lines changed: 156 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 156 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,157 @@
1-
# Linkora Server
1+
Linkora Sync-Server is self-hostable and based on a `single-user server` mechanism, meaning it is designed to be used
2+
exclusively by one individual rather than multiple users.
23

3-
The server is in development and will be available soon. Once ready, Linkora will be able to connect to a self-hostable server, allowing you to run it on your own machine.
4+
---
5+
6+
### 1. Prerequisites
7+
8+
#### For Local Hosting (Using JAR):
9+
10+
- Ensure **Java 11 or later** is installed on your machine to run the server properly.
11+
12+
#### For Docker Hosting:
13+
14+
- If you are using Docker, no additional setup is required. Docker handles all dependencies.
15+
16+
#### Supported Databases:
17+
18+
- Linkora supports SQL-based databases such as **MySQL**, **SQLite**, **PostgreSQL**, and other databases supported by
19+
the [Exposed](https://github.com/JetBrains/Exposed?tab=readme-ov-file#supported-databases).
20+
- Note: The server has been tested with MySQL, SQLite, and PostgreSQL.
21+
22+
---
23+
24+
### 2. Server Configuration
25+
26+
Linkora Sync Server can be configured in two ways:
27+
28+
1. Using the `linkoraConfig.json` file.
29+
2. Using environment variables.
30+
31+
#### 1. Using `linkoraConfig.json`
32+
33+
This file is auto-generated on the first run of the server if no environment variables are detected. During setup, you
34+
will be prompted to provide the required values, which will be saved locally.
35+
36+
`linkoraConfig.json`:
37+
38+
```json
39+
{
40+
"databaseUrl": "",
41+
"databaseUser": "",
42+
"databasePassword": "",
43+
"hostAddress": "",
44+
"serverPort": 45454,
45+
"serverAuthToken": ""
46+
}
47+
```
48+
49+
- `databaseUrl`: The database URL (without username or password).
50+
- `databaseUser`: The username for your database.
51+
- `databasePassword`: The password for your database.
52+
- `hostAddress`: The host address of the server. If not provided, defaults to `0.0.0.0`.
53+
- `serverPort`: The port number on which the server runs. If not provided, defaults to `8080`.
54+
- `serverAuthToken`: A secure token used to authenticate requests from the Linkora app. Treat this like a password and
55+
keep it confidential.
56+
57+
58+
**Note**: A pre-written `linkoraConfig.json` file can also be used on remote hosting if no environment variables are
59+
provided or if you prefer this method. However, ensure the file is correctly placed.
60+
61+
#### 2. Using Environment Variables
62+
63+
When hosting on remote services or using Docker, environment variables are recommended. The following variables must be
64+
set:
65+
66+
- `LINKORA_SERVER_USE_ENV_VAL`: Set this to `true` to indicate the server is running on a remote service. This must
67+
always
68+
be `true` when using environment variables.
69+
- `LINKORA_DATABASE_URL`: The database URL (without username or password).
70+
- `LINKORA_DATABASE_USER`: The username for your database.
71+
- `LINKORA_DATABASE_PASSWORD`: The password for your database.
72+
- `LINKORA_SERVER_AUTH_TOKEN`: A secure token used to authenticate requests from the Linkora app. Treat this like a
73+
password and
74+
keep it confidential.
75+
- `LINKORA_HOST_ADDRESS`: The host address of the server. If not provided, defaults to `0.0.0.0`.
76+
- `LINKORA_SERVER_PORT`: The port number on which the server runs. If not provided, defaults to `8080`.
77+
78+
### 3. Hosting Options
79+
80+
Linkora Sync Server supports both local and remote hosting. Below are the details for each method:
81+
82+
#### 3.1 Local Hosting
83+
84+
You can host the server locally using either the JAR file or Docker.
85+
86+
##### 3.1.1 Using JAR:
87+
88+
- Use the prebuilt JAR file from the latest release.
89+
90+
**Important**: Instead of double-clicking the JAR file, always open a terminal in the directory where the JAR file is
91+
located and run the following command:
92+
93+
```
94+
java -jar "linkoraSyncServer.jar"
95+
```
96+
97+
This ensures the server runs as expected and avoids potential issues.
98+
99+
- **Recommendation**:
100+
- Place the server JAR file in a separate folder before running it. This is because the `linkoraConfig.json` file is
101+
generated in the same directory as the JAR file.
102+
- For local hosting with JAR, using `linkoraConfig.json` (this file is auto-generated on the first run of the server
103+
if no environment variables are detected) is recommended.
104+
105+
##### 3.1.2 Using Docker:
106+
107+
When running Docker on your local machine, pass the required environment variables using the `-e` flag:
108+
109+
```
110+
docker run -e LINKORA_SERVER_USE_ENV_VAL="true" -e LINKORA_DATABASE_URL="mysql://your-db-url" -e LINKORA_DATABASE_USER="your-db-user" -e LINKORA_DATABASE_PASSWORD="your-db-password" -e LINKORA_SERVER_AUTH_TOKEN="your-auth-token" linkora-server
111+
```
112+
113+
Replace `your-db-url`, `your-db-user`, `your-db-password`, and `your-auth-token` with your actual database and
114+
authentication details.
115+
116+
#### 3.2 Remote Hosting
117+
118+
- For remote hosting, pass the environment variables using the environment variable service provided by your cloud
119+
hosting provider.
120+
- Ensure `LINKORA_SERVER_USE_ENV_VAL` is set to `true` and all other required variables are configured.
121+
122+
### Key Features
123+
124+
- **Delta-Sync Mechanism**: Linkora uses a delta-sync mechanism to efficiently synchronize data between the server and
125+
clients.
126+
- **Two-Way Sync**: The server supports two-way synchronization, ensuring that changes on the server are reflected on
127+
the client and vice versa.
128+
- **Real-Time Updates**: Events on the server are sent to clients via socket, ensuring data is always up-to-date.
129+
- This server implements the LWW (Last-Write-Wins) mechanism, where the latest client update takes effect.
130+
131+
### Important Notes
132+
133+
- **Client-Server Compatibility**: Always verify client-server compatibility to confirm that the applications work
134+
together properly.
135+
- **Security**: The `serverAuthToken`/`LINKORA_SERVER_AUTH_TOKEN` acts as a password to your server. Never share it
136+
publicly.
137+
- **Database Compatibility**: While Linkora supports multiple databases, ensure your chosen database is properly
138+
configured and accessible.
139+
- **Local vs Remote Hosting**:
140+
- For local hosting with JAR, `linkoraConfig.json` is recommended.
141+
- For local hosting with Docker, use the provided `docker run` command with environment variables.
142+
- For remote hosting, use the environment variable service provided by your cloud hosting provider.
143+
144+
### Join the Community
145+
146+
[![Join us on Discord](https://discord.com/api/guilds/1214971383352664104/widget.png?style=banner2)](https://discord.gg/ZDBXNtv8MD)
147+
148+
### Contribute
149+
150+
Want to help improve Linkora Sync Server? You can contribute by:
151+
152+
- Reporting issues
153+
- Submitting pull requests
154+
155+
### License
156+
157+
This project is licensed under the MIT License.

0 commit comments

Comments
 (0)