Skip to content

Commit

Permalink
install.html updated according to the last migration of cypht to dotenv
Browse files Browse the repository at this point in the history
  • Loading branch information
@Shadow243
Shadow243 committed Dec 22, 2023
1 parent 5614872 commit a5da80c
Showing 1 changed file with 22 additions and 18 deletions.
40 changes: 22 additions & 18 deletions install.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ <h4>2. Download and prepare the code</h4>
cd cypht-master && composer install && cd ..

# create a vanilla ini file
cp cypht-master/hm3.sample.ini cypht-master/hm3.ini
cp cypht-master/.env.example cypht-master/.env

# fix permissions and ownership
find cypht-master -type d -print | xargs chmod 755
Expand All @@ -121,9 +121,11 @@ <h4>2. Download and prepare the code</h4>

</pre>
<h4>2. Configure the program</h4>
<p>To configure Cypht for your environment, you must first edit the <a href="https://github.com/cypht-org/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>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, eliminating the need to edit the previously used hm3.ini file.</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>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>

Expand All @@ -136,13 +138,15 @@ <h4>2. Configure the program</h4>
</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>
<h4>3. 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>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>
<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>4. Enable the program in your web-server</h4>
Expand All @@ -153,7 +157,7 @@ <h4>4. Enable the program in your web-server</h4>

<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:
<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>
# create an account
php ./scripts/create_account.php username password
Expand All @@ -171,34 +175,34 @@ <h4>6. Debug mode</h4>

<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.
<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.ini file:<br />
<a href="https://github.com/cypht-org/cypht/blob/master/modules/github/github.ini">https://github.com/cypht-org/cypht/blob/master/modules/github/github.ini</a><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 ini file:<br />
<a href="https://github.com/cypht-org/cypht/blob/master/modules/imap/oauth2.ini">https://github.com/cypht-org/cypht/blob/master/modules/imap/oauth2.ini</a><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.ini file:<br />
<a href="https://github.com/cypht-org/cypht/blob/master/modules/ldap_contacts/ldap.ini">https://github.com/cypht-org/cypht/blob/master/modules/ldap_contacts/ldap.ini</a><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.ini file:<br />
<a href="https://github.com/cypht-org/cypht/blob/master/modules/wordpress/wordpress.ini">https://github.com/cypht-org/cypht/blob/master/modules/wordpress/wordpress.ini</a><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.ini 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/modules/themes/themes.ini">https://github.com/cypht-org/cypht/blob/master/modules/themes/themes.ini</a><br /><br />
<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>

Expand Down

0 comments on commit a5da80c

Please sign in to comment.