Project

General

Profile

Wiki » History » Version 25

Tomek Dziemidowicz, 2019-07-04 08:42 PM

1 2 Tomek Dziemidowicz
h1. SQLite-sync documentation
2
3
*Owner* : AMPLIFIER sp. z o.o.
4
*Contact* : support (at) ampliapps.com
5
*website* : https://ampliapps.com
6
7 3 Tomek Dziemidowicz
{{>toc}}
8
9 9 Tomek Dziemidowicz
Welcome to the AMPLI-SYNC documentation!
10
We have language bindings in JavaScript, .NET C#, Java and Objective-C! 
11 1 Tomek Dziemidowicz
12 9 Tomek Dziemidowicz
h2. AMPLI-SYNC concept
13
14
h3. Solution diagram
15
16 8 Tomek Dziemidowicz
!{width:700px}SQLite-sync-structure.png!
17 1 Tomek Dziemidowicz
18 13 Tomek Dziemidowicz
* Devices communicate with server using HTTP/HTTPS protocol. 
19
* Proxy Load Balancer. If necessary, proxy can redirect request to another instance of SQLite-core.
20
* Authorization provider will generate token based on response from authorization provider.
21 9 Tomek Dziemidowicz
22
h3. Proxy Balancer flowchart
23
24
!{width:400px}SQLite-sync-proxy-balancer.png!
25
26
h3. Authorization Provider flowchart
27
28
!{width:350px}SQLite-sync-authentication-process.png!
29
30 2 Tomek Dziemidowicz
h2. REST API (server API)
31
32 10 Tomek Dziemidowicz
h3. Protocol version
33
34
This document describes integration with the REST API 3.x protocol.
35
36
h3. Service description
37
38
There are two stages to processing a request:
39
40 12 Tomek Dziemidowicz
* Device places an request.
41
* SQLite-sync server confirms the request has been processed successfully and sends confirmation with eventual conflict list that need to be resolved.
42 10 Tomek Dziemidowicz
43 11 Tomek Dziemidowicz
h3. Synchronization flowchart
44
45
!{width:200px;}Device-synchronization-diagram.png!
46 10 Tomek Dziemidowicz
47 23 Tomek Dziemidowicz
h3. Request URL format
48 22 Tomek Dziemidowicz
49
Sample REST API call:
50
<pre>
51
https://example.com/API3/__method___
52
</pre>
53
Explanation:
54
*https://example.com/* - adres of REST API service 
55
*API3* - version of synchronization
56
*__method___* - method/action
57
58 24 Tomek Dziemidowicz
h3. API methods
59
60 25 Tomek Dziemidowicz
There are three method used by client:
61
62
h4. *Sync* - gets changes for table
63
*Method* : GET
64
*Path* : /Sync/{subscriberUUID}/{tableName}“
65
*Produces* : TEXT_PLAIN
66
*Description* : Get changed data. Params:
67
*subscriberUUID* - identifier of subscriber. By default device unique ID is used. But we can place there any value (also #user.UUID)
68
Response:
69
70
71 2 Tomek Dziemidowicz
h2. Conflict Resolution
72
73
h2. Update procedure
74
75
h2. Data filtering
76
77 1 Tomek Dziemidowicz
h2. Installation
78 9 Tomek Dziemidowicz
79 18 Tomek Dziemidowicz
h3. Server Prerequisites
80
81
To make ampli-sync server work you need:
82
* Apache Tomcat 8.
83
* Java
84
* Linux/Windows environment. 
85
86 9 Tomek Dziemidowicz
h3. Manual
87
88 14 Tomek Dziemidowicz
Steps needed to install AMPLI-SYNC manually on Ubuntu.
89
90 15 Tomek Dziemidowicz
# Install Tomcat on Ubuntu:
91 14 Tomek Dziemidowicz
https://www.digitalocean.com/community/tutorials/how-to-install-apache-tomcat-8-on-ubuntu-16-04
92
# Create new user
93
<pre>
94
sudo adduser amplisync
95
</pre>
96
System will ask you for password for newly created user.
97
# Add user to group ‘tomcat’
98
<pre>
99
sudo usermod -a -G tomcat amplisync
100
</pre>
101
# Chang in web.xml path variable to 
102
<pre>
103
\home/sqlitesync/demo
104
</pre>
105
# Install new application in Tomcat. Start with switching to amplisync user.
106
<pre>
107
su amplisync
108
</pre>
109
# Create new folder /home/sqlitesync/demo
110 16 Tomek Dziemidowicz
# Upload new service amplisync-demo to Tomcat. You can do that using Tomcat application manager, or you can put WAR file in Tomcat webapps folder. Name of your WAR file is app name in Tomcat environment. Remember to not place spaces and special chars in name of your WAR file.
111 17 Tomek Dziemidowicz
# Restart Tomcat:
112 14 Tomek Dziemidowicz
<pre>
113
service tomcat restart
114
</pre>
115
Now you can access your installation using link:
116
<pre>
117
http://your_ip:8080/amplisync-app-name/API3
118
</pre>
119
# Setup permissions:
120
<pre>
121
chown -R sqlitesync:tomcat /home/amplisync/demo/
122
</pre>
123
124 9 Tomek Dziemidowicz
h3. Docker
125 2 Tomek Dziemidowicz
126 20 Tomek Dziemidowicz
h3. Configuring AMPLI-SYNC service
127 19 Tomek Dziemidowicz
128
First you need to adjust website configuration file (web.xml), then you need to change main configuration file (sync.properties).
129
*Service configuration (web.xml)*
130
Go to your_webapps_folder/SqliteSync/WEB-INF/web.xml and open for edit. Navigate to section:
131
<pre><code class="xml">
132
<env-entry>
133
<env-entry-name>working-dir</env-entry-name>
134
<env-entry-type>java.lang.String</env-entry-type>
135
<env-entry-value>/your/working/dir/sqlite-sync/</env-entry-value>
136
</env-entry>
137
</code></pre>
138
change env-entry-value key and point to working dir where SQLite-sync.com server will store log files, temporary files and configuration. Create manually a subfolder named config. Create a text file sync.properties in folder config. The path should look like this:
139
<pre>
140
\working_dir\config\sync.properties
141
</pre>
142
*IMPORTANT* Restart service after changing web.xml. Make sure that Tomcat has read/write access to working dir.
143
Sample configurations for MySQL server
144
<pre>
145
DB_ENGINE = mysql
146
DBURL = jdbc:mysql://server:3306/dbname?rewriteBatchedStatements=true
147
DBUSER = user
148
DBPASS = pass
149
DBDRIVER = com.mysql.cj.jdbc.Driver
150
DATE_FORMAT = yyyy-MM-dd HH:mm:ss
151
HISTORY_DAYS = 7
152
LOG_LEVEL = 4
153
</pre>
154
If you faced a timezone error after configuration in `sync.properties` add at the end of connection string:
155
<pre>
156
&useUnicode=true&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC
157
</pre>
158
*Keys explanation*
159 21 Tomek Dziemidowicz
*DB_ENGINE* - type of database engine. Available options:
160
* mysql
161
* mssql
162
* postgresql
163
* oracle
164
165 19 Tomek Dziemidowicz
*LOG_LEVEL* - defain details level for log
166
> 4: TRACE, DEBUG, INFO, WARN; (default)
167
> 3: DEBUG, INFO, WARN; 
168
> 2: INFO,WARN; 
169
> 1: WARN; 
170
> 0 - disable logs
171
*DATE_FORMAT* - set format of date 
172
default format: yyyy-MM-dd HH:mm:ss 
173
*HISTORY_DAYS* - How long files with sync data will be kept
174
default value: 7
175
When you use MySQL database DO NOT remove from the end of the connection string:
176
<pre>
177
?rewriteBatchedStatements=true
178 20 Tomek Dziemidowicz
</pre>
179 19 Tomek Dziemidowicz
180 2 Tomek Dziemidowicz
h2. Supported databases
181
182
h2. Samples