-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathget_started.html
More file actions
231 lines (215 loc) · 13.2 KB
/
get_started.html
File metadata and controls
231 lines (215 loc) · 13.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<link rel="stylesheet" href="res/css/style.css">
<link rel="icon" type="image/png" href="res/img/icon_neutral.png">
<title>Get started with ChiffonUpdater</title>
</head>
<body>
<div class="top">
<div class="mainlogo">
<img src="res/img/icon_neutral.png" width="128" height="128">
</div>
<h2>ChiffonUpdater Project</h2>
<h3>Updating your products has never been so easy</h3>
<img src="res/img/icon_arrow.png" width="32" height="32">
<img src="res/img/icon_globe.png" width="32" height="32">
</div>
<div class="navbar">
<a href="index.html">Home</a> | <a href="get_started.html">Get started</a> | <a href="demo.html">Demo</a> | <a
href="techdocs/">Technical Documentation</a>
</div>
<div class="main-content">
<h1>Getting started with ChiffonUpdater</h1>
<h2>This page will teach you how to configure correctly a simple infrastructure with ChiffonUpdater</h2>
<h3>First, grab a copy of the toolkit here:</h3>
<div class="bold-button-div">
<h2>
<a class="bold-button"
href="https://github.com/ExplodingBottle/ChiffonUpdater/releases/latest/download/toolkit.jar"><img
src="res/img/icon_arrow.png" width="128" height="128">Get latest Toolkit</a>
</h2>
</div>
<h3>Now, let's learn important terminology</h3>
<ul>
<li>
<b>Project (also ChiffonUpdater Project or CUPJ)</b>: This is the project file used by the toolkit which
contains all the informations about every registered products as well as various settings.<br>A software
editor should usually only need one cupj file. The project file doesn't need to be public and it is even
recommended to keep it private.
</li>
<li>
<b>Product</b>: This usually represents one software that the software editor distributes.
</li>
<li>
<b>Feature</b>: A product have at least one feature. A feature is a special set of file that a product
can have. <i>For instance, a video game could have a feature called <u>shared</u> containing shared
files, a feature called <u>zombies</u> containing files for a special zombie game mode and a feature
called <u>bonus</u> which could be a paid DLC.</i><br>
<b>Please note that the updating software doesn't support rolling back products which modified their
feature set. If you install an update then add a new feature, you won't be able to rollback.</b>
</li>
<li>
<b>Reporting file</b>: This is the file which is considered as the main file of the project and which
uses the external library to register itself to the products list.
</li>
<li>
<b>External library</b>: This is a piece of software generated by the Toolkit which should be unique to
each software editor and which is included in every products to register itself to the local product
list.
</li>
<li>
<b>Local product list</b>: A local list on the end-user computer which contains the location where the
different products are installed. Without this file, it is impossible to detect products to update.
</li>
<li>
<b>Source folder</b>: This is the folder in which every binaries should be found.
</li>
<li>
<b>BinPack</b>: A set of binary components used by ChiffonUpdater.
</li>
<li>
<b>Backend folder</b>: This is the folder that should be hosted on a server
</li>
</ul>
<h3>Selecting a source folder</h3>
At this point you will be prompted to select a source folder. For this, you can create an empty source folder
(it will be filled during the different steps).<br><b>This folder has no reason of being public, but it could be
shared in an intranet.</b>
<h3>Creating a project</h3>
At this point you learn some important terminology, you can open the toolkit. The first thing you want to do is
create a project. This project will contain your products.<br><u>Creating a new project can be done by reaching
the toolbar, and going into File > New...</u><br><br>
At this point, informations about the project are asked to you: in which folder will be the local product list
and other
core files of ChiffonUpdater. You have two choices:
<ul>
<li>
<b>Use a global path which will be independant of the system</b>: This path should not rely on system
specific environment variables.
</li>
<li>
<b>Use a system dependant path</b>: You can rely on system environment variables.
</li>
</ul>
<b>In both cases, you can surround your variable with the dollar sign (example: $variable$) to replace it with a
Java system property (a small list can be found <a
href="https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html">on this documentation
page</a>)<br>You can also surround it with the percent sign (example: %variable%) to replace it with an
OS-specific environment variable</b><br><br>
<img src="res/img/bulb.png" width="32" height="32"><b>Choosing the right path can be though
sometimes. The best
path is a folder named <i>Updates</i> under a folder shared by all the softwares of the editor.</b>
<h3>Preparing products</h3>
With the help of the toolkit, you can now generate an external library that you will have to integrate into
your products. For this, you must <u>go to Project > Generate external library</u>.<br>You will be prompted
for a BinPack selection, consider choosing GitHub (if you want to update the cached binaries) or Cached (if
the binaries are known to be already up-to-date).<br>You will afterwards be prompted for a path where to save
the external library. Once you have this external library, integrate it in your products according to the <a
href="techdocs/extlib/integration.html">technical documentation guide for integrating the external
library</a>.
<h3>Registring products</h3>
You now need to register products: this requires a little bit of planning.<br>
<img src="res/img/warn.png" width="32" height="32"><b>You can also choose not to use a source folder but this is
not supported by this tutorial page.</b>
<ol>
<h4>
<li>Preparing the structure of products</li>
</h4>
This step entirely consists on gathering informations. You will need to know what is the version in which
the external library can be integrated (this usually will be the next version of the product).<br>
Then you have to think about how will the product be divided. If it is not needed to divide the product in
different set of files, then you must put everything into one feature that you would idealy call
<b>main</b>.
<h4>
<li>Registering the product</li>
</h4>
You can now register a new product (<u>Project > Register new product</u> or <u>right click on the project
icon then Register new product</u>)<br>
Fill in the blank corresponding to the product name, and add the different features required by the
product.<br>
Once this is done, a new entry will appear in the tree: this is your product.<br>You will now have to add a
new
version entry corresponding to the first version of the program embedding the ChiffonUpdater external
library (or another
version if you are here because you are registering a new update).<br>To do so, <u>right click on your
product and click Add version</u>.<br>You can also choose a version description that will appear in the
update package or the website.<b><br>Note that each version you create will be set as the latest: their
version
rank will be the highest. You can increase and decrease the version rank.</b><br><br>
This task must be done for every products you want to register into the system.
<h4>
<li>Completing the source folder</li>
</h4>
Once you entered all the informations, you can fill the source folder. If you haven't disabled the automatic
source folder structure generation,<br>
the source folder should be organised like this (in this example, multiple versions are included):
<pre>
root of the source folder
|
|
+-- Product A -+- v1.0 -+- main
| | \- bonus
| |
| \- v2.0 -+- main
| \- bonus
|
\-- Product B -+- v1.0 -+- main
| \- bonus
|
+- v2.0 -+- main
| \- bonus
|
\- v3.0 -+- main
\- bonus
</pre>
<img src="res/img/bulb.png" width="32" height="32">You can also add other files such as EULA or custom
modules at the root of the source folder, a product folder or a version folder, <b>but avoid putting content
in a feature folder as it contains the binary files of your program and it might be interpreted as part
of the program.</b><br><br>
You will have to fill now the different folders with the different binaries of each product (this includes
the external library file). Once this is
done,<br>
you will now need to navigate to the different features of the versions of each products and press <u>Auto
add files from
folder</u> which will save the hash of the different files.<br>
</ol>
<h3>Preparing the website</h3>
First, you will have to think about two locations:
<ul>
<li>
A location which can serve a static web site in HTTP or HTTPS (for hosting the website)
</li>
<li>
A location which can act as a download server in HTTP or HTTPS (for hosting the backend folder)
</li>
</ul>
The two locations can be on the same server, but avoid putting the backend folder in the website folder and the
website folder in the backend folder.<br>
A recommended structure could be (as an example):
<pre>https://updates...........com/web (for the website) and https://updates...........com/updates (for the backend)</pre>
<br>
Once you know these two locations, create a backend folder (that can be accessed by the server or that you will
update manually on the server, for example through FTP).<br>
In the toolkit, move to the <u>Website</u> section (which should appear as Disconnected) for now.
<b>You can choose here if you want an update catalog or not. The update catalog would allow administrators to
run offline updates.</b><br><br>In <u>Backend URL</u>, write the URL which will be used to access the
backend folder through (<i>https://updates...........fr/updates/</i> in the example, <b>DO NOT FORGET THE
TRAILING SLASH!</b>)<br><br>
Once this is done, <u>right-click on the website and click Create frontend configuration file</u>. This file
contains useful informations for the website such as where to find the backend.<br>
<img src="res/img/bulb.png" width="32" height="32">If you change the backend URL, you will have to regenerate
this file.<br><br>
<b>This file must replace the <i>res/js/config/webcucfg.js</i> file in the website folder.</b>.<br><br>
We now have a final step which consists of synchronizing the backend folder. To do so, you must first tell the
tookit where can it modify the folder. To do so, <u>right-click on Website and press Connect backend folder</u>,
then choose the local path to the backend folder.<br>
You now only need to <u>right-click on Website and press Synchronize backend files</u>, and go through the
different steps.
<h2>Congrats, you now have a working ChiffonUpdater update infrastructure running and accessible!</h2>
<b>While this tutorial covered what to do to get a running infrastructure, don't forget to check the <a
href="techdocs/">technical documentation</a> for many more information</b>
</div>
</body>
</html>