forked from cypht-org/cypht-website
-
Notifications
You must be signed in to change notification settings - Fork 0
/
install-2x.html
383 lines (338 loc) · 18.9 KB
/
install-2x.html
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
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
<!DOCTYPE html>
<html class="no-js">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>Install</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/png" href="icon.ico">
<link rel="stylesheet" href="site.css">
</head>
<body>
<header>
<nav class="navbar navbar-expand-lg navbar-dark fixed-top">
<div class="container">
<a class="navbar-brand" href="index.html">
<img src="img/logo.svg" width="120" height="60" alt="">
</a>
<button class="navbar-toggler toggler-home" type="button" data-toggle="collapse"
data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false"
aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse " id="navbarSupportedContent">
<ul class="navbar-nav ml-lg-auto">
<li class="nav-item">
<a class="nav-link" href="index.html">Home <span class="sr-only">(current)</span>
</a>
</li>
<li class="nav-item">
<a class="nav-link" href="features.html">Features</a>
</li>
<li class="nav-item">
<a class="nav-link" href="security.html">Security</a>
</li>
<li class="nav-item">
<a class="nav-link" href="modules.html">Mods</a>
</li>
<li class="nav-item">
<a class="nav-link" href="license.html">License</a>
</li>
<li class="nav-item">
<!--<a class="nav-link" href="tests.html">Test</a>-->
</li>
<li class="nav-item">
<a class="nav-link" href="documentation.html">Documentation</a>
</li>
<li class="nav-item">
<a class="nav-link" href="https://unencumberedbyfacts.com">Blog</a>
</li>
<li class="nav-item">
<a onclick="document.getElementsByClassName('navbar-collapse')[0].style.display='none';" class="nav-link"
href="contribute.html">Contribute</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<section class="content-section container">
<h2>Install Cypht v2.x</h2>
<p>You can install specific versions of Cypht:</p>
<p>
<a href="install.html">
<button type="button" class="btn btn-success">Cypht master</button>
</a>
<a href="install-1x.html">
<button type="button" class="btn btn-success">Cypht v1.4.x</button>
</a>
<a href="install-2x.html">
<Cypht type="button" class="btn btn-success">Cypht v2.x</button>
</a>
</p>
<p>Cypht has four differents installation ways:</p>
<ul>
<li>Manual installation</li>
<li>Installation within Tiki</li>
<li>install using Docker (use cypht docker image)</li>
<li>Install cypht on a YunoHost server</li>
</ul>
<p>Please read the bellow explanations about each way and pick one of your choice.</p>
<hr>
<h2>1. Manual installation</h2>
<h2>Requirements</h2>
<p>Cypht 2.x requires at least PHP 8.1,<a href="https://getcomposer.org/">Composer 2</a>, and at minimum the <a
href="http://php.net/manual/en/book.openssl.php">OpenSSL</a>, <a
href="http://php.net/manual/en/book.mbstring.php">mbstring</a> and <a
href="http://php.net/manual/en/book.curl.php">cURL</a> extensions. Cypht can also leverage several other
extensions as defined in <a
href="https://github.com/cypht-org/cypht/blob/master/composer.json#L37-L44">composer.json</a>.
Testing is done on <a href="https://www.debian.org/">Debian</a> and <a href="http://www.ubuntu.com/">Ubuntu</a>
platforms with <a href="http://nginx.com/">Nginx</a> and <a href="http://httpd.apache.org/">Apache</a>.
</p>
<p>Before proceeding please make sure your system meets minimal requirements</p>
<h2>Steps</h2>
<h4>1. Check minimum requirements</h4>
<p>
<pre>
#!/bin/bash
# You need to check php version which should be >=8.1
php --version
# Next you need to check composer version which should be >=2.0.0
composer --version
# List installed PHP extensions. at least OpenSSL, mbstring and cURL should be in the list
php -m</pre>
</p>
<h4>2. Download and prepare the code</h4>
<p>It's important to consider where you put the Cypht source. The web-server will need read-only access to it, and
moving it from one place to another requires re-running the configuration script. Do NOT put the source in the
document root as this could create a security risk. On Debian, it's common to use the /usr/local/share/
sub-directory for a situation like this. Here is short bash script that will download the latest code, setup the
correct permissions and ownership, put the source in /usr/local/share/cypht, and create a default .env file. It
requires sudo access:
</p>
<pre>
#!/bin/bash
# this is where Cypht will be installed
DESTINATION="/usr/local/share/cypht"
# validate the destination directory
sudo test -r $DESTINATION -a -x $DESTINATION
if [ $? -ne 0 ]; then
sudo mkdir $DESTINATION
fi
# create working directory
mkdir cypht-temp
cd cypht-temp
# Fetch latest release information
$latest_release = Invoke-RestMethod -Uri "https://api.github.com/repos/cypht-org/cypht/releases/latest"
# Extract tag name of the latest release
$latest_tag = $latest_release.tag_name
# Construct download URL for the latest release within the 2.x series
$download_url = "https://github.com/cypht-org/cypht/archive/refs/tags/$latest_tag.zip"
# Download the latest release
Invoke-WebRequest -Uri $download_url -OutFile "latest_cypht_release.zip"
# unpack the archive
unzip latest_cypht_release.zip
# run composer
cd latest_cypht_release && composer install && cd ..
# create a .env file
cp latest_cypht_release/.env.example latest_cypht_release/.env
# fix permissions and ownership
find latest_cypht_release -type d -print | xargs chmod 755
find latest_cypht_release -type f -print | xargs chmod 644
sudo chown -R root:root latest_cypht_release
# copy to destination folder
sudo mv latest_cypht_release/* $DESTINATION
# remove working directory
cd ..
sudo rm -rf cypht-temp
</pre>
<h4>3. Configure the program</h4>
<p>To configure Cypht for your environment, make adjustments to the <a
href="https://github.com/cypht-org/cypht/blob/master/.env.example">.env</a> file according to your preferences.
The .env file serves as the primary configuration file.</p>
<p>First edit the .env file to configure Cypht for your environment. If you choose to leverage a database for
authentication, sessions, or user settings, ensure to complete the relevant sections within the .env file based on
the information provided in the config/app.php file.</p>
<p>The necessary SQL commands for creating tables can be found in the config/app.php file, specifically starting
from line 617 in the "DB Sessions" section. </p>
<p>Cypht needs read, and read-write access to a few directories on the server. For security reasons these should NOT
be inside the web-server document root. A good place for these is under the /var/lib/ sub-directory. Here are the
commands To create the required directories per the default values in the ini file (assuming your web-server
software runs as the "www-data" user).</p>
<pre>
sudo mkdir /var/lib/hm3
sudo mkdir /var/lib/hm3/attachments
sudo mkdir /var/lib/hm3/users
sudo mkdir /var/lib/hm3/app_data
sudo chown -R www-data /var/lib/hm3/
</pre>
<p>The /var/lib/hm3/users directory is only required if you are using the file-system and not a database to store
user settings (user_config_type = file in the .env). You can put these directories anywhere, just make sure the
values in the ini file point to the right place.
</p>
<h4>4. Generate Dynamic Run-Time Configuration</h4>
<p>Cypht utilizes a build process to create an optimized configuration and to combine and minimize page assets.
Previously, after editing the hm3.ini file, the configuration and asset minimization were generated using the
following steps:</p>
<pre>cd /usr/local/share/cypht (or wherever you put the code in section 1)
sudo php ./scripts/config_gen.php</pre>
<p>Recent updates have streamlined the process, and running the command above will now specifically generate the
config/dynamic.php file. This file incorporates dynamic configurations, including 'handler_modules,'
'output_modules,' and 'input_filters.' Furthermore, the command continues to optimize the configuration and
combine/minimize page assets, ensuring efficient runtime operation.</p>
<p>Additionally, executing this command will create a sub-directory called 'site' that contains the code and page
assets required within the document root. If you ever relocate the source location, you'll need to re-run the
config_gen script to update the program.</p>
<h4>5. Enable the program in your web-server</h4>
<p>The easiest way to serve Cypht is to symlink it to the web-server document root. You can also copy the generated
files to your web-server location, but then you will need to re-copy them anytime the config_gen script is run. If
the source is located at /usr/local/share/cypht, and the web-server document root is at /var/www/html, the
following command will make Cypht available under the "mail" path of the
web-server:</p>
<pre>sudo ln -s /usr/local/share/cypht/site /var/www/html/mail</pre>
<p>Now going to https://your-server/mail/ should load the Cypht login page. Note that If you use a symlink, your
web-server must be configured to follow symlinks.</p>
<h4>6. Users</h4>
<p>Setting up users depends on what type of authentication you configure in the config/app.php file. If you are
using the local database configuration for users, there are scripts in the scripts/ directory to help manage them:
<pre>
# Generate necessary tables to manage users,sessions, or settings depending on the configuration in the .env file
php ./scripts/setup_database.php
# create an account
php ./scripts/create_account.php username password
# delete an account
php ./scripts/delete_account.php username
# change an account password
php ./scripts/update_password.php username password
</pre>
</p>
<h4>7. Debug mode</h4>
<p>Cypht has a debug or developer mode that can be used to troubleshoot problems or enable faster development of
modules. To enable the debug version of Cypht, just sym-link the entire source directory instead of the site
sub-directory:</p>
<pre>sudo ln -s /usr/local/share/cypht /var/www/html/mail-debug</pre>
<p>Debug mode is not as efficient as the normal version, and it is NOT designed to be secure. DO NOT RUN DEBUG MODE
IN PRODUCTION. You have been warned! Debug mode outputs lots of information to the PHP error log that can be
useful for trouble-shooting problems. The location of the error log varies based on your php.ini settings and
web-server software.</p>
<h4>8. Other Configs files</h4>
<p>Some Cypht modules necessitate additional configuration files for proper setup. It is crucial that these files
are NOT located within the web-server document root. Certain modules may require configuration with a service
provider, particularly those related to Oauth2 client setup (such as Github, WordPress, Oauth2 over IMAP for
Gmail, and Outlook). After configuring related files, there is no need to rerun the config_gen script; the changes
will be automatically merged into the main configuration settings.Alternatively, you can clear your app cache.
<ul>
<li><b>Github</b>
<p>Cypht can connect to github and aggregate notification data about repository activity.<br /><br />
Example github.php file:<br />
<a
href="https://github.com/cypht-org/cypht/blob/master/config/github.php">https://github.com/cypht-org/cypht/blob/master/config/github.php</a><br /><br />
Authorize an application for github:<br />
<a href="https://github.com/settings/developers">https://github.com/settings/developers</a>
</p>
</li>
<li><b>OAUTH2 over IMAP</b>
<p>Gmail and Outlook.com support OAUTH2 authentication over IMAP. This is preferable to normal IMAP
authentication because Cypht never has access to your account password.<br /><br />
Example oauth2.php file:<br />
<a
href="https://github.com/cypht-org/cypht/blob/master/config/oauth2.php">https://github.com/cypht-org/cypht/blob/master/config/oauth2.php</a><br /><br />
Authorize an application for gmail<br />
<a
href="https://console.developers.google.com/project">https://console.developers.google.com/project</a><br /><br />
Authorize an application for outlook.com<br />
<a
href="https://account.live.com/developers/applications/">https://account.live.com/developers/applications/</a><br /><br />
</p>
</li>
<li><b>LDAP contacts</b>
<p>Cypht can use an LDAP server for contacts.<br /><br />
Example ldap.php file:<br />
<a
href="https://github.com/cypht-org/cypht/blob/master/config/ldap.php">https://github.com/cypht-org/cypht/blob/master/config/ldap.php</a><br /><br />
</p>
</li>
<li><b>WordPress</b>
<p>Cypht can aggregate WordPress.com notifications.<br /><br />
Example wordpress.php file:<br />
<a
href="https://github.com/cypht-org/cypht/blob/master/config/wordpress.php">https://github.com/cypht-org/cypht/blob/master/config/wordpress.php</a><br /><br />
Authorize an application for WordPress.com:<br />
<a href="https://developer.wordpress.com/apps/">https://developer.wordpress.com/apps/</a>
</p>
</li>
<li><b>Custom themes</b>
<p>You can create your own themes for Cypht. Edit the themes.php file to include your theme, and put the css
file in modules/themes/assets.<br /><br />
<a
href="https://github.com/cypht-org/cypht/blob/master/config/themes.php">https://github.com/cypht-org/cypht/blob/master/config/themes.php</a><br /><br />
</ul>
<h2>2. Install cypht using Docker</h2>
<p>
Using Docker is one of the easiest way to install cypht as the cypht docker image comes with all the steps
required in the manual instalation done for you. But the bad news is that this installation way requires docker
knowledge.<br />
Here is the cypht docker repository: <a
href="https://hub.docker.com/r/cypht/cypht">https://hub.docker.com/r/cypht/cypht</a><br />
To run containers required by cypht, please, first make sure you have docker and docker-compose installed on your
system, then take a look on the section "example docker-compose" of repository overview, then do the following:
</p>
<ul>
<li>Create a new directory on your system named as you want.</li>
<li>In the directory created previously, create a file named "docker-compose.yaml" then copy and paste the content of <a href="https://github.com/cypht-org/cypht/blob/2.x/docker/docker-compose.yaml">the example docker-compose file</a> in the created file or just download the example docker-compose file in the previously created directory.</li>
<li>Open your CLI/terminal and move to the directory containing the docker-compose file and run the command to
run containers
<pre>docker-compose up -d</pre>
</li>
<li>After containers started, you can access cypht on port 80 of your host if you didn't change the port value in
the docker-compose file.</li>
</ul>
<p>
NOTE: Please change usernames and passwords before using the given docker-compose code in your production
environment.
</p>
<h2>3. Install Cypht on a YunoHost server</h2>
<p>This is an other easy way of installing and use Cypht.<br>
YunoHost is an operating system that aims to simplify server administration as much as possible to democratize
self-hosting while remaining reliable,
secure, ethical and lightweight. It is a free software project owned exclusively by volunteers. Technically, it
can be seen as a distribution based on
Debian GNU/Linux and can be installed on many types of hardware.<br />
To learn more about YunoHost, visit <a
href="https://yunohost.org/en/overview/what_is_yunohost">https://yunohost.org/en/overview/what_is_yunohost</a>
</p>
<p>To install Cypht on YunoHost, please follow these steps:</p>
<ul>
<li>If you don't have an installed YunoHost server, please consult <a href="https://yunohost.org/#/install">the
guide</a> to learn how to install it. If you have it, please go directly to the next step.</li>
<li>If you just installed YunoHost or had it installed before, access your server and go to the admin dashboard,
then click on "Applications"</li>
<li>In the next page, click on the "install" button</li>
<li>In the search area, enter "cypht"</li>
<li>In the search result, click on cypht app</li>
<li>Scroll down, then fill in the form according to your need or keep the default values, then clik on the
"install" button. Note: Make sure the url value is not
used by another app on the server or in case you have another cypht instance previously installed you have to
modify it instead of using the default valuue.
</li>
<li>Once clicked on the "install" button, wait for the installation to complete, it may take while.</li>
<li>Once the installation completed, you will be taking back to the dashboard.</li>
<li>To open the app, click on the app recently installed and then on the "open the app" button, then the
application opens in a new tab.</li>
<li>Enter the username and admin password you've provided previously in the installation form and then click on
the login button to enter cypht and start configuring your email accounts.</li>
</ul>
<h2>4. Install Cypht within Tiki</h2>
<p>If you have tiki installed, you can use Cypht within tiki. This is an easy way of installing Cypht.<br />
Please follow the following link for a complete guide of how to install and use cypht within Tiki.</br>
<a href="https://doc.tiki.org/Webmail">https://doc.tiki.org/Webmail</a>
</p></br>
<h4>Having problems?</h4>
We are happy to help trouble-shoot any installation issues you run into. Chat with us at Gitter <a href="https://gitter.im/cypht-org/community">Cypht at Gitter</a> and We'll get back to you as soon as we can.
</section>
<script src="jquery.slim.min.js"></script>
<script src="bootstrap.bundle.min.js"></script>
</body>
</html>