|
2 | 2 |
|
3 | 3 | Guest operated service for creating bootable USB storage devices at any community conference kiosk |
4 | 4 |
|
5 | | -## Screenshots |
| 5 | +## Instruction |
6 | 6 |
|
7 | | - |
8 | | - |
9 | | - |
10 | | - |
11 | | -## Features |
12 | | - |
13 | | -### For development |
14 | | -- Minimal command line interface based configuration with wide range of customizable options |
15 | | -- Stellar overall codebase quality is ensured with 100% coverage of functional backend code |
16 | | -- Over 34 checks are provided for unit based, end-to-end based integration based codebase testing |
17 | | -- GitHub Actions and Pre-Commit CI are enabled to automate maintenance of codebase quality |
18 | | - |
19 | | -### For consumption |
20 | | -- Asynchronous multiprocessing allows for flashing multiple storage devices simultaneously |
21 | | -- Programming standards and engineering methodologies are maintained as much as possible |
22 | | -- Frontend is adaptive across various viewport types and browser-side assistive technologies |
23 | | -- Detailed documentation for both consumption and development purposes are readily provided |
24 | | - |
25 | | -## Installation |
26 | | - |
27 | | -### For development |
28 | | - |
29 | | -1. Install the supported version of Python, Virtualenv, Poetry, Redis and CoreUtils on your Fedora Linux installation. |
30 | | - ``` |
31 | | - $ sudo dnf install python3 python3-virtualenv poetry |
32 | | - ``` |
33 | | - ``` |
34 | | - $ sudo dnf install redis coreutils |
35 | | - ``` |
36 | | -
|
37 | | -2. Clone the repository to your local storage and make it your present working directory. |
38 | | - ``` |
39 | | - $ git clone https://github.com/gridhead/syncstar.git |
40 | | - ``` |
41 | | - ``` |
42 | | - $ cd syncstar |
43 | | - ``` |
44 | | -
|
45 | | -3. Establish a virtual environment within the project and activate it for installing dependencies. |
46 | | - ``` |
47 | | - $ virtualenv venv |
48 | | - ``` |
49 | | - ``` |
50 | | - $ source venv/bin/activate |
51 | | - ``` |
52 | | -
|
53 | | -4. Check the validity of the project configuration and install the dependencies from the lockfile. |
54 | | - ``` |
55 | | - (venv) $ poetry check |
56 | | - ``` |
57 | | - ``` |
58 | | - (venv) $ poetry install |
59 | | - ``` |
60 | | -
|
61 | | -### For consumption |
62 | | -
|
63 | | -1. Install the supported version of Python, Python Package Installer Redis CoreUtils on your Fedora Linux installation. |
64 | | - ``` |
65 | | - $ sudo dnf install python3 python3-pip |
66 | | - ``` |
67 | | - ``` |
68 | | - $ sudo dnf install redis coreutils |
69 | | - ``` |
70 | | -
|
71 | | -2. Elevate the privileges to the superuser level and install the `syncstar` package from Python Package Index. |
72 | | - ``` |
73 | | - $ sudo -s |
74 | | - ``` |
75 | | - ``` |
76 | | - # pip3 install syncstar |
77 | | - ``` |
78 | | -
|
79 | | -3. Configure the service unit files for the endpoint service and worker service to the system services directory. |
80 | | - ``` |
81 | | - $ sudo wget https://raw.githubusercontent.com/gridhead/syncstar/main/syncstar/system/endpoint.service -O /etc/systemd/system/ss-endpoint.service |
82 | | - ``` |
83 | | - ``` |
84 | | - $ sudo wget https://raw.githubusercontent.com/gridhead/syncstar/main/syncstar/system/worker.service -O /etc/systemd/system/ss-worker.service |
85 | | - ``` |
86 | | -
|
87 | | -4. Enable the service unis for the endpoint service and worker services. |
88 | | - ``` |
89 | | - $ sudo systemctl enable ss-endpoint.service |
90 | | - ``` |
91 | | - ``` |
92 | | - $ sudo systemctl enable ss-worker.service |
93 | | - ``` |
94 | | -
|
95 | | -## Initialization |
96 | | -
|
97 | | -1. Download the Fedora Linux live images to a certain directory and make the images archive configuration file. |
98 | | - ``` |
99 | | - $ wget https://download.fedoraproject.org/pub/fedora/linux/releases/40/Workstation/x86_64/iso/Fedora-Workstation-Live-x86_64-40-1.14.iso |
100 | | - ``` |
101 | | - ``` |
102 | | - $ cp Fedora-Workstation-Live-x86_64-40-1.14.iso /etc/syncstar/images/Fedora-Workstation-Live-x86_64-40-1.14.iso |
103 | | - ``` |
104 | | -
|
105 | | -2. Download the images archive configuration file and make changes to include the recently downloaded image files. |
106 | | - ``` |
107 | | - $ wget https://raw.githubusercontent.com/gridhead/syncstar/main/syncstar/config/images.yml -O /etc/syncstar/images.yml |
108 | | - ``` |
109 | | - ``` |
110 | | - $ nano /etc/syncstar/images.yml |
111 | | - ``` |
112 | | -
|
113 | | -3. Set the value of the following environment variable as the present location of the images archive configuration file. |
114 | | - ``` |
115 | | - $ nano /home/$(whoami)/.bashrc |
116 | | - ``` |
117 | | - ``` |
118 | | - $ export SYNCSTAR_ISOSYAML=/etc/syncstar/images.yml |
119 | | - ``` |
120 | | -
|
121 | | -4. Enable the Redis service unit and check the status of the service. |
122 | | - ``` |
123 | | - $ sudo systemctl enable redis.service |
124 | | - ``` |
125 | | - ``` |
126 | | - $ sudo systemctl status redis.service |
127 | | - ``` |
128 | | -
|
129 | | -## Execution |
130 | | -
|
131 | | -### For development |
132 | | -
|
133 | | -1. Ensure that the Redis service unit is active and check the status of the service. |
134 | | - ``` |
135 | | - $ sudo systemctl start redis.service |
136 | | - ``` |
137 | | - ``` |
138 | | - $ sudo systemctl status redis.service |
139 | | - ``` |
140 | | -
|
141 | | -2. In a separate terminal session, execute the following command to start the endpoint service in an activated virtual environment. |
142 | | - ``` |
143 | | - $ source venv/bin/activate |
144 | | - ``` |
145 | | - ``` |
146 | | - (venv) $ syncstar --port 8080 --repair false --period 2 --images $SYNCSTAR_ISOSYAML |
147 | | - ``` |
148 | | - - This will start the endpoint service on port 8080 available across all network interfaces of the host device. |
149 | | - - The debug mode for the endpoint service will be disabled and the information would be refreshed after 2 seconds. |
150 | | - - The images archive configuration file mentioned previously will be used as a source for the live images. |
151 | | - - Dictionaries consisting of task schedules will not persist after a live reload when using the debug mode. |
152 | | -
|
153 | | -3. In a separate terminal session, execute the following command to start the worker service in an activated virtual environment |
154 | | - ``` |
155 | | - $ source venv/bin/activate |
156 | | - ``` |
157 | | - ``` |
158 | | - (venv) $ sudo SYNCSTAR_ISOSYAML=/etc/syncstar/images.yml celery -A syncstar.task.taskmgmt worker --loglevel=info |
159 | | - ``` |
160 | | - - This will start the worker service that would accept tasks requested by the users of the endpoint service. |
161 | | - - The debug mode for the worker service will be disabled and there will be a default concurrency of 12 processes. |
162 | | - - The images archive configuration file mentioned previously will be used as a source for the live images. |
163 | | - - Dictionaries consisting of task schedules will not persist after a live reload when using the debug mode. |
164 | | -
|
165 | | -4. Visit the homepage of the endpoint service using the browser of your choice to get started with using SyncStar. |
166 | | -
|
167 | | -### For consumption |
168 | | -
|
169 | | -1. Ensure that the Redis service unit is active and check the status of the service. |
170 | | - ``` |
171 | | - $ sudo systemctl start redis.service |
172 | | - ``` |
173 | | - ``` |
174 | | - $ sudo systemctl status redis.service |
175 | | - ``` |
176 | | -
|
177 | | -2. Start the endppint service unit and check the status of the service. |
178 | | - ``` |
179 | | - $ sudo systemctl start ss-endpoint.service |
180 | | - ``` |
181 | | - ``` |
182 | | - $ sudo systemctl status ss-endpoint.service |
183 | | - ``` |
184 | | -
|
185 | | -3. Start the worker service unit and check the status of the service. |
186 | | - ``` |
187 | | - $ sudo systemctl start ss-worker.service |
188 | | - ``` |
189 | | - ``` |
190 | | - $ sudo systemctl status ss-worker.service |
191 | | - ``` |
192 | | -
|
193 | | -4. Visit the homepage of the endpoint service using the browser of your choice to get started with using SyncStar. |
194 | | -
|
195 | | -## Organization |
196 | | -
|
197 | | -1. The images archive configuration file stores an unordered dictionary of images archives available for usage. |
198 | | - ``` |
199 | | - $ cat /etc/syncstar/images.yml |
200 | | - ``` |
201 | | -
|
202 | | -2. The identifier for the images archives is the message digest text which can be found out using the following command. |
203 | | - ``` |
204 | | - $ cat Fedora-Workstation-Live-x86_64-40-1.14.iso | sha256sum |
205 | | - ``` |
206 | | -
|
207 | | -3. The second line per images archive entry stores the location of the file which is validated on every task run. |
208 | | - ``` |
209 | | - path: /home/archdesk/Downloads/Fedora-Workstation-Live-x86_64-40-1.14.iso |
210 | | - ``` |
211 | | -
|
212 | | -4. The third line per images archive entry stores the name that would be displayed to the users on the service frontend. |
213 | | - ``` |
214 | | - name: Fedora Linux 40 Workstation rc1.14 |
215 | | - ``` |
216 | | -
|
217 | | -5. The fourth line per images archive entry stores the type that would be used for metadata generation purposes. |
218 | | - ``` |
219 | | - type: fedora |
220 | | - ``` |
221 | | -
|
222 | | -6. The images archive that have not been provided with one of the supported types would be provided with the generic type. |
223 | | - ``` |
224 | | - type: common |
225 | | - ``` |
226 | | -
|
227 | | -7. The images archive should be verified for their consistency by the service administrators before consumption. |
228 | | - ``` |
229 | | - $ wget https://download.fedoraproject.org/pub/fedora/linux/releases/40/Workstation/x86_64/iso/Fedora-Workstation-40-1.14-x86_64-CHECKSUM |
230 | | - ``` |
231 | | -
|
232 | | -8. The following types of images archive are supported for metadata generation purposes used on the service frontend. |
233 | | -
|
234 | | - | # | Name | Identity | Icon | |
235 | | - |----|--------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
236 | | - | 1 | Android | `gdroid` |  | |
237 | | - | 2 | Arch Linux | `archlx` |  | |
238 | | - | 3 | CentOS Stream | `centos` |  | |
239 | | - | 4 | Debian Linux | `debian` |  | |
240 | | - | 5 | Fedora Linux | `fedora` |  | |
241 | | - | 6 | Kodi or XBMC | `kodimc` |  | |
242 | | - | 7 | Linux Mint | `lxmint` |  | |
243 | | - | 8 | Manjaro Linux | `mnjaro` |  | |
244 | | - | 9 | Red Hat Enterprise Linux | `redhat` |  | |
245 | | - | 10 | OpenSUSE Linux | `opsuse` |  | |
246 | | - | 11 | Ubuntu Linux | `ubuntu` |  | |
247 | | - | 12 | Generic | `common` |  | |
248 | | -
|
249 | | -## Appreciation |
250 | | -
|
251 | | -If you like the efforts made here and want to support the development of the project, please consider giving a star to |
252 | | -the project and forking it your namespace. I appreciate all kinds of contributions - ranging from small sized bug fixes |
253 | | -to major sized feature additions as well as from trivial documentation changes to awesome codebase refactoring. Even if |
254 | | -you do not have the capacity to take the development for a spin, you can help me out by testing out the project and |
255 | | -getting in touch with me on the issue tracker with the things that must be fixed and the things that should be introduced. |
| 7 | +Please visit the [documentation](https://github.com/gridhead/syncstar/wiki) to know more about the project |
0 commit comments