forked from cypht-org/cypht-website
-
Notifications
You must be signed in to change notification settings - Fork 0
/
install.html
195 lines (165 loc) · 13.6 KB
/
install.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
<!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 bg-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" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span onclick="document.getElementsByClassName('navbar-collapse')[0].style.display = 'block';" 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 </a>
</li>
<li class="nav-item">
<a class="nav-link " href="features.html">Features<span class="sr-only">(current)</span></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 class="nav-link" href="contribute.html">Contribute</a>
</li>
</ul>
</div>
</div>
</nav>
</header>
<section class="content-section container">
<h2>Installation</h2>
<hr>
<h2>Requirements</h2>
<p> Cypht requires at least PHP 5.4, composer, 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 here: <a href="https://github.com/jasonmunro/cypht/blob/master/composer.json#L31-L37">https://github.com/jasonmunro/cypht/blob/master/composer.json#L31-L37</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>
<h2>Steps</h2>
<h4>1. 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 hm3.ini 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
# grab latest code
wget https://github.com/jasonmunro/cypht/archive/master.zip
# unpack the archive
unzip master.zip
# run composer
cd cypht-master && composer install && cd ..
# create a vanilla ini file
cp cypht-master/hm3.sample.ini cypht-master/hm3.ini
# fix permissions and ownership
find cypht-master -type d -print | xargs chmod 755
find cypht-master -type f -print | xargs chmod 644
sudo chown -R root:root cypht-master
# copy to destination folder
sudo mv cypht-master/* $DESTINATION
# remove working directory
cd ..
sudo rm -rf cypht-temp
</pre>
<h4>2. Configure the program</h4>
<p>To configure Cypht for your environment, you must first edit the <a href="https://github.com/jasonmunro/cypht/blob/master/hm3.sample.ini">hm3.ini</a> file to your liking, then run the config_gen.php script to generate the optimized configuration file and assets used at run-time.</p>
<p>First edit the hm3.ini file to configure Cypht for your environment. If you choose to use a database for any of the 3 available purposes (authentication, sessions, or user settings), you will need to complete the "DB support" section and create the required tables. SQL to do so can be found in the hm3.sample.ini file. The ini file has lots of comments explaining what each option does.</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 hm3.ini). You can put these directories anywhere, just make sure the values in the ini file point to the right place.
</p>
<h4>3. Generate the run-time configuration</h4>
<p>Cypht uses a build process to create an optimized configuration, and to combine and minimize page assets. Once you have edited your hm3.ini file, generate the configuration with:</p>
<pre>cd /usr/local/share/cypht (or wherever you put the code in section 1)
sudo php ./scripts/config_gen.php</pre>
<p>This will create a sub-directory called site that contains the code and page assets that need to be inside the document root, and it creates an optimized configuration file called hm3.rc in the current directory. Anytime you change the ini file settings, or move the source location, you will need to re-run the config_gen script to update the program.</p>
<h4>4. 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>5. Users</h4>
<p>Setting up users depends on what type of authentication you configure in the hm3.ini file. If you are using the local database configuration for users, there are scripts in the scripts/ directory to help manage them:
<pre>
# 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>6. 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>7. Other INI files</h4>
<p>Some Cypht modules require additional ini files to be configured. These should NOT be inside the web-server document root. Cypht will look for them in the location defined by "app_data_dir" in the hm3.ini file. A sample ini file for each module set that requires one is included in the source for that module. To configure them you must copy the sample ini file to the "app_data_dir" and edit it for your setup. Some of these require configuring your service with a provider, specifically ones related to Oauth2 client setup (Github, WordPress, Oauth2 over IMAP for Gmail and Outlook). Re-run the config_gen script after configuring an ini file and it will be merged into the main configuration settings.
<ul>
<li><b>Github</b><p>Cypht can connect to github and aggregate notification data about repository activity.<br /><br />
Example github.ini file:<br />
<a href="https://github.com/jasonmunro/cypht/blob/master/modules/github/github.ini">https://github.com/jasonmunro/cypht/blob/master/modules/github/github.ini</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 ini file:<br />
<a href="https://github.com/jasonmunro/cypht/blob/master/modules/imap/oauth2.ini">https://github.com/jasonmunro/cypht/blob/master/modules/imap/oauth2.ini</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.ini file:<br />
<a href="https://github.com/jasonmunro/cypht/blob/master/modules/ldap_contacts/ldap.ini">https://github.com/jasonmunro/cypht/blob/master/modules/ldap_contacts/ldap.ini</a><br /><br />
</p></li>
<li><b>WordPress</b><p>Cypht can aggregate WordPress.com notifications.<br /><br />
Example wordpress.ini file:<br />
<a href="https://github.com/jasonmunro/cypht/blob/master/modules/wordpress/wordpress.ini">https://github.com/jasonmunro/cypht/blob/master/modules/wordpress/wordpress.ini</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.ini file to include your theme, and put the css file in modules/themes/assets.<br /><br />
<a href="https://github.com/jasonmunro/cypht/blob/master/modules/themes/themes.ini">https://github.com/jasonmunro/cypht/blob/master/modules/themes/themes.ini</a><br /><br />
</ul>
<h4>Having problems?</h4>
I'm happy to help trouble-shoot any installation issues you run into. Send a message to jason <span class="e_hl">[at]</span> cypht <span class="e_hl">[dot]</span> org and I will get back to you as soon as I can.
</section>
</body>
</html>