README.md (6487B)
1 # ktistec tweaks
2
3 Small tweaks and hacks for [ktistec](https://github.com/toddsundsted/ktistec).
4
5 Please send patches or remarks to
6 [jayvii+ktistec-tweaks[AT]posteo[DOT]de](mailto:jayvii+ktistec-tweaks[AT]posteo[DOT]de).
7
8 ---
9
10 ## Docker
11
12 You can run ktistec via the provided
13 [`docker-compose`](https://docs.docker.com/compose/)
14
15 ```bash
16 cd docker/
17 docker-compose -f docker-compose.yaml up -d
18 ```
19
20 In order to use
21 [machine generated translations](https://github.com/toddsundsted/ktistec/?tab=readme-ov-file#configuring-translation),
22 you can set the `DEEPL_API_KEY` or the `LIBRETRANSLATE_API_KEY` environment
23 variables while starting up the container:
24
25 ```bash
26 cd docker/
27 LIBRETRANSLATE_API_KEY="abcd" docker-compose -f docker-compose.yaml up -d
28 ```
29
30 ---
31
32 ## CSS
33
34 Currently, the `./css/` directory contains three theming tweaks:
35
36 - [purple-ish](#purple-ish-theme): a modern theme with automatic dark/bright
37 mode and purple highlights
38 - [mobile](#mobile): small adjustments of the layout to make the UI more
39 appealing for mobile users
40 - [visibility](#visibility): small adjustments to improve visibility of content
41 in the sense of accessibility
42
43 ### Purple-Ish Theme:
44
45 
46
47 ### Mobile:
48
49 
50
51 
52
53 
54
55 
56
57 ### Visibility:
58
59 
60
61 
62
63 The *Visibility* CSS rules also mark all external URLs with an arrow-icon. For
64 this to work properly, you have to inject your ktistec's domain into the CSS
65 file. For example, if your ktistec is running under `social.example.com`, run
66 following command before deploying the CSS file to your ktistec instance:
67
68 ```bash
69 sed -e 's/\/\/localhost/\/\/social.example.com/g' -i css/visibility.css
70 sed -e 's/\/\/localhost/\/\/social.example.com/g' -i css/visibility.min.css
71 ```
72
73 **Minify CSS:**
74
75 ```bash
76 make minify-css
77 ```
78
79 Place the minified `purpleish.min.css`, `layout.min.css` and/or
80 `visibility.min.css`in the `public/3rd/` directory and at **AT THE START OF**
81 `public/3rd/semantic-2.4.1.min.css`:
82
83 ```css
84 @import url('purpleish.min.css');
85 @import url('visibility.min.css');
86 @import url('mobile.min.css');
87
88 /* ... rest of the file's content */
89 ```
90
91 **Manual installation:**
92
93 ```bash
94 KTISTEC_PATH="/var/www/ktistec"
95 KTISTEC_CSS="${KTISTEC_PATH}/public/3rd"
96 cp ./css/*.min.css ${KTISTEC_CSS}/
97 cp -r ./css/icons ${KTISTEC_CSS}/icons
98 echo "@import url('purpleish.min.css');" > ${KTISTEC_CSS}/tmp
99 echo "@import url('visibility.min.css');" >> ${KTISTEC_CSS}/tmp
100 echo "@import url('mobile.min.css');" >> ${KTISTEC_CSS}/tmp
101 cat ${KTISTEC_CSS}/semantic-*.min.css >> ${KTISTEC_CSS}/tmp
102 mv ${KTISTEC_CSS}/tmp ${KTISTEC_CSS}/semantic-*.min.css
103 ```
104
105 **Docker (via [this repo's docker-compose](#docker) file):**
106
107 ```bash
108 docker cp ./css/purpleish.min.css ktistec:/app/public/3rd/purpleish.min.css
109 docker cp ./css/visibility.min.css ktistec:/app/public/3rd/visibility.min.css
110 docker cp ./css/mobile.min.css ktistec:/app/public/3rd/mobile.min.css
111 docker cp ./css/icons ktistec:/app/public/3rd/icons
112 docker exec -ti ktistec \
113 sh -c "
114 echo \"@import url('purpleish.min.css');\" > /app/public/3rd/tmp && \
115 echo \"@import url('visibility.min.css');\" >> /app/public/3rd/tmp && \
116 echo \"@import url('mobile.min.css');\" >> /app/public/3rd/tmp && \
117 cat /app/public/3rd/semantic*.css >> /app/public/3rd/tmp && \
118 mv /app/public/3rd/tmp /app/public/3rd/semantic-*.min.css
119 "
120 ```
121
122 ## Backups
123
124 ### Database
125
126 Database backups should be done either by file-copying **when the database is
127 not in use**, i.e. as long as ktistec is not running, or better yet with the
128 [`.backup`](https://sqlite.org/cli.html#special_commands_to_sqlite3_dot_commands_)
129 command, which handles file-locking and changes to the database during the
130 backup procedure. However, either way, because `.backup` also honours file
131 locking by the ktistec process itself and because changes to the database
132 are constantly accounted for (which, depending on your instances volume, can
133 prolonge the backup process indefinitely), ktistec should not be running during
134 backup process.
135
136 **Manual installation:**
137
138 ```bash
139 KTISTEC_PATH="/var/www/ktistec"
140 kill server && \
141 sqlite3 ${KTISTEC_PATH}/db/ktistec.db \
142 ".backup \"${KTISTEC_PATH}/db/ktistec_backup_$(date +%Y-%m-%d).sq3\""; \
143 ${KTISTEC_PATH}/server &
144 ```
145
146 **Docker (via [this repo's docker-compose](#docker) file):**
147
148 ```bash
149 docker stop ktistec && \
150 docker run -ti --rm \
151 -v /var/www/ktistec/db:/db \
152 -v /var/www/ktistec/backups:/backups \
153 alpine:latest \
154 sh -c '
155 apk update && \
156 apk add sqlite && \
157 sqlite3 /db/ktistec.db \
158 ".backup \"/backups/ktistec_backup_$(date +%Y-%m-%d).sq3\""
159 '; \
160 docker restart ktistec
161 ```
162
163 ### Uploads
164
165 The uploads-folder contains images and other media files that you uploaded or
166 included in one of your posts. It makes sense to back them up as well in order
167 to prevent data loss.
168
169 Since these are typically just image files, the easiest way to back them up is
170 by archiving them with `tar`.
171
172 **Manual installation:**
173
174 ```bash
175 KTISTEC_PATH="/var/www/ktistec"
176 tar -cf ${KTISTEC_PATH}/uploads_backup_$(date +%Y-%m-%d).tar \
177 ${KTISTEC_PATH}/public/uploads/
178 ```
179
180 **Docker (via [this repo's docker-compose](#docker) file):**
181
182 ```bash
183 docker run -ti --rm \
184 -v /var/www/ktistec/uploads:/uploads \
185 -v /var/www/ktistec/backups:/backups \
186 alpine:latest \
187 sh -c '
188 apk update && \
189 apk add tar && \
190 tar -vcf /backups/uploads_backup_$(date +%Y-%m-%d).tar /uploads/
191 '
192 ```
