diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..3795408 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,49 @@ +# Based on https://github.com/actions/starter-workflows/blob/main/pages/static.yml +name: Build static & deploy to GitHub Pages + +on: + # Runs on pushes targeting specified branch + push: + branches: ["cecil"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + + # Allows this workflow to be called from other workflows + workflow_call: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: shivammathur/setup-php@v2 + - name: Setup GitHub Pages + uses: actions/configure-pages@v5 + + - name: Build static + run: php cecil.phar build + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: '_site/' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/.gitignore b/.gitignore index d8f8d46..a18501a 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,5 @@ docs + +_site/ +.cache* +.cecil \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..6902050 --- /dev/null +++ b/Makefile @@ -0,0 +1,12 @@ +all: data/configOptions.json + +.PHONY: build +build: + php cecil.phar build + +.PHONY: serve +serve: + php cecil.phar serve + +data/configOptions.json: + php data/fetch.php diff --git a/README.md b/README.md index 8114c25..2371914 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,28 @@ # cypht-website -This is the source of the [cypht.org](https://cypht.org/) website. It's simple static HTML with no +This is the source of the [cypht.org](https://cypht.org/) website. It's a HTML site statically generated with [cecil](https://cecil.app/), with no non-vendor JavaScript. Cypht (pronounced "sift") is like a news reader, but for E-mail. Cypht does not replace your existing accounts - it combines them into one. And it's also a news reader. As of 2024-02-14, www.cypht.org updates from https://github.com/cypht-org/cypht-website/ on a daily cron job. + +## How-to +### Build locally +This requires git & PHP 8 to be installed. +```bash +git clone https://github.com/cypht-org/cypht-website.git +cd cypht-website + +# Build to _site/ +php cecil.phar build # alt: make build + +# Serve/develop on localhost:8000 +php cecil.phar serve # alt: make serve +``` + +Nix users can use `nix-shell -p php81 gnumake git` to get all requirements to build. + +### Update config generator options +```bash +# In project root +rm data/configOptions.json +php data/fetch.php # alt: make +``` diff --git a/assets/favicon.png b/assets/favicon.png new file mode 100644 index 0000000..f1765ba Binary files /dev/null and b/assets/favicon.png differ diff --git a/cecil.phar b/cecil.phar new file mode 100644 index 0000000..5b21443 Binary files /dev/null and b/cecil.phar differ diff --git a/cecil.yml b/cecil.yml new file mode 100644 index 0000000..dff3f5f --- /dev/null +++ b/cecil.yml @@ -0,0 +1,63 @@ +title: 'Cypht Website' +baseline: 'cypht.org website' +baseurl: 'https://www.cypht.org/' +description: 'Cecil-powered static site generation for cypht.org' +author: + name: multiple + url: 'https://example.com/' +image: cecil-card.png +pages: + virtual: + - path: contribute-redirect + slug: contribute + redirect: /contribute/ + uglyurl: true + - path: developers-documentation-redirect + slug: developers-documentation + redirect: /developers-documentation/ + uglyurl: true + - path: documentation-redirect + slug: documentation + redirect: /documentation/ + uglyurl: true + - path: email-filters-redirect + slug: email-filters + redirect: /email-filters/ + uglyurl: true + - path: features-redirect + slug: features + redirect: /features/ + uglyurl: true + - path: how-to-join-redirect + slug: how-to-join + redirect: /how-to-join/ + uglyurl: true + - path: install-redirect + slug: install + redirect: /install/ + uglyurl: true + - path: install-1x-redirect + slug: install-1x + redirect: /install-1x/ + uglyurl: true + - path: install-2x-redirect + slug: install-2x + redirect: /install-2x/ + uglyurl: true + - path: license-redirect + slug: license + redirect: /license/ + uglyurl: true + - path: modules-redirect + slug: modules + redirect: /modules/ + uglyurl: true + - path: security-redirect + slug: security + redirect: /security/ + uglyurl: true + - path: tests-redirect + slug: tests + redirect: /tests/ + uglyurl: true + \ No newline at end of file diff --git a/contribute.html b/contribute.html deleted file mode 100644 index 6ac9dd5..0000000 --- a/contribute.html +++ /dev/null @@ -1,171 +0,0 @@ - - - - - - Contribute - - - - - - -
- -
- -
-
-

Want to contribute?

-

First of all, thank you for interest to cypht! The goal of this page is to provide everything you need to know in order to contribute to cypht-website and its different integrations.

- -

Development Workflow

-

The project, particularly version 1.4.x, has been designed with plain HTML and CSS, focusing on front-end and back-end development without the use of extra features or frameworks.

-

However, it's worth noting that in version 2.1.x, while there's no PHP back-end framework utilized for its back-end, Bootstrap is adopted as the front-end framework, enhancing the project's user interface and experience.

- -

Requirements

-
    -
  1. You're familiar with GitHub and the - Pull Request (PR) workflow. -
    2. -
  2. You've read the Cypht documentation and the README. -
    3. -
  3. You know about the Cypht community. Please use this as help and check how to join the community. -
    4. -
-

Git Guidelines

-
    -
  1. Make sure that the contribution you want to make is explained or detailed in a GitHub issue! Find an - existing issue or - open a new one. -
    2. -
  2. Once done, - fork the cypht website repository to your own GitHub account. - You can request a maintainer to check your issue before making a PR. -
    3. -
  3. Create a new Git branch.
    4. -
  4. Review the Development Workflow section that describes the project's technology used. -
    5. -
  5. Implement the changes on your branch.
    6. -
  6. - Submit the branch as a PR pointing to the master branch of cypht-website repository. - A maintainer will comment and/or review your Pull Request. Depending on the circumstances, this process may take some time.
    -
    7. -
- -

Have a question?

-

We love feedback so let us know what you think!
Leave a comment, submit your problem or contribute to - the project
by joining the community first. -

- - - - - - - - - - -
-
- - -
-
-
-
-

- Page on Github
- Edit here -

-
-
-

- Fill out an issue at Github
- Submit an issue -

-
-
-

- Chat with us at Gitter
- Cypht at Gitter -

-
-
-

- Want to contribute?
- Cypht website contribution -

-
-
-
-
- - - - - diff --git a/data/configFiles.json b/data/configFiles.json new file mode 100644 index 0000000..eafb98c --- /dev/null +++ b/data/configFiles.json @@ -0,0 +1,12 @@ +[ + "app.php", + "database.php", + "2fa.php", + "carddav.php", + "dynamic_login.php", + "github.php", + "ldap.php", + "oauth2.php", + "recaptcha.php", + "wordpress.php" +] \ No newline at end of file diff --git a/data/configOptions.json b/data/configOptions.json new file mode 100644 index 0000000..a02f332 --- /dev/null +++ b/data/configOptions.json @@ -0,0 +1,1377 @@ +{ + "app.php": [ + { + "key": "SESSION_TYPE", + "valueDefault": "PHP", + "comment": "------------\nSession Type\n------------\nSessions are how the server maintains your logged in state. Cypht supports\nstandard PHP sessions, as well as its own completely independent session\nsystem that uses memcached or a database for storage. In order to use\ndatabase sessions, the database must be correctly configured in the \"DB\nSupport\" section and the hm_user_session table must be created (see\nconfig\/database.php for more information). In order to use Memcached\nsessions, the memcached server must be correctly configured in the\n\"Memcached Support\" section. In order to use Redis session, the Redis\nserver must be configured in the \"Redis Support\" section.\nValid values for this setting:\nPHP Standard PHP session handlers\nDB Custom database based sessions\nMEM Custom Memcached based sessions\nREDIS Custom Redis based sessions\ncustom Create your own session class. See the modules\/site\/lib.php file for\n more info", + "commentHtml": "------------\nSession Type\n------------\nSessions are how the server maintains your logged in state. Cypht supports\nstandard PHP sessions, as well as its own completely independent session\nsystem that uses memcached or a database for storage. In order to use\ndatabase sessions, the database must be correctly configured in the \"DB\nSupport\" section and the hm_user_session table must be created (see\nconfig\/database.php for more information). In order to use Memcached\nsessions, the memcached server must be correctly configured in the\n\"Memcached Support\" section. In order to use Redis session, the Redis\nserver must be configured in the \"Redis Support\" section.\nValid values for this setting:\nPHP     Standard PHP session handlers\nDB      Custom database based sessions\nMEM     Custom Memcached based sessions\nREDIS   Custom Redis based sessions\ncustom  Create your own session class. See the modules\/site\/lib.php file for\n            more info", + "inputType": "select", + "setValues": [ + { + "value": "PHP", + "description": "Standard PHP session handlers" + }, + { + "value": "DB", + "description": "Custom database based sessions" + }, + { + "value": "MEM", + "description": "Custom Memcached based sessions" + }, + { + "value": "REDIS", + "description": "Custom Redis based sessions" + }, + { + "value": "custom", + "description": "Create your own session class. See the modules\/site\/lib.php file for more info" + } + ] + }, + { + "key": "AUTH_TYPE", + "valueDefault": "DB", + "comment": "-------------------\nAuthentication Type\n-------------------\nThis setting defines how Cypht will authenticate your username and password\nwhen you login. If you want to use a database it must be correctly configured\nin the \"DB Support\" section and the hm_user table must be created (see\nconfig\/database.php for more information). There are 3 PHP cli scripts to\nhelp manage database users in the scripts\/ directory (create_account.php,\ndelete_account.php, and update_password.php). If you want to authenticate\nagainst an IMAP server, you must setup the imap_auth_* settings below. If\nyou want to authenticate against an LDAP server, you must setup the ldap_auth_*\nsettings. Finally, if you want to let users pick from a list of popular mail\nservices or try to auto-discover a mail system, set this to dynamic and make\nsure the dynamic_login module set is enabled in the \"Module Sets\" section of\nthis file.\nValid values for this setting:\nDB Authenticate against the database\nLDAP Authenticate against an LDAP server\nIMAP Authenticate using an IMAP server\ndynamic Let the user choose from a list, or try to auto discover the mail\nservices based on the email domain\ncustom Create your own auth class. See the modules\/site\/lib.php file for\nmore info", + "commentHtml": "-------------------\nAuthentication Type\n-------------------\nThis setting defines how Cypht will authenticate your username and password\nwhen you login. If you want to use a database it must be correctly configured\nin the \"DB Support\" section and the hm_user table must be created (see\nconfig\/database.php for more information). There are 3 PHP cli scripts to\nhelp manage database users in the scripts\/ directory (create_account.php,\ndelete_account.php, and update_password.php). If you want to authenticate\nagainst an IMAP server, you must setup the imap_auth_* settings below. If\nyou want to authenticate against an LDAP server, you must setup the ldap_auth_*\nsettings. Finally, if you want to let users pick from a list of popular mail\nservices or try to auto-discover a mail system, set this to dynamic and make\nsure the dynamic_login module set is enabled in the \"Module Sets\" section of\nthis file.\nValid values for this setting:\nDB       Authenticate against the database\nLDAP     Authenticate against an LDAP server\nIMAP     Authenticate using an IMAP server\ndynamic  Let the user choose from a list, or try to auto discover the mail\nservices based on the email domain\ncustom   Create your own auth class. See the modules\/site\/lib.php file for\nmore info", + "inputType": "select", + "setValues": [ + { + "value": "DB", + "description": "Authenticate against the database" + }, + { + "value": "LDAP", + "description": "Authenticate against an LDAP server" + }, + { + "value": "IMAP", + "description": "Authenticate using an IMAP server" + }, + { + "value": "dynamic", + "description": "Let the user choose from a list, or try to auto discover the mail" + }, + { + "value": "services", + "description": "based on the email domain" + }, + { + "value": "custom", + "description": "Create your own auth class. See the modules\/site\/lib.php file for more info" + } + ] + }, + { + "key": "LDAP_AUTH_SERVER", + "valueDefault": "localhost", + "comment": "-------------------\nLDAP Authentication\n-------------------\nIf auth_type is set to LDAP, configure the LDAP server to authenticate against\nwith the following settings, otherwise these are ignored.\nThe hostname or IP address of the LDAP server to authenticate to", + "commentHtml": "-------------------\nLDAP Authentication\n-------------------\nIf auth_type is set to LDAP, configure the LDAP server to authenticate against\nwith the following settings, otherwise these are ignored.\nThe hostname or IP address of the LDAP server to authenticate to", + "inputType": "text", + "setValues": null + }, + { + "key": "LDAP_AUTH_PORT", + "valueDefault": "389", + "comment": "The port the LDAP server is listening on.", + "commentHtml": "The port the LDAP server is listening on.", + "inputType": "text", + "setValues": null + }, + { + "key": "LDAP_AUTH_TLS", + "valueDefault": null, + "comment": "Enable TLS\/SSL connections. Leave blank or set to false to disable. Set to\ntrue to enable TLS connections.", + "commentHtml": "Enable TLS\/SSL connections. Leave blank or set to false to disable. Set to\ntrue to enable TLS connections.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "LDAP_AUTH_BASE_DN", + "valueDefault": "example,dc=com", + "comment": "The \"base dn\" of the LDAP server", + "commentHtml": "The \"base dn\" of the LDAP server", + "inputType": "text", + "setValues": null + }, + { + "key": "IMAP_AUTH_NAME", + "valueDefault": "Gandi", + "comment": "-------------------\nIMAP Authentication\n-------------------\nIf auth_type is set to IMAP, configure the IMAP server to authenticate against\nwith the following settings, otherwise these are ignored.\nThis is just a label used in the UI. It can be set to anything", + "commentHtml": "-------------------\nIMAP Authentication\n-------------------\nIf auth_type is set to IMAP, configure the IMAP server to authenticate against\nwith the following settings, otherwise these are ignored.\nThis is just a label used in the UI. It can be set to anything", + "inputType": "text", + "setValues": null + }, + { + "key": "IMAP_AUTH_SERVER", + "valueDefault": "mail.gandi.net", + "comment": "The hostname or IP address of the IMAP server to authenticate to", + "commentHtml": "The hostname or IP address of the IMAP server to authenticate to", + "inputType": "text", + "setValues": null + }, + { + "key": "IMAP_AUTH_PORT", + "valueDefault": "993", + "comment": "The hostname or IP address of the IMAP server to authenticate to", + "commentHtml": "The hostname or IP address of the IMAP server to authenticate to", + "inputType": "text", + "setValues": null + }, + { + "key": "IMAP_AUTH_TLS", + "valueDefault": "true", + "comment": "Enable TLS\/SSL connections. Leave blank or set to false to disable. Set to\ntrue to enable TLS connections. If you want to use IMAP STARTTLS, do NOT\nenable this. This is only for TLS enabled sockets (typically on port 993).", + "commentHtml": "Enable TLS\/SSL connections. Leave blank or set to false to disable. Set to\ntrue to enable TLS connections. If you want to use IMAP STARTTLS, do NOT\nenable this. This is only for TLS enabled sockets (typically on port 993).", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "IMAP_AUTH_SIEVE_CONF_HOST", + "valueDefault": "", + "comment": "The hostname\/IP address and port sieve is listening on. Example: example.org:4190\nKeep this blank to disable sieve filter support on login", + "commentHtml": "The hostname\/IP address and port sieve is listening on. Example: example.org:4190\nKeep this blank to disable sieve filter support on login", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "IMAP_AUTH_SIEVE_TLS_MODE", + "valueDefault": "true", + "comment": "this will add the tls:\nto make this work make sure you set DEFAULT_SETTING_ENABLE_SIEVE_FILTER to true", + "commentHtml": "this will add the tls:\nto make this work make sure you set DEFAULT_SETTING_ENABLE_SIEVE_FILTER to true", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SMTP_NAME", + "valueDefault": null, + "comment": "-------------------\nDefault SMTP Server\n-------------------\nYou can set a default SMTP server for all Cypht users. Authentication will be\ndone with the users login credentials, so this only makes sense if you are\nusing IMAP for authentication. Leave these values blank to disable a\ndefault SMTP server, otherwise fill in the required values below\nThis is just a label used in the UI. It can be set to anything", + "commentHtml": "-------------------\nDefault SMTP Server\n-------------------\nYou can set a default SMTP server for all Cypht users. Authentication will be\ndone with the users login credentials, so this only makes sense if you are\nusing IMAP for authentication. Leave these values blank to disable a\ndefault SMTP server, otherwise fill in the required values below\nThis is just a label used in the UI. It can be set to anything", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SMTP_SERVER", + "valueDefault": null, + "comment": "The hostname or IP address of the SMTP server", + "commentHtml": "The hostname or IP address of the SMTP server", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SMTP_PORT", + "valueDefault": null, + "comment": "The port the SMTP server is listening on.", + "commentHtml": "The port the SMTP server is listening on.", + "inputType": "number", + "setValues": null + }, + { + "key": "DEFAULT_SMTP_TLS", + "valueDefault": null, + "comment": "Enable TLS\/SSL connections. Leave blank or set to false to disable. Set to\ntrue to enable TLS connections.", + "commentHtml": "Enable TLS\/SSL connections. Leave blank or set to false to disable. Set to\ntrue to enable TLS connections.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SMTP_NO_AUTH", + "valueDefault": null, + "comment": "If your SMTP service does not require authentication, you can disable it\nby setting the following to true.", + "commentHtml": "If your SMTP service does not require authentication, you can disable it\nby setting the following to true.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "USER_CONFIG_TYPE", + "valueDefault": "file", + "comment": "----------------\nSettings Storage\n----------------\nCypht supports 3 methods for saving user settings between logins. File based\nsettings, database table or custom implementation. To store settings in a\ndatabase, it must be configured in the \"DB Support\" section and the\nhm_user_settings table must be created (see config\/database.php for more\ninformation). To store settings on the filesystem, the user_settings_dir must\nbe created and the webserver software must be able to write to it. For custom\nimplementations, see Hm_User_Config_File.\nValid values for this setting:\nfile Store user settings in the filesystem\nDB Store user settings in a database\ncustom Store user settings via custom implementation. Specify class name\nafter colon, e.g. custom:Custom_User_Config", + "commentHtml": "----------------\nSettings Storage\n----------------\nCypht supports 3 methods for saving user settings between logins. File based\nsettings, database table or custom implementation. To store settings in a\ndatabase, it must be configured in the \"DB Support\" section and the\nhm_user_settings table must be created (see config\/database.php for more\ninformation). To store settings on the filesystem, the user_settings_dir must\nbe created and the webserver software must be able to write to it. For custom\nimplementations, see Hm_User_Config_File.\nValid values for this setting:\nfile    Store user settings in the filesystem\nDB      Store user settings in a database\ncustom  Store user settings via custom implementation. Specify class name\nafter colon, e.g. custom:Custom_User_Config", + "inputType": "select", + "setValues": [ + { + "value": "file", + "description": "Store user settings in the filesystem" + }, + { + "value": "DB", + "description": "Store user settings in a database" + }, + { + "value": "custom", + "description": "Store user settings via custom implementation. Specify class name after colon, e.g. custom:Custom_User_Config" + } + ] + }, + { + "key": "USER_SETTINGS_DIR", + "valueDefault": "\/var\/lib\/hm3\/users", + "comment": "-----------------\nSettings Location\n-----------------\nIf user_config_type is set to file, this must be set to an existing directory\nthat the webserver software can read and write to. If settings storage is set\nto DB, this is ignored. It should not be inside the webserver document root.", + "commentHtml": "-----------------\nSettings Location\n-----------------\nIf user_config_type is set to file, this must be set to an existing directory\nthat the webserver software can read and write to. If settings storage is set\nto DB, this is ignored. It should not be inside the webserver document root.", + "inputType": "text", + "setValues": null + }, + { + "key": "ATTACHMENT_DIR", + "valueDefault": "\/var\/lib\/hm3\/attachments", + "comment": "-------------------\nAttachment Location\n-------------------\nThis must be set to an existing directory that the webserver software\ncan read and write to. It should not be inside the webserver document root.", + "commentHtml": "-------------------\nAttachment Location\n-------------------\nThis must be set to an existing directory that the webserver software\ncan read and write to. It should not be inside the webserver document root.", + "inputType": "text", + "setValues": null + }, + { + "key": "DISABLE_ORIGIN_CHECK", + "valueDefault": "false", + "comment": "--------------------\nDisable origin check\n--------------------\nTo help protect against CSRF attacks, Cypht checks origin headers to confirm\nthat the source and target origin domains match. If you are using proxies this\ncould create a problem making it impossible to login. Change this to true to\ndisable the origin check.", + "commentHtml": "--------------------\nDisable origin check\n--------------------\nTo help protect against CSRF attacks, Cypht checks origin headers to confirm\nthat the source and target origin domains match. If you are using proxies this\ncould create a problem making it impossible to login. Change this to true to\ndisable the origin check.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "ADMIN_USERS", + "valueDefault": null, + "comment": "-----------\nAdmin Users\n-----------\nYou can define a comma delimited list of admin users that Cypht will grant\nspecial rights to. Currently this only enables the \"create account\" link in\nthe account module set that provides a form to create a new account. This is\nonly used if the auth_type is set to DB. Leave this blank if you don't want\nto define any admin users, or are using IMAP authentication.", + "commentHtml": "-----------\nAdmin Users\n-----------\nYou can define a comma delimited list of admin users that Cypht will grant\nspecial rights to. Currently this only enables the \"create account\" link in\nthe account module set that provides a form to create a new account. This is\nonly used if the auth_type is set to DB. Leave this blank if you don't want\nto define any admin users, or are using IMAP authentication.", + "inputType": "text", + "setValues": null + }, + { + "key": "COOKIE_DOMAIN", + "valueDefault": null, + "comment": "-------------\nCookie Domain\n-------------\nBy default Cypht uses the server name used in the request to determine\nthe domain name to set the cookie for. Configurations that use a reverse\nproxy might need to define the domain name used for cookies. Leave this\nblank to let Cypht automatically determine the domain. You can also use\nthe special value of \"none\" to force Cypht to NOT set the cookie domain\nproperty at all. This is not recommended unless you know what you are\ndoing!", + "commentHtml": "-------------\nCookie Domain\n-------------\nBy default Cypht uses the server name used in the request to determine\nthe domain name to set the cookie for. Configurations that use a reverse\nproxy might need to define the domain name used for cookies. Leave this\nblank to let Cypht automatically determine the domain. You can also use\nthe special value of \"none\" to force Cypht to NOT set the cookie domain\nproperty at all. This is not recommended unless you know what you are\ndoing!", + "inputType": "text", + "setValues": null + }, + { + "key": "COOKIE_PATH", + "valueDefault": null, + "comment": "-----------\nCookie Path\n-----------\nBy default Cypht uses the request URI to determine the cookie path to set\nthe cookie for. Configurations that use mod_rewrite might need to define\nthe path used for cookies. E.g. \/cypht\/embedded?page=compose will set path\nto \/cypht\/embedded\/ which won't send the cookies back to the server. In that\ncase set cookie_path=\/cypht\/. Leave this blank to let Cypht automatically\ndetermine the path. You can also use the special value of \"none\" to force\nCypht to NOT set the cookie path property at all. This is not recommended\nunless you know what you are doing!", + "commentHtml": "-----------\nCookie Path\n-----------\nBy default Cypht uses the request URI to determine the cookie path to set\nthe cookie for. Configurations that use mod_rewrite might need to define\nthe path used for cookies. E.g. \/cypht\/embedded?page=compose will set path\nto \/cypht\/embedded\/ which won't send the cookies back to the server. In that\ncase set cookie_path=\/cypht\/. Leave this blank to let Cypht automatically\ndetermine the path. You can also use the special value of \"none\" to force\nCypht to NOT set the cookie path property at all. This is not recommended\nunless you know what you are doing!", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_EMAIL_DOMAIN", + "valueDefault": null, + "comment": "---------------------\nOutbound Email Domain\n---------------------\nDefault domain used for outbound email addresses when using IMAP auth and\nusers don't login with a full email address. Users can customize this with\nthe profiles module which will override this default", + "commentHtml": "---------------------\nOutbound Email Domain\n---------------------\nDefault domain used for outbound email addresses when using IMAP auth and\nusers don't login with a full email address. Users can customize this with\nthe profiles module which will override this default", + "inputType": "text", + "setValues": null + }, + { + "key": "AUTO_CREATE_PROFILE", + "valueDefault": null, + "comment": "-------------------\nAuto-Create Profile\n-------------------\nWhen a user logs in and they have only 1 IMAP server and 1 SMTP server, and\nno configured profiles - enabling this option will auto-create a profile for\nthem. Email and reply-to addresses will use the default_email_domain if\nset, otherwise it will fallback to the domain Cypht is hosted on.", + "commentHtml": "-------------------\nAuto-Create Profile\n-------------------\nWhen a user logs in and they have only 1 IMAP server and 1 SMTP server, and\nno configured profiles - enabling this option will auto-create a profile for\nthem. Email and reply-to addresses will use the default_email_domain if\nset, otherwise it will fallback to the domain Cypht is hosted on.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "REDIRECT_AFTER_LOGIN", + "valueDefault": null, + "comment": "--------------------\nRedirect After Login\n--------------------\nYou can login directly to any page in Cypht by going to the correct url before\nlogging in, but that is not very user-friendly. To redirect users to a url\nafter login, add the url arguments below (everything in the url after, but\nincluding, the question mark). You must use double quotes around the value\notherwise it will cause an ini parsing error. To redirect users after login\nto the combined unread view you would use:\nredirect_after_login=\"?page=message_list&list_path=unread\"", + "commentHtml": "--------------------\nRedirect After Login\n--------------------\nYou can login directly to any page in Cypht by going to the correct url before\nlogging in, but that is not very user-friendly. To redirect users to a url\nafter login, add the url arguments below (everything in the url after, but\nincluding, the question mark). You must use double quotes around the value\notherwise it will cause an ini parsing error. To redirect users after login\nto the combined unread view you would use:\nredirect_after_login=\"?page=message_list&list_path=unread\"", + "inputType": "text", + "setValues": null + }, + { + "key": "APP_NAME", + "valueDefault": "Cypht", + "comment": "----------------\nApplication Name\n----------------\nThis label is used in the UI to reference the program - you can change it to\n\"Your awesome webmail\" to replace the Cypht name used in various places.", + "commentHtml": "----------------\nApplication Name\n----------------\nThis label is used in the UI to reference the program - you can change it to\n\"Your awesome webmail\" to replace the Cypht name used in various places.", + "inputType": "text", + "setValues": null + }, + { + "key": "ALWAYS_MOBILE_UI", + "valueDefault": null, + "comment": "---------------\nForce Mobile UI\n---------------\nCypht will detect mobile devices and display a mobile optimized UI. If you want\nto aways use this UI regardless of device, set this to true", + "commentHtml": "---------------\nForce Mobile UI\n---------------\nCypht will detect mobile devices and display a mobile optimized UI. If you want\nto aways use this UI regardless of device, set this to true", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_LANGUAGE", + "valueDefault": "en", + "comment": "----------------\nDefault Language\n----------------\nUsers can select from available interface languages on the site settings page.\nThis sets the default for a user who has not done so. Valid values are the\nlangauge codes that have matching language definitions in the language\/ folder.", + "commentHtml": "----------------\nDefault Language\n----------------\nUsers can select from available interface languages on the site settings page.\nThis sets the default for a user who has not done so. Valid values are the\nlangauge codes that have matching language definitions in the language\/ folder.", + "inputType": "text", + "setValues": null + }, + { + "key": "JS_COMPRESS", + "valueDefault": "false", + "comment": "----------------------\nJavaScript Compression\n----------------------\nWhen the configuration script is run, all JavaScript files are concatenated\nand optionally compressed. To compress the content, define a command and its\noptions below. Cypht does not come with compresson software, so you must\ninstall and configure that separately. Leave blank or set to false to disable\nexternal compression. Compression software must be able to handle ES6.\nExample:\njs_compress='uglifyjs.terser -c -m --verbose --warn'", + "commentHtml": "----------------------\nJavaScript Compression\n----------------------\nWhen the configuration script is run, all JavaScript files are concatenated\nand optionally compressed. To compress the content, define a command and its\noptions below. Cypht does not come with compresson software, so you must\ninstall and configure that separately. Leave blank or set to false to disable\nexternal compression. Compression software must be able to handle ES6.\nExample:\njs_compress='uglifyjs.terser -c -m --verbose --warn'", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "CSS_COMPRESS", + "valueDefault": "false", + "comment": "---------------\nCSS Compression\n---------------\nWhen the configuration script is run, all CSS files are concatenated and\noptionally compressed. To compress the content, define a command and its\noptions below. Cypht does not come with compresson software, so you must\ninstall and configure that separately. Leave blank or set to false to disable\nexternal compression.\nExample:\ncss_compress='java -jar \/usr\/local\/lib\/yuicompressor-2.4.8.jar --type css'", + "commentHtml": "---------------\nCSS Compression\n---------------\nWhen the configuration script is run, all CSS files are concatenated and\noptionally compressed. To compress the content, define a command and its\noptions below. Cypht does not come with compresson software, so you must\ninstall and configure that separately. Leave blank or set to false to disable\nexternal compression.\nExample:\ncss_compress='java -jar \/usr\/local\/lib\/yuicompressor-2.4.8.jar --type css'", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "ENABLE_REDIS", + "valueDefault": "true", + "comment": "----------------------\nCaching Server Support\n----------------------\nCypht can use Redis or Memcache to improve performance, as well as to store\nuser sessions. Configure Redis or Memcached below and Cypht will\nautomatically use them for caching. All data cached for a user in either\nsystem is encrypted. Currently, the feeds, and IMAP modules will use\nthe configured cache. If both Redis and Memcached are configured, Redis will\nbe used for the cache.\nIf you want to use the user session as a cache, uncomment the line below and\nset to true. THIS IS NOT RECOMMENDED. Cypht uses parallel requests to the\nserver, and using the session as a cache is likely to cause race conditions\nand integrity issues. If you are running Cypht in an \"embedded\" mode with\nonly one email source, this option is less likely to be a problem.\n'allow_session_cache' => env('ALLOW_SESSION_CACHE', false),\n'cache_class' => env('CACHE_CLASS')", + "commentHtml": "----------------------\nCaching Server Support\n----------------------\nCypht can use Redis or Memcache to improve performance, as well as to store\nuser sessions. Configure Redis or Memcached below and Cypht will\nautomatically use them for caching. All data cached for a user in either\nsystem is encrypted. Currently, the feeds, and IMAP modules will use\nthe configured cache. If both Redis and Memcached are configured, Redis will\nbe used for the cache.\nIf you want to use the user session as a cache, uncomment the line below and\nset to true. THIS IS NOT RECOMMENDED. Cypht uses parallel requests to the\nserver, and using the session as a cache is likely to cause race conditions\nand integrity issues. If you are running Cypht in an \"embedded\" mode with\nonly one email source, this option is less likely to be a problem.\n'allow_session_cache' => env('ALLOW_SESSION_CACHE', false),\n'cache_class' => env('CACHE_CLASS')", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "REDIS_SERVER", + "valueDefault": "127.0.0.1", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "REDIS_PORT", + "valueDefault": "6379", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "REDIS_INDEX", + "valueDefault": "1", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "REDIS_PASS", + "valueDefault": null, + "comment": "", + "commentHtml": null, + "inputType": "password", + "setValues": null + }, + { + "key": "REDIS_SOCKET", + "valueDefault": "\/var\/run\/redis\/redis-server.sock", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "ENABLE_MEMCACHED", + "valueDefault": "true", + "comment": "-----------------\nMemcached Support\n-----------------\nConfigure Memcached details below to use it for caching", + "commentHtml": "-----------------\nMemcached Support\n-----------------\nConfigure Memcached details below to use it for caching", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "MEMCACHED_SERVER", + "valueDefault": "127.0.0.1", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "MEMCACHED_PORT", + "valueDefault": "11211", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "MEMCACHED_AUTH", + "valueDefault": "false", + "comment": "If you need SASL authentication for memcached, set the following to true\nand add the username and password to authenticate with", + "commentHtml": "If you need SASL authentication for memcached, set the following to true\nand add the username and password to authenticate with", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "MEMCACHED_USER", + "valueDefault": null, + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "MEMCACHED_PASS", + "valueDefault": null, + "comment": "", + "commentHtml": null, + "inputType": "password", + "setValues": null + }, + { + "key": "ALLOW_LONG_SESSION", + "valueDefault": "false", + "comment": "-------------------\nAllow Long Sessions\n-------------------\nCypht logins only last as long as the browser is open. Closing the browser,\nor moving to a new network, will cause you to be logged out. This setting\nprovides users with a \"stay logged in\" option during login that will set the\nsesison lifetime to a default of 30 days, and disable the IP address check.\nUSE WITH CAUTION SINCE THIS DISABLES SOME SESSION PROTECTIONS.\nSpecifically:\n- Session cookies stay active after a browser restart making them more\nsusceptible to snooping\n- The browser \"fingerprint\" was use to help protect against session hijacking\nincludes the client's IP. With this option enabled a client IP can change\nmid-session and it won't log them out", + "commentHtml": "-------------------\nAllow Long Sessions\n-------------------\nCypht logins only last as long as the browser is open. Closing the browser,\nor moving to a new network, will cause you to be logged out. This setting\nprovides users with a \"stay logged in\" option during login that will set the\nsesison lifetime to a default of 30 days, and disable the IP address check.\nUSE WITH CAUTION SINCE THIS DISABLES SOME SESSION PROTECTIONS.\nSpecifically:\n- Session cookies stay active after a browser restart making them more\nsusceptible to snooping\n- The browser \"fingerprint\" was use to help protect against session hijacking\nincludes the client's IP. With this option enabled a client IP can change\nmid-session and it won't log them out", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "LONG_SESSION_LIFETIME", + "valueDefault": "30", + "comment": "Set the session lifetime in days. Only applies if allow_long_session is set to\ntrue, and a user checks the box to \"stay logged in\" during login.", + "commentHtml": "Set the session lifetime in days. Only applies if allow_long_session is set to\ntrue, and a user checks the box to \"stay logged in\" during login.", + "inputType": "text", + "setValues": null + }, + { + "key": "ENCRYPT_AJAX_REQUESTS", + "valueDefault": null, + "comment": "--------------------------\nBrowser Encryption Options\n--------------------------\nCypht can use the Forge JavaScript encryption library to encrypt AJAX\nresponses and data stored in browser local storage. Enabling either one of\nthese options causes the Forge JavaScript library to be included. This adds\nabout 70KB to the page size (when gzipped).\nUse AES encryption for AJAX responses. Set to true to enable, leave blank or\nset to false to disable.", + "commentHtml": "--------------------------\nBrowser Encryption Options\n--------------------------\nCypht can use the Forge JavaScript encryption library to encrypt AJAX\nresponses and data stored in browser local storage. Enabling either one of\nthese options causes the Forge JavaScript library to be included. This adds\nabout 70KB to the page size (when gzipped).\nUse AES encryption for AJAX responses. Set to true to enable, leave blank or\nset to false to disable.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "ENCRYPT_LOCAL_STORAGE", + "valueDefault": null, + "comment": "Use AES encryption for data stored in the browser local storage. Set to true\nto enable, or leave blank or set to false to disable.", + "commentHtml": "Use AES encryption for data stored in the browser local storage. Set to true\nto enable, or leave blank or set to false to disable.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DISABLE_IP_CHECK", + "valueDefault": "false", + "comment": "-----------------------\nAllow client IP changes\n-----------------------\nBy default Cypht will log you out if your client IP address changes. This is\nan extra layer of protection against session hijacking, but it's not uncommon\nfor your client IP to change. Change this to true if you want to disable this\ncheck", + "commentHtml": "-----------------------\nAllow client IP changes\n-----------------------\nBy default Cypht will log you out if your client IP address changes. This is\nan extra layer of protection against session hijacking, but it's not uncommon\nfor your client IP to change. Change this to true if you want to disable this\ncheck", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "ALLOW_EXTERNAL_IMAGE_SOURCES", + "valueDefault": "true", + "comment": "--------------------------\nAllow remote image sources\n--------------------------\nWARNING: Using this feature could leak information to external sources.\nBy default, Cypht will not allow external images to be loaded when viewing an\nHTML formatted email message. A Content Security Policy header limits images\nsources to \"self\" only and the message content is filtered to remove any external\nresource. If you really want the ability to view external images in an email,\nyou first need to change the following setting to true. When viewing an HTML\nformatted message, you will now have a link before the message body called \"Allow\nImages\" that will reload the message part with external images visible.", + "commentHtml": "--------------------------\nAllow remote image sources\n--------------------------\nWARNING: Using this feature could leak information to external sources.\nBy default, Cypht will not allow external images to be loaded when viewing an\nHTML formatted email message. A Content Security Policy header limits images\nsources to \"self\" only and the message content is filtered to remove any external\nresource. If you really want the ability to view external images in an email,\nyou first need to change the following setting to true. When viewing an HTML\nformatted message, you will now have a link before the message body called \"Allow\nImages\" that will reload the message part with external images visible.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "SINGLE_SERVER_MODE", + "valueDefault": "false", + "comment": "------------------\nSingle server mode\n------------------\nThis setting restricts Cypht to only using a single email source (\nIMAP) and the default SMTP server defined in this file. It modifies the UI to\nremove the ability to add other email sources, and removes the password\nrestriction when saving data between logins. You must use either IMAP\nauthentication for this setting to be enforced, and auth server will be the\nsingle email source users have access to. If you enable this after users\nhave saved any settings, they will be lost (or if you disable it after they\nhave saved any settings). WARNING: USER SETTINGS SAVED TO THE SERVER WILL NOT\nBE ENCRYPTED WITH THIS ENABLED", + "commentHtml": "------------------\nSingle server mode\n------------------\nThis setting restricts Cypht to only using a single email source (\nIMAP) and the default SMTP server defined in this file. It modifies the UI to\nremove the ability to add other email sources, and removes the password\nrestriction when saving data between logins. You must use either IMAP\nauthentication for this setting to be enforced, and auth server will be the\nsingle email source users have access to. If you enable this after users\nhave saved any settings, they will be lost (or if you disable it after they\nhave saved any settings). WARNING: USER SETTINGS SAVED TO THE SERVER WILL NOT\nBE ENCRYPTED WITH THIS ENABLED", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DISABLE_EMPTY_SUPERGLOBALS", + "valueDefault": "false", + "comment": "-------------------\nIntegration options\n-------------------\nCypht does a few things to make it more secure by default, but these features\ncan make it difficult to integrate Cypht into 3rd party software. Specifically,\nCypht disables PHP \"super globals\", and sets a restrictive PHP \"open basedir\"\nsetting, tweaks PHP ini settings to increase security, and uses a browser\n\"fingerprint\" to improve session security. You can disable each with the\nfollowing options:\nDon't empty PHP super globals", + "commentHtml": "-------------------\nIntegration options\n-------------------\nCypht does a few things to make it more secure by default, but these features\ncan make it difficult to integrate Cypht into 3rd party software. Specifically,\nCypht disables PHP \"super globals\", and sets a restrictive PHP \"open basedir\"\nsetting, tweaks PHP ini settings to increase security, and uses a browser\n\"fingerprint\" to improve session security. You can disable each with the\nfollowing options:\nDon't empty PHP super globals", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DISABLE_OPEN_BASE_DIR", + "valueDefault": "false", + "comment": "Don't apply open basedir restrictions", + "commentHtml": "Don't apply open basedir restrictions", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DISABLE_INI_SETTINGS", + "valueDefault": "false", + "comment": "Don't tweak ini settings", + "commentHtml": "Don't tweak ini settings", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DISABLE_FINGERPRINT", + "valueDefault": "false", + "comment": "Don't use a browser fingerprint", + "commentHtml": "Don't use a browser fingerprint", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "AUTH_CLASS", + "valueDefault": null, + "comment": "You can create your own custom authentication and session classes using the\nsite module set, however you might want those classes located somewhere else\noutside of the Cypht code base. By setting session_type and auth_type to custom,\nyou can control what class is used with the following settings", + "commentHtml": "You can create your own custom authentication and session classes using the\nsite module set, however you might want those classes located somewhere else\noutside of the Cypht code base. By setting session_type and auth_type to custom,\nyou can control what class is used with the following settings", + "inputType": "text", + "setValues": null + }, + { + "key": "SESSION_CLASS", + "valueDefault": null, + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "CYPHT_MODULES", + "valueDefault": "core,contacts,local_contacts,feeds,imap,smtp,account,idle_timer,calendar,themes,nux,developer,history,saved_searches,advanced_search,highlights,profiles,inline_message,imap_folders,keyboard_shortcuts,tags", + "comment": "-----------------------------------------------------------------------------\nModules\n-----------------------------------------------------------------------------\n-----------\nModule Sets\n-----------\nCypht uses module sets to separate functionality in the program. Module sets\ncan be enabled and disabled independently by commenting out or uncommenting\nthe assignments below. Add a new assignment to enable your own module sets.\n----\nCore\n----\nHandles page layout, login\/logout, and the default settings pages. This set\nis required.", + "commentHtml": "-----------------------------------------------------------------------------\nModules\n-----------------------------------------------------------------------------\n-----------\nModule Sets\n-----------\nCypht uses module sets to separate functionality in the program. Module sets\ncan be enabled and disabled independently by commenting out or uncommenting\nthe assignments below. Add a new assignment to enable your own module sets.\n----\nCore\n----\nHandles page layout, login\/logout, and the default settings pages. This set\nis required.", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_NO_PASSWORD_SAVE", + "valueDefault": "false", + "comment": "----------\nAPI login\n----------", + "commentHtml": "----------\nAPI login\n----------", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_IMAP_PER_PAGE", + "valueDefault": "20", + "comment": "Number of messages per page when viewing IMAP folders\nDefaults to 20", + "commentHtml": "Number of messages per page when viewing IMAP folders\nDefaults to 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_SIMPLE_MSG_PARTS", + "valueDefault": "false", + "comment": "Amount of IMAP message structure detail on the message view page\nDefaults to full structure", + "commentHtml": "Amount of IMAP message structure detail on the message view page\nDefaults to full structure", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_PAGINATE_LINKS", + "valueDefault": "true", + "comment": "Next and Previous emails on the message view page\nDefaults to full structure", + "commentHtml": "Next and Previous emails on the message view page\nDefaults to full structure", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_MSG_PART_ICONS", + "valueDefault": "true", + "comment": "Show icons for each IMAP message part type\nDefaults to true", + "commentHtml": "Show icons for each IMAP message part type\nDefaults to true", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_REVIEW_SENT_EMAIL", + "valueDefault": "true", + "comment": "Show the message after sending\nDefaults to true", + "commentHtml": "Show the message after sending\nDefaults to true", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_TEXT_ONLY", + "valueDefault": "false", + "comment": "Prefer text parts when viewing a message\nDefaults to false", + "commentHtml": "Prefer text parts when viewing a message\nDefaults to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_SENT_PER_SOURCE", + "valueDefault": "20", + "comment": "Per source max for the combined sent view\nDefaults to 20", + "commentHtml": "Per source max for the combined sent view\nDefaults to 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_SENT_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for the combined sent view\nDefaults to 1 week", + "commentHtml": "Per source time limit for the combined sent view\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_JUNK_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for junk page\nDefaults to 1 week", + "commentHtml": "Per source time limit for junk page\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_JUNK_PER_SOURCE", + "valueDefault": "20", + "comment": "Per source number limit for junk page\nDefaults 20", + "commentHtml": "Per source number limit for junk page\nDefaults 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_TAGS_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for tags page\nDefaults to 1 week", + "commentHtml": "Per source time limit for tags page\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_TAGS_PER_SOURCE", + "valueDefault": "20", + "comment": "Per source number limit for tags page\nDefaults 20", + "commentHtml": "Per source number limit for tags page\nDefaults 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_TRASH_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for trash page\nDefaults to 1 week", + "commentHtml": "Per source time limit for trash page\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_TRASH_PER_SOURCE", + "valueDefault": "20", + "comment": "Per source number limit for trash page\nDefaults 20", + "commentHtml": "Per source number limit for trash page\nDefaults 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_DRAFT_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for draft page\nDefaults to 1 week", + "commentHtml": "Per source time limit for draft page\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_DRAFT_PER_SOURCE", + "valueDefault": "20", + "comment": "Per source number limit for draft page\nDefaults 20", + "commentHtml": "Per source number limit for draft page\nDefaults 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_SHOW_LIST_ICONS", + "valueDefault": "true", + "comment": "Display source icons in message lists\nDefaults to true", + "commentHtml": "Display source icons in message lists\nDefaults to true", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_START_PAGE", + "valueDefault": "none", + "comment": "Redirect to this page on login\nDefaults to none", + "commentHtml": "Redirect to this page on login\nDefaults to none", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_DISABLE_DELETE_PROMPT", + "valueDefault": "false", + "comment": "Don't prompt when deleting something\nDefaults to false", + "commentHtml": "Don't prompt when deleting something\nDefaults to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_NO_FOLDER_ICONS", + "valueDefault": "false", + "comment": "Hide icons in the folder list\nDefaults to false", + "commentHtml": "Hide icons in the folder list\nDefaults to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_ALL_EMAIL_PER_SOURCE", + "valueDefault": "20", + "comment": "Source max for the all email combined view\nDefaults to 20", + "commentHtml": "Source max for the all email combined view\nDefaults to 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_ALL_EMAIL_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for the all email combined view\nDefaults to 1 week", + "commentHtml": "Per source time limit for the all email combined view\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_ALL_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for the everything combined view\nDefaults to 1 week", + "commentHtml": "Per source time limit for the everything combined view\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_ALL_PER_SOURCE", + "valueDefault": "20", + "comment": "Per source max for the everything combined view\nDefaults to 20", + "commentHtml": "Per source max for the everything combined view\nDefaults to 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_UNREAD_PER_SOURCE", + "valueDefault": "20", + "comment": "Per source max for the unread combined view\nDefaults to 20", + "commentHtml": "Per source max for the unread combined view\nDefaults to 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_FLAGGED_PER_SOURCE", + "valueDefault": "20", + "comment": "Per source max for the flagged combined view\nDefaults to 20", + "commentHtml": "Per source max for the flagged combined view\nDefaults to 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_FLAGGED_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for the flagged combined view\nDefaults to 1 week", + "commentHtml": "Per source time limit for the flagged combined view\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_UNREAD_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for the unread combined view\nDefaults to 1 week", + "commentHtml": "Per source time limit for the unread combined view\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_SEARCH_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for IMAP SEARCH to find matching messages\nDefaults to 1 week", + "commentHtml": "Per source time limit for IMAP SEARCH to find matching messages\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_TIMEZONE", + "valueDefault": "UTC", + "comment": "Timezone for date displays\nDefaults to UTC", + "commentHtml": "Timezone for date displays\nDefaults to UTC", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_LIST_STYLE", + "valueDefault": "email_style", + "comment": "Message list format style\nDefaults to email client style", + "commentHtml": "Message list format style\nDefaults to email client style", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_LANGUAGE", + "valueDefault": "en", + "comment": "Interface language\nDefaults to en (English)", + "commentHtml": "Interface language\nDefaults to en (English)", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_UNREAD_EXCLUDE_FEEDS", + "valueDefault": "false", + "comment": "Hide new news feed items from the unread combined view\nDefaults to false", + "commentHtml": "Hide new news feed items from the unread combined view\nDefaults to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_FEED_LIMIT", + "valueDefault": "20", + "comment": "Per source max for news feeds\nDefaults to 20", + "commentHtml": "Per source max for news feeds\nDefaults to 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_FEED_SINCE", + "valueDefault": "-1 week", + "comment": "Per source time limit for news feeds\nDefaults to 1 week", + "commentHtml": "Per source time limit for news feeds\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_SMTP_COMPOSE_TYPE", + "valueDefault": "0", + "comment": "Toggle between plain text or HTML formatted mail on the compose page\nDefaults to 0 (plain text)", + "commentHtml": "Toggle between plain text or HTML formatted mail on the compose page\nDefaults to 0 (plain text)", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_SMTP_AUTO_BCC", + "valueDefault": "false", + "comment": "BCC a copy of outbound mail to the sender\nDefaults to false", + "commentHtml": "BCC a copy of outbound mail to the sender\nDefaults to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_THEME", + "valueDefault": "default", + "comment": "UI theme\nDefaults to the default white one (\"White Bread\")", + "commentHtml": "UI theme\nDefaults to the default white one (\"White Bread\")", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_UNREAD_EXCLUDE_WORDPRESS", + "valueDefault": "false", + "comment": "Hide WordPress notifications from the unread combined view\nDefaults to false", + "commentHtml": "Hide WordPress notifications from the unread combined view\nDefaults to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_WORDPRESS_SINCE", + "valueDefault": "-1 week", + "comment": "Time limit for WordPress notifications\nDefaults to 1 week", + "commentHtml": "Time limit for WordPress notifications\nDefaults to 1 week", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_UNREAD_EXCLUDE_GITHUB", + "valueDefault": "false", + "comment": "Hide Github notifications from the unread combined view\nDefaults to false", + "commentHtml": "Hide Github notifications from the unread combined view\nDefaults to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_GITHUB_LIMIT", + "valueDefault": "20", + "comment": "Max per source for Github notifications\nDefaults to 20", + "commentHtml": "Max per source for Github notifications\nDefaults to 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_GITHUB_SINCE", + "valueDefault": "-1 week", + "comment": "Max per source for Github notifications\nDefaults to 20", + "commentHtml": "Max per source for Github notifications\nDefaults to 20", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_INLINE_MESSAGE", + "valueDefault": "false", + "comment": "Display message details inline from the message list\nDefaults to false", + "commentHtml": "Display message details inline from the message list\nDefaults to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_INLINE_MESSAGE", + "valueDefault": "right", + "comment": "Display message style inline from the message list\nDefaults to right", + "commentHtml": "Display message style inline from the message list\nDefaults to right", + "inputType": "text", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_ENABLE_KEYBOARD_SHORTCUTS", + "valueDefault": "false", + "comment": "Enable keyboard shortcuts\nDefaults to false", + "commentHtml": "Enable keyboard shortcuts\nDefaults to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DEFAULT_SETTING_ENABLE_SIEVE_FILTER", + "valueDefault": "false", + "comment": "Enable sieve filter\nDefaults to false", + "commentHtml": "Enable sieve filter\nDefaults to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "FANCY_LOGIN", + "valueDefault": "false", + "comment": "Fancy Login page\nUse this setting switch between the legacy login page and the fancy one", + "commentHtml": "Fancy Login page\nUse this setting switch between the legacy login page and the fancy one", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "JS_EXCLUDE_DEPS", + "valueDefault": "", + "comment": "", + "commentHtml": null, + "inputType": "checkbox", + "setValues": null + } + ], + "database.php": [ + { + "key": "DB_CONNECTION_TYPE", + "valueDefault": "host", + "comment": "-----------------------------------------------------------------------------\nDB Support\n-----------------------------------------------------------------------------\n----------------\nDatabase Support\n----------------\nCypht can use a database for 3 different purposes: authentication, sessions,\nand user settings. Each requires the following settings to be configured and\nthe correct table to be created. CREATE TABLE SQL statements for MySQL and\nPostgresql are below.\nConnection type. Can be \"host\" to connect to a hostname, or \"socket\" to\nconnect to a unix socket.", + "commentHtml": "-----------------------------------------------------------------------------\nDB Support\n-----------------------------------------------------------------------------\n----------------\nDatabase Support\n----------------\nCypht can use a database for 3 different purposes: authentication, sessions,\nand user settings. Each requires the following settings to be configured and\nthe correct table to be created. CREATE TABLE SQL statements for MySQL and\nPostgresql are below.\nConnection type. Can be \"host\" to connect to a hostname, or \"socket\" to\nconnect to a unix socket.", + "inputType": "text", + "setValues": null + }, + { + "key": "DB_HOST", + "valueDefault": "127.0.0.1", + "comment": "Database host name or ip address. If db_connection_type is set to \"socket\",\nthis value is ignored", + "commentHtml": "Database host name or ip address. If db_connection_type is set to \"socket\",\nthis value is ignored", + "inputType": "text", + "setValues": null + }, + { + "key": "DB_PORT", + "valueDefault": "3306", + "comment": "Database port. Only needed if your database is running on a non-standard\nport", + "commentHtml": "Database port. Only needed if your database is running on a non-standard\nport", + "inputType": "text", + "setValues": null + }, + { + "key": "DB_SOCKET", + "valueDefault": "\/var\/lib\/mysqld\/mysqld.sock", + "comment": "If db_connection_type is set to \"socket\", this should be the filesystem\nlocation of the unix socket file. If db_connection_type is set to \"host\"\nthis value is ignored.", + "commentHtml": "If db_connection_type is set to \"socket\", this should be the filesystem\nlocation of the unix socket file. If db_connection_type is set to \"host\"\nthis value is ignored.", + "inputType": "text", + "setValues": null + }, + { + "key": "DB_NAME", + "valueDefault": "cypht_db", + "comment": "Name of the database with the required tables", + "commentHtml": "Name of the database with the required tables", + "inputType": "text", + "setValues": null + }, + { + "key": "DB_USER", + "valueDefault": "root", + "comment": "User to connect to the database with", + "commentHtml": "User to connect to the database with", + "inputType": "text", + "setValues": null + }, + { + "key": "DB_PASS", + "valueDefault": null, + "comment": "Password to connect to the database with", + "commentHtml": "Password to connect to the database with", + "inputType": "password", + "setValues": null + }, + { + "key": "DB_DRIVER", + "valueDefault": "mysql", + "comment": "Database type. can be any supported PDO driver ; (http:\/\/php.net\/manual\/en\/pdo.drivers.php)", + "commentHtml": "Database type. can be any supported PDO driver ; (http:\/\/php.net\/manual\/en\/pdo.drivers.php)", + "inputType": "text", + "setValues": null + } + ], + "2fa.php": [ + { + "key": "APP_2FA_SECRET", + "valueDefault": "", + "comment": "--------------------------------------------------------------------\nConstants used for 2 factor authentication with Google Authenticator\n--------------------------------------------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !\nEnter the raw secret value (minimum 10 characters) to be used with the Google\nAuthenticator Application (or any TOTP app providing 6 digit pins). Users\nmust opt-in for 2fa on the site settings page which provides a QR barcode\nto configure Google Authenticator.\nIn order for 2fa to work, your server MUST have an accurate date and time,\notherwise the codes won't match up. NTP is the standard way to keep a server's\ntime synced: http:\/\/www.ntp.org\/", + "commentHtml": "--------------------------------------------------------------------\nConstants used for 2 factor authentication with Google Authenticator\n--------------------------------------------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !\nEnter the raw secret value (minimum 10 characters) to be used with the Google\nAuthenticator Application (or any TOTP app providing 6 digit pins). Users\nmust opt-in for 2fa on the site settings page which provides a QR barcode\nto configure Google Authenticator.\nIn order for 2fa to work, your server MUST have an accurate date and time,\notherwise the codes won't match up. NTP is the standard way to keep a server's\ntime synced: http:\/\/www.ntp.org\/", + "inputType": "password", + "setValues": null + }, + { + "key": "APP_2FA_SIMPLE", + "valueDefault": "false", + "comment": "By default the generated secret will be 64 characters before being base32\nencoded. To use a shorter secret that is easier to manually enter, set the\nfollowing to true. Note that if you change this setting after users have\nenabled 2fa, they will have to use a backup code to login, then reset there\naccount in the authenticator app.", + "commentHtml": "By default the generated secret will be 64 characters before being base32\nencoded. To use a shorter secret that is easier to manually enter, set the\nfollowing to true. Note that if you change this setting after users have\nenabled 2fa, they will have to use a backup code to login, then reset there\naccount in the authenticator app.", + "inputType": "checkbox", + "setValues": null + } + ], + "carddav.php": [ + { + "key": "CARD_DAV_SERVER", + "valueDefault": "http:\/\/localhost:5232", + "comment": "----------------------------------------\nConstants used for CardDav communication\n----------------------------------------", + "commentHtml": "----------------------------------------\nConstants used for CardDav communication\n----------------------------------------", + "inputType": "text", + "setValues": null + } + ], + "dynamic_login.php": [ + { + "key": "DYNAMIC_HOST", + "valueDefault": "true", + "comment": "----------------------------------------------\nConstants used for dynamic login configuration\n----------------------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !\nThe dynamic login module set tries to autodetect mail server configurations,\nbut you can configure it to act specifically with the following settings.\nSet this to true to use the hostname in the URL used to access Cypht to\ndetermine the domain for mail services (IMAP\/SMTP). If this is set to\ntrue, the mail service selection dropdown is not displayed on the login page.", + "commentHtml": "----------------------------------------------\nConstants used for dynamic login configuration\n----------------------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !\nThe dynamic login module set tries to autodetect mail server configurations,\nbut you can configure it to act specifically with the following settings.\nSet this to true to use the hostname in the URL used to access Cypht to\ndetermine the domain for mail services (IMAP\/SMTP). If this is set to\ntrue, the mail service selection dropdown is not displayed on the login page.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DYNAMIC_HOST_SUBDOMAIN", + "valueDefault": "", + "comment": "If dynamic_host is true, you can strip the subdomain on the url with this\nsetting. Leave empty for no subdomain. For example, if a user accesses Cypht\nat webmail.example.com, set this to \"webmail\" to use just example.com for the\nIMAP\/SMTP services.", + "commentHtml": "If dynamic_host is true, you can strip the subdomain on the url with this\nsetting. Leave empty for no subdomain. For example, if a user accesses Cypht\nat webmail.example.com, set this to \"webmail\" to use just example.com for the\nIMAP\/SMTP services.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DYNAMIC_USER", + "valueDefault": "false", + "comment": "Set this to true to use the domain portion of an E-mail address used as a\nusername during login for mail services. Even if this is set to false, it\nwill still by attempted if dynamic_host is disabled and \"other\" is selected\nfrom the mail service dropdown. If set to true, the mail service selection\ndropdown is not displayed on the login page.", + "commentHtml": "Set this to true to use the domain portion of an E-mail address used as a\nusername during login for mail services. Even if this is set to false, it\nwill still by attempted if dynamic_host is disabled and \"other\" is selected\nfrom the mail service dropdown. If set to true, the mail service selection\ndropdown is not displayed on the login page.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DYNAMIC_SMTP_SUBDOMAIN", + "valueDefault": "", + "comment": "Subdomain to prepend to the mail service domain for SMTP. If the mail service\ndomain is example.com, but the SMTP server is at smtp.example.com, you would\nset this to \"smtp\". Leave blank for no subdomain.", + "commentHtml": "Subdomain to prepend to the mail service domain for SMTP. If the mail service\ndomain is example.com, but the SMTP server is at smtp.example.com, you would\nset this to \"smtp\". Leave blank for no subdomain.", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "DYNAMIC_MAIL_SUBDOMAIN", + "valueDefault": "", + "comment": "Subdomain to prepend to the mail service domain for IMAP. If the mail\nservice is example.com, but the IMAP service is at \"mail\", you would\nset this to \"mail\". Leave blank for no subdomain.", + "commentHtml": "Subdomain to prepend to the mail service domain for IMAP. If the mail\nservice is example.com, but the IMAP service is at \"mail\", you would\nset this to \"mail\". Leave blank for no subdomain.", + "inputType": "checkbox", + "setValues": null + } + ], + "github.php": [ + { + "key": "GITHUB_CLIENT_ID", + "valueDefault": "", + "comment": "[github.com]\n-------------------------------------------------------\nConstants used for oauth2 communication with github.com\n-------------------------------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !", + "commentHtml": "[github.com]\n-------------------------------------------------------\nConstants used for oauth2 communication with github.com\n-------------------------------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "GITHUB_CLIENT_SECRET", + "valueDefault": "", + "comment": "", + "commentHtml": null, + "inputType": "password", + "setValues": null + }, + { + "key": "GITHUB_REDIRECT_URI", + "valueDefault": "http:\/\/localhost\/?page=home", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "GITHUB_AUTH_URL", + "valueDefault": "https:\/\/github.com\/login\/oauth\/authorize", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "GITHUB_TOKEN_URL", + "valueDefault": "https:\/\/github.com\/login\/oauth\/access_token", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + } + ], + "ldap.php": [ + { + "key": "LDAP_SERVER", + "valueDefault": "localhost", + "comment": "-------------------------------------\nConstants used for LDAP communication\n-------------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !\nCreate one section for each LDAP backend you want to support. The section name\nwill be used in the UI for the name of this addressbook", + "commentHtml": "-------------------------------------\nConstants used for LDAP communication\n-------------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !\nCreate one section for each LDAP backend you want to support. The section name\nwill be used in the UI for the name of this addressbook", + "inputType": "text", + "setValues": null + }, + { + "key": "LDAP_ENABLE_TLS", + "valueDefault": "true", + "comment": "| Flag to enable or disable TLS connections", + "commentHtml": "| Flag to enable or disable TLS connections", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "LDAP_PORT", + "valueDefault": "389", + "comment": "| Port to connect to", + "commentHtml": "| Port to connect to", + "inputType": "text", + "setValues": null + }, + { + "key": "LDAP_BASE_DN", + "valueDefault": "dc=example,dc=com", + "comment": "| Base DN", + "commentHtml": "| Base DN", + "inputType": "text", + "setValues": null + }, + { + "key": "LDAP_SEARCH_TERM", + "valueDefault": "objectclass=inetOrgPerson", + "comment": "| Base DN", + "commentHtml": "| Base DN", + "inputType": "text", + "setValues": null + }, + { + "key": "LDAP_AUTH", + "valueDefault": "false", + "comment": "| Flag to enable user binding. Anonymous binding is used when set to false", + "commentHtml": "| Flag to enable user binding. Anonymous binding is used when set to false", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "LDAP_USER", + "valueDefault": "", + "comment": "| Global username and password to bind with if auth is set to true. If left\n | blank, users will have a setting on the Settings -> Site page for this\n | connection to enter their own", + "commentHtml": "| Global username and password to bind with if auth is set to true. If left\n            | blank, users will have a setting on the Settings -> Site page for this\n            | connection to enter their own", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "LDAP_PASS", + "valueDefault": "", + "comment": "", + "commentHtml": null, + "inputType": "checkbox", + "setValues": null + }, + { + "key": "LDAP_OBJECT_CLASS", + "valueDefault": "top,person,organizationalperson,inetorgperson", + "comment": "| Object classes for the addressbook entries", + "commentHtml": "| Object classes for the addressbook entries", + "inputType": "text", + "setValues": null + }, + { + "key": "LDAP_READ_WRITE", + "valueDefault": "true", + "comment": "| Flag to allow editing of the addressbook contents", + "commentHtml": "| Flag to allow editing of the addressbook contents", + "inputType": "checkbox", + "setValues": null + } + ], + "oauth2.php": [ + { + "key": "GMAIL_CLIENT_ID", + "valueDefault": "", + "comment": "-------------------------------------------------\nConstants used for oauth2 authentication over IMAP\n-------------------------------------------------\nCurrently there are only two popular E-mail providers supporting IMAP\/oauth2,\nOutlook and Gmail. In order to use oauth2 you must create a web application\nthat generates a client id, client secret and a redirect URI, then define them\nin this file.\nAn OAuth2 app can connect multiple accounts by using the user's authorization\nto request unique access tokens for each account during the OAuth2 flow.\nEach token corresponds to a specific user's permissions and account data.\nOutlook.com https:\/\/account.live.com\/developers\/applications\/\nGmail: https:\/\/console.developers.google.com\/project", + "commentHtml": "-------------------------------------------------\nConstants used for oauth2 authentication over IMAP\n-------------------------------------------------\nCurrently there are only two popular E-mail providers supporting IMAP\/oauth2,\nOutlook and Gmail. In order to use oauth2 you must create a web application\nthat generates a client id, client secret and a redirect URI, then define them\nin this file.\nAn OAuth2 app can connect multiple accounts by using the user's authorization\nto request unique access tokens for each account during the OAuth2 flow.\nEach token corresponds to a specific user's permissions and account data.\nOutlook.com https:\/\/account.live.com\/developers\/applications\/\nGmail: https:\/\/console.developers.google.com\/project", + "inputType": "checkbox", + "setValues": null + }, + { + "key": "GMAIL_CLIENT_SECRET", + "valueDefault": "", + "comment": "", + "commentHtml": null, + "inputType": "password", + "setValues": null + }, + { + "key": "GMAIL_CLIENT_URI", + "valueDefault": "http:\/\/localhost\/?page=home", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "GMAIL_AUTH_URI", + "valueDefault": "https:\/\/accounts.google.com\/o\/oauth2\/auth", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "GMAIL_TOKEN_URI", + "valueDefault": "https:\/\/www.googleapis.com\/oauth2\/v3\/token", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "GMAIL_REFRESH_URI", + "valueDefault": "https:\/\/www.googleapis.com\/oauth2\/v3\/token", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "OUTLOOK_CLIENT_ID", + "valueDefault": "", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "OUTLOOK_CLIENT_SECRET", + "valueDefault": "", + "comment": "", + "commentHtml": null, + "inputType": "password", + "setValues": null + }, + { + "key": "OUTLOOK_CLIENT_URI", + "valueDefault": "http:\/\/localhost\/?page=home", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "OUTLOOK_AUTH_URI", + "valueDefault": "https:\/\/login.live.com\/oauth20_authorize.srf", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "OUTLOOK_TOKEN_URI", + "valueDefault": "https:\/\/login.live.com\/oauth20_token.srf", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "OUTLOOK_REFRESH_URI", + "valueDefault": "https:\/\/login.live.com\/oauth20_token.srf", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "OFFICE365_CLIENT_ID", + "valueDefault": "", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "OFFICE365_CLIENT_SECRET", + "valueDefault": "", + "comment": "", + "commentHtml": null, + "inputType": "password", + "setValues": null + }, + { + "key": "OFFICE365_CLIENT_URI", + "valueDefault": "http:\/\/localhost\/?page=home", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "OFFICE365_AUTH_URI", + "valueDefault": "https:\/\/login.live.com\/oauth20_authorize.srf", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "OFFICE365_TOKEN_URI", + "valueDefault": "https:\/\/login.live.com\/oauth20_token.srf", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + }, + { + "key": "OFFICE365_REFRESH_URI", + "valueDefault": "https:\/\/login.live.com\/oauth20_token.srf", + "comment": "", + "commentHtml": null, + "inputType": "text", + "setValues": null + } + ], + "recaptcha.php": [ + { + "key": "RECAPTCHA_SECRET", + "valueDefault": "", + "comment": "-----------------------------------\nConstants used for google recaptcha\n-----------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !", + "commentHtml": "-----------------------------------\nConstants used for google recaptcha\n-----------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !", + "inputType": "password", + "setValues": null + }, + { + "key": "RECAPTCHA_SITE_KEY", + "valueDefault": "", + "comment": "Site key from the recaptcha admin", + "commentHtml": "Site key from the recaptcha admin", + "inputType": "password", + "setValues": null + } + ], + "wordpress.php": [ + { + "key": "WORDPRESS_CLIENT_ID", + "valueDefault": "", + "comment": "[wordpress.com]\n----------------------------------------------------------\nConstants used for oauth2 communication with WordPress.com\n----------------------------------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !", + "commentHtml": "[wordpress.com]\n----------------------------------------------------------\nConstants used for oauth2 communication with WordPress.com\n----------------------------------------------------------\nSECURITY ALERT ! MAKE SURE THAT THIS FILE IS NOT ACCESSIBLE BY THE BROWSER !", + "inputType": "password", + "setValues": null + }, + { + "key": "WORDPRESS_CLIENT_SECRET", + "valueDefault": "", + "comment": "", + "commentHtml": null, + "inputType": "password", + "setValues": null + }, + { + "key": "WORDPRESS_CLIENT_URI", + "valueDefault": "", + "comment": "", + "commentHtml": null, + "inputType": "password", + "setValues": null + } + ] +} \ No newline at end of file diff --git a/data/fetch.php b/data/fetch.php new file mode 100644 index 0000000..c70ad92 --- /dev/null +++ b/data/fetch.php @@ -0,0 +1,189 @@ +(.|\n)*?)\*\/(.|\n)*?)?env\(\'(?.*?)\'(, *?(?.*?))?\)/'; +$REGEX_REMOVE_FIRST_COMMENT = '/\/\*(.|\n)*?\*\//'; +$REGEX_REMOVE_LINE_COMMENTS = '/ *\/\/.*?$/m'; +$REGEX_VALID_VALUES = '/Valid values.*?\n(?(.|\n)*)/'; +$FILES = json_decode(file_get_contents("data/configFiles.json"), false); + + +function getFile($filename) { + $filepath = $GLOBALS["CACHE_DIR"] . $filename; + + if (!is_file($filepath)) { + $data = file_get_contents( + $GLOBALS["BASE_URL"] . $filename, + false, + stream_context_create([]) + ); + $write = fopen($filepath, "w"); + fwrite($write, $data); + fclose($write); + } + return file_get_contents($filepath); +} + + +if (!is_dir($GLOBALS["CACHE_DIR"])) { + mkdir($GLOBALS["CACHE_DIR"]); +} + +$options = (object) []; +for ($i = 0; $i < count($FILES); $i++) { + $filename = $FILES[$i]; + $contents = getFile($filename); + + if ($filename == "app.php") { + $contents = preg_replace($REGEX_REMOVE_FIRST_COMMENT, "", $contents, 1); + $contents = preg_replace($REGEX_REMOVE_LINE_COMMENTS, "", $contents); + } + $fileOptions = array(); + + preg_match_all( + $REGEX_THE_BIG_ONE, + $contents, + $matches, + PREG_SET_ORDER); + + foreach ($matches as $match) { + $key = $match["key"]; + $valueDefault = (array_key_exists("default", $match) ? trim($match["default"], " '") : null); + $comment = $match["comment"]; // TODO Run cleancomment + $commentHtml = null; + $setValues = null; + if ($comment) { + // Clean comment + $commentLines = explode( + "\n |", + preg_replace('/\n\n/', "\n", $comment) + ); + $commentLines = array_map('trim', $commentLines); + $commentLines = array_filter($commentLines); + $comment = implode("\n", $commentLines); + + // Create HTML-innerText-insertable comment + $commentHtml = preg_replace('/\n/', "
", $comment); + $commentHtml = preg_replace('/ /', " ", $comment); + } + + + + // Determine input type + if ($valueDefault) { + if (is_int($valueDefault)) { + $inputType = "number"; + } else if ($valueDefault == "false" || $valueDefault == "true") { + $inputType = "checkbox"; + } else if (is_string($valueDefault)) { + $inputType = "text"; + } + } else { + switch ($key) { + case "DEFAULT_SMTP_TLS": + case "LDAP_AUTH_TLS": + case "DEFAULT_SMTP_TLS": + case "DEFAULT_SMTP_NO_AUTH": + case "AUTO_CREATE_PROFILE": + case "ALWAYS_MOBILE_UI": + case "ENCRYPT_AJAX_REQUESTS": + case "ENCRYPT_LOCAL_STORAGE": + $inputType = "checkbox"; + break; + + case "DEFAULT_SMTP_NAME": + case "DEFAULT_SMTP_SERVER": + case "ADMIN_USERS": + case "COOKIE_DOMAIN": + case "COOKIE_PATH": + case "DEFAULT_EMAIL_DOMAIN": + case "REDIRECT_AFTER_LOGIN": + case "AUTH_CLASS": + case "API_LOGIN_KEY": + case "MEMCACHED_USER": + case "SESSION_CLASS": + $inputType = "text"; + break; + + case "DB_PASS": // database.php + case "REDIS_PASS": + case "MEMCACHED_PASS": + case "APP_2FA_SECRET": // 2fa.php + $inputType = "password"; + break; + + case "DEFAULT_SMTP_PORT": + $inputType = "number"; + break; + } + } + + + if (str_contains($key, "SECRET")) { + $inputType = "password"; + } + + if ($comment) { + // Fetch setValues + preg_match( + $REGEX_VALID_VALUES, + $comment, + $match); + if ($match) { + $unfiliterdValues = explode("\n", $match["values"]); + $values = array(); + $customAlreadyAdded = false; + + foreach ($unfiliterdValues as $value) { + if ($customAlreadyAdded) { + // add all text after custom to custom + $customAndMore = trim(array_pop($values)) . " " . trim($value); + $values[] = $customAndMore; + continue; + } + // manual override + if (!str_starts_with($value, "langauge codes")) { + $values[] = $value; + if (str_starts_with($value, "custom")) { + $customAlreadyAdded = true; + } + } + } + if (count($values) > 0) { // superfluous? + $setValues = array(); + foreach ($values as $commentLine) { + $keyIndex = strpos($commentLine, ' '); + $setValues[] = (object) [ + "value" => substr($commentLine, 0, $keyIndex), + "description" => trim(substr($commentLine, $keyIndex)), + ]; + } + $inputType = "select"; + } + } + } + + if (!isset($inputType)) { + throw new Exception("inputType could not be determined for $key"); + } + + + // Push to array + $fileOptions[] = (object) [ + "key" => $key, + "valueDefault" => $valueDefault, + "comment" => $comment, + "commentHtml" => $commentHtml, + "inputType" => $inputType, + "setValues" => $setValues + ]; + } + + $options->$filename = $fileOptions; +} +$out = fopen("data/configOptions.json", "w"); +fwrite($out, json_encode($options, JSON_PRETTY_PRINT)); +fclose($out); + +?> \ No newline at end of file diff --git a/developers-documentation.html b/developers-documentation.html deleted file mode 100644 index 69e54ad..0000000 --- a/developers-documentation.html +++ /dev/null @@ -1,1082 +0,0 @@ - - - - - - - Documentation - - - - - - - - -
- -
- -
-
-

Folder structure

-

.github

-

This folder contains files used for CI/CD on GitHub, such as running tests during merge requests and - building Docker images. It streamlines collaboration, automates processes, and ensures consistency - across the repository. You'll also find templates for pull requests, issues, and bug reports. To edit - the default text in a merge request description, simply modify the relevant file in this folder.

- -

.travis

-

Refer to https://docs.travis-ci.com/user/for-beginners/

- -

Config

-

This was introduced with the support of .env files in Cypht

-

It contains all the contents of the .env file grouped by semantics within the files. Files in this folder - return an array. They simply take the values from the .env file and set a default value if it is not - defined in .env.

-

A special case is that the Dynamic.php file (not tracked by git) is automatically generated every time - you change something in the .env file. After compiling all other files in this folder, this is the - configuration file used by Cypht at runtime.

-

Related PR: Switching cypht config hm3.* to dotenv

-

https://github.com/cypht-org/cypht/pull/823/

- -

language

-

Contain translation files

- -

lib

-

Contain the core of Cypht

- -

modules

-
    -
  • site.js: contains module-specific javascript code
    • -
  • site.css: contains module-specific CSS code
    • -
  • setup.php: These are management modules, output modules, pages, allowed post variables, allowed get - variables, allowed output variables, allowed cookies are set.
    • -
  • modules.php: This file contains handlers and output classes. Some modules with multiple handlers, - outputs and functions may use this file to simply include other files. Take a look at - modules/core/modules.php to get an idea.
    • -
  • Assets folder: some modules have assets (fonts, images, samples). Please see the core or local_contacts - modules.
    • -
-

Contains all modules. Each module contains the files below:

- -

You will get a detailed explanation of how each module works in config/app.php.

- -

scripts

-

Contains script files to generate configuration (done once after installation), create/delete/update user - accounts, generate necessary tables to manage users, sessions, or settings based on values in the - environment file and finally others script for development purpose.

- -

site

-

The site folder contains production files generated by scripts/config_gen.php

- -

tests

-

contains PHPUnit and selenium tests

- -

third_party

-

Contains third party minified files used in Cypht

- -

.env

-

The .env file is for high-level configuration. For any variables you're unsure about, check the - configuration folder for detailed explanations.

- -

How to

-

See the new link in the left menu

-

Sometimes you can add a link to the left menu without seeing it. Cypht caches all menus. You need to - click on the reload link below the navigation menu.

- -

Create a page

-

Cypht supports two types of pages: basic and AJAX. Basic pages are accessible via URL and require a page - reload, while AJAX pages load asynchronously.

- -

To create a page called list_messages that displays all messages from the database, navigate to the - correct module (e.g., the nux module) and insert the following code just before the return array:

- -

In nux/setup.php:

- - setup_base_page('all_messages', 'core');
- add_handler('all_messages', 'load_messages', true);
- add_output('all_messages', 'print_messages', true); - - -

- setup_base_page adds your new page to the routes, the first argument is the name of the page accessible - by typing /?page=all_messages in the browser in this case

-

- add_handler adds a handler to the page. A handler class contains logic, validates forms, binds alert - messages, and passes output variables for use in the output.

-

- add_output adds output to the page. An output class contains HTML that will be returned to the client by typing /?page=all_messages

- -

Handler and Output Modules

-

In nux/modules.php:

- - - class Hm_Handler_load_messages extends Hm_Handler_Module {
- public function process() {
- // Do some logic here
- // Get the list of messages
- // Pass the list to the output
- }
- }

- class Hm_Output_print_messages extends Hm_Output_Module {
- protected function output() {
- // Get the list of message passed by Hm_Handler_load_messages
- // Build the html that will be returned
- // Use return statement to return the html
- }
- } - - -

Let's say you want to add an ajax page called ajax_load_new_messages which will receive new messages sent - to the user and update the message list every 15 seconds.

- -

In nux/setup.php:

- - - setup_base_ajax_page('ajax_load_new_messages', 'core');
- add_handler('ajax_load_new_messages', 'get_new_messages', true);
- add_output('ajax_load_new_messages', 'print_new_messages', true); - - -

In nux/modules.php:

- - - class Hm_Handler_get_new_messages extends Hm_Handler_Module {
- public function process() {
- // Do some logic here
- // Get the list of new messages
- // Pass the list to the output
- }
- }

- class Hm_Output_print_new_messages extends Hm_Output_Module {
- protected function output() {
- // Get the list of messages passed by Hm_Handler_get_new_messages
- // Build the HTML that will be returned
- // Use the out to return data
- $this->out('ajax_messages', $new_messages);
- }
- } - - -

Add this code in nux/site.js to run your ajax page every 15 seconds: -

- - - $(function() {
- if (hm_page_name() === 'all_messages') {
- setInterval(function() {
- Hm_Ajax.request(
- [{'name': 'hm_ajax_hook', 'value': 'ajax_load_new_messages'}],
- function(res) {
- if (res.ajax_messages) {
- // Append new messages to the list of messages
- $('#messages_list').append(res.messages);
- }
- }
- );
- }, 15000);
- }
- }); - - -

Note: If setup_base_ajax_page does not have output modules, the - values returned with $this->out() will be accessible in res in JavaScript.

- -

Finally, add the following code to nux/setup.php:

- - - return array(
- 'allowed_pages' => array(
- ...
- 'ajax_load_new_messages',
- 'all_messages'
- ),
- 'allowed_get' => array(
- ...
- ),
- 'allowed_output' => array(
- ...
- 'ajax_messages'
- ),
- 'allowed_post' => array(
- ...
- )
- ); - - -

Add all_messages and ajax_load_new_messages to the list of allowed pages.

-

Add ajax_messages to the list of allowed outputs.

-

Add post/get variables if they exist in the list of allowed get/posts.

- -

Note: A page can have multiple handlers/outputs. A full list of all handlers and outputs attached to - a page can be seen by accessing ?page=info page on your instance in - the configuration map section.

- -

Add third party

-

Copy the minified file to the third-party directory

-

Add the file path in Hm_Output_page_js~np~::~/np~output or Hm_Output_header_css~np~::~/np~output if it is - a CSS file.

-

Finally, add the file in the combine_includes function in scripts/config_gen.php so that it is added when - generating the production site.

- -

Enable a module

-

Edit .env file and add your module to CYPHT_MODULES variable

- -

Create a module

-

In the modules folder, you'll find a hello_world module with the necessary scaffolding for creating a - new module. Customize your module by following the code explained above.

- -

Translate string

-

If you need to translate a string in:

- -

Handler module:

-

Most strings in handlers are only intended to alert the user of success/information/failure operations. - And so they are all written without a translation method but they are all translated later in the - Hm_Output_msgs::output function.

- -

Output module:

- - - $this->trans("Your text here"); - - -

JS file:

- - - hm_trans("Your text here", "en"); - - -

The second parameter here is optional because the default language is the user's language in the settings - page.

- -

Add new translation string

-

Add your string to each file contained in the language folder.

-

The file names in this folder are language codes. And all return an array. Just add your new string to - the end of the array. If you know the translation of the text in a language, add it as a value, - otherwise add false as a value.

- -

Add new language

-

Duplicate the en.php file into the language folder

-

Rename it (Cypht uses 2 digit code, please refer to https://en.wikipedia.org/wiki/List_of_ISO_639_lingual_codes)

-

In the renamed file, modify interface_lang and interface_direction in the array accordingly.

-

Add your language in the interface_langs() function.

-

Update this test to add your language: Hm_Test_Core_Output_Modules::test_lingual_setting

- -

Run test

-

Cypht has PHPUnit tests and selenium

- -

PHPUnit

-

To run all tests:

- - php vendor/phpunit/phpunit/phpunit --configuration tests/phpunit/phpunit.xml - - -

To run tests contained in a class or a single test method:

-

To run tests contained in a class or a single test method:

- - - php vendor/phpunit/phpunit/phpunit --configuration tests/phpunit/phpunit.xml --filter classOrMethodName - - -

To run Selenium tests, make sure you have Python installed (https://www.python.org/downloads/). Once Python is - installed, you should be able to run the following command:

- - - pip install -r requirements.txt - - -

This command will install all required packages. The - requirements.txt file is located at tests/selenium, so make sure to specify the correct path in the - command line, or navigate to that location.

- -

Once all packages are installed, you can run Selenium tests - using this command:

- - - sh runall.sh - -

Fix PHPUnit failing tests

-

Run all tests or filter specific ones, and the console will show the results. In VSCode or similar, click - on the file path to go directly to the line causing the issue. Check recent changes to classes, divs, or - logic in the handlers that may be causing the failure.

- - - There was 1 failure: - - 1) Hm_Test_Uid_Cache::test_uid_is_read - - Failed asserting that true is false. - - /Applications/MAMP/htdocs/cypht/tests/phpunit/cache.php:19 - -

Debug AJAX requests

-

Cypht relies heavily on AJAX requests. To debug, add var_dump and exit in your code. Open your browser's - developer tools, go to the Network tab, filter by Fetch/XHR to see AJAX requests, then run the code. - Click on the request you want to inspect and view the preview or response.

- -

The core module

-

The core module handles:

-

- Rendering CSS headers

-

- Displaying alert messages

-

- Loading JS files and defining shared JS functions

-

- Configuring basic features like backups, server pages, settings, etc.

- -

Practical Example: 1. Add a test page

-

As mentioned earlier, we use the setup_base_page function to add a new page. We'll call this function to - make our test page available:

-

In core/setup.php:

- - - setup_base_page('test'); - -

My Cypht project is available locally at cypht.test. Once we have added this page, we should be able to - access cypht.test as follows: cypht.test?page=test

- - - -

You might find it strange that we see "Page Not Found!" 😔, but understand that this is completely normal - because we have explained the concept of authorizing pages, forms, etc.

- -

In core/setup.php:

- - - /* allowed input */
- return array(
- 'allowed_pages' => array(
- ...
- 'test'
- ),
- 'allowed_output' => array(
- ...
- ),
- 'allowed_cookie' => array(
- ...
- ),
- 'allowed_server' => array(
- ...
- ),
- 'allowed_get' => array(
- ...
- ),
- 'allowed_post' => array(
- ...
- )
- ); - - -

After authorizing our page, we can now see a blank page. At least we are getting a result, even if it's - not yet what we expected 😁.

- - - -

As mentioned earlier, the concepts of output and handle are important. At this stage, we define outputs - to display the content of our pages. To show content to the user, create outputs containing HTML.

- -

In core/setup.php:

- - - add_output('test', 'test_heading', true, 'core', 'content_section_start', 'after'); - - -

The first parameter refers to the page that we defined above: test. The second parameter refers to the - class (module) that we need to define in core/modules.php with the name Hm_Output_test_heading (In the - definition of the output in setup.php, we are not going to include Hm_Output_ because it is a prefix - that will be detected automatically). The third parameter allows you to indicate whether this content - will be displayed based on the user's authentication status. The fourth parameter indicates the module - that contains the module (output) code. The fifth parameter indicates the position on our page where - this content will be displayed, and the sixth parameter, which goes with the fifth, determines whether - this content will be before or after the fifth parameter.

- -

Here is Hm_Output_content_section_start, the content after which we want to display our header.

- -

In core/output_modules.php:

- - - class Hm_Output_content_section_start extends Hm_Output_Module {
- /**
- * Opens a main tag for the primary content section
- */
- protected function output() {
- return '.$this->trans('Offline').' - }
- - -

In our case, we want to place our html content before closing:

-

In core/output_modules.php: -

- - <div class="row m-0 position-relative">
- <main class="container-fluid content_cell"> - - -

Here is the definition of the module: test_heading which will display the title Test in the header

-

In core/output_modules.php: -

- - - class Hm_Output_test_heading extends Hm_Output_Module {
- /**
- */
- protected function output() {
- return '<div class="content_title">'.$this->trans('Test').'</div>';
- }
- } - - -

And here is the result we get; we start to see the result that we are looking for 👌.

- - - -

Now that we know how to add content, let's add another section after the header.

- -

Define the output in core/setup.php to display it right after the header. You should already know what - the penultimate and last parameters will be.

-

In core/setup.php:

- - - add_output('test', 'test_first_div', true, 'core', 'test_heading', 'after'); - - -

Let's define our class(module): test_first_div

-

In core/output_modules.php: -

- - - class Hm_Output_test_first_div extends Hm_Output_Module {
- protected function output() {
- return '<div class="mt-3 col-lg-6 col-md-12 col-sm-12"> - <div class="card"> - <div class="card-body"> - <div class="card_title"> - <h4>'.$this->trans('Test').'</h4> - </div> - '.$this->trans('We are just testing').' - </div> - </div> - </div>'; - }
- } - - -

And here is the result we hope for:

- - -

Let's add another element to our page just after our second - element:

-

In core/setup.php:

- - - add_output('test', 'test_second_div', true, 'core', 'test_first_div', 'after'); - - -

In core/output_modules.php: -

- - - class Hm_Output_test_second_div extends Hm_Output_Module {
- protected function output() {
- return '<div class="mt-3 col-lg-6 col-md-12 col-sm-12">'.
- '<div class="card">'.
- '<div class="card-body">'.
- '<div class="card_title">'.
- '<h4>'.$this->trans('Test again').'</h4></div>'.
- $this->trans('We are again just testing').' '.
- '</div>'.
- '</div>'.
- '</div>';
- }
- } - - -

And here is the result:

- - -

Now that we know how to add content, let's add a form element to - the page. We'll submit the form and handle its processing in the backend

-

In core/setup.php:

- - - add_output('test', 'test_third_div', true, 'core', 'test_second_div', 'after'); - - -

In core/output_modules.php: -

- - - class Hm_Output_test_third_div extends Hm_Output_Module { - protected function output() { - return '<div class="nux_help mt-3 col-lg-12 col-md-12 col-sm-12">' + - '<div class="card">' + - '<div class="card-body">' + - '<div class="card_title"><h4>' + - $this->trans('Test Our Form') + '</h4></div>' + - '<form class="add_server me-0" method="POST" action="?page=test">' + - '<input type="hidden" name="hm_page_key" value="' + - $this->html_safe(Hm_Request_Key::generate()) + '" />' + - '<div class="subtitle mt-4">Tag name</div>' + - '<div class="form-floating mb-3">' + - '<input required type="text" id="new_tag_name" name="new_tag_name" class="txt_fld' - 'form-control" value="" placeholder="' + $this->trans('Tag name') + '" />' + - '<label class="" for="new_tag_name">' + - $this->trans('Tag name') + '</label>' + - '</div>' + - '<input type="submit" class="btn btn-primary px-5" value="' + - $this->trans('Add') + '" name="submit_tag" />' + - '</form>' + - '</div>' + - '</div>' + - '</div>'; - } - } - - -

Here is the result:

- - -

We learned that add_output allows us to add HTML content to the page, while add_handler is used for - backend processing (like a controller). Both accept similar parameters, with the concepts of 'before' - and 'after' applying to handlers instead of outputs. Remember that these refer to other handlers, and - the class will extend Hm_Handler_Module

-

In core/setup.php:

- - add_handler('test', 'process_test_third_div', true, 'core', 'load_user_data', 'after'); - - -

Don't forget to authorize the form field in 'allowed_post'; otherwise, you won't be able to access it. -

- -

In core/setup.php:

- - - /* allowed input */
- return array(
- 'allowed_pages' => array(
- '...',
- 'test'
- ),
- 'allowed_output' => array(
- '...',
- ),
- 'allowed_cookie' => array(
- '...',
- ),
- 'allowed_server' => array(
- '...',
- ),
- 'allowed_get' => array(
- '...',
- ),
- 'allowed_post' => array(
- '...',
- 'new_tag_name' => FILTER_DEFAULT
- )
- ); - - -

We can now define our handler:

- -

In core/handler_modules.php:

- - - class Hm_Handler_process_test_third_div extends Hm_Handler_Module {
- /**
- * If "stay logged in" is checked, set the session lifetime
- */
- public function process() {
- list($success, $form) = $this->process_form(array('new_tag_name'));
- if ($success && $form['new_tag_name']) {
- // var_dump($form);die();
- }
- }
- } - - -

In this documentation, we've discussed how to pass data from POST to GET. Let's consider a scenario where - we want to display the entered data as the label for a field in our form. This involves using sessions - in Cypht:

- -

In core/handler_modules.php:

- - $this->session->set('key', 'value'); - - -

Our code will look like this:

- -

In core/handler_modules.php:

- - - class Hm_Handler_process_test_third_div extends Hm_Handler_Module {
- /**
- * If "stay logged in" is checked, set the session lifetime
- */
- public function process() {
- list($success, $form) = $this->process_form(array('new_tag_name'));
- if ($success && $form['new_tag_name']) {
- $this->session->set('tag_name', $form['new_tag_name']);
- }
- }
- } - - -

Remember: to retrieve our stored data, we need another handler, and it must be placed after the handlers - that store the data; otherwise, it may cause malfunctions.

- -

In core/setup.php:

- - add_handler('test', 'get_test_third_div', true, 'core', 'load_user_data', 'after'); - - -

To retrieve an element from the session, we will do it like this:

- - - $res = $this->session->get('key', 'Default Value'); - - -

Let's also define the module in handler_modules.php

- -

In core/handler_modules.php:

- - class Hm_Handler_get_test_third_div extends Hm_Handler_Module {
- /**
- * If "stay logged in" is checked, set the session lifetime
- */
- public function process() {
- $res = $this->session->get('tag_name', 'Tag name');
- if(!is_null($res)) {
- $this->out('tag_name', $res);
- // we can now delete session as we do not need no more
- $this->session->del('tag_name');
- }
- }
- } - - -

This is how you can delete an element from the session

- - - $this->session->del('key'); - - -

In the Hm_Handler_get_test_third_div module, we will never encounter a null value because we provided a - default. Therefore, the is_null condition is unnecessary. We use $this->out('tag_name', $res); to pass - our data to the output. To retrieve it from the output, we will do it like this:

- - - $this->get('key'); - - -

We will have to edit our class Hm_Output_test_third_div like this:

- -

In core/output_modules.php: -

- - class Hm_Output_test_third_div extends Hm_Output_Module {
- protected function output() {
- $tag_name = $this->get('tag_name');
- return '<div class="nux_help mt-3 col-lg-12 col-md-12 col-sm-12">'.
- '<div class="card">'.
- '<div class="card-body">'.
- '<div class="card_title"><h4>'.$this->trans('Test Our Form').'</h4></div>'.
- '<form class="add_server me-0" method="POST" action="?page=test">'.
- '<input type="hidden" name="hm_page_key" value="'.$this->'.
- 'html_safe(Hm_Request_Key::generate()).'" />'.
- '<div class="subtitle mt-4">'.$tag_name.'</div>'.
- '<div class="form-floating mb-3">'.
- '<input required type="text" id="new_tag_name" name="new_tag_name".
- 'class="txt_fld form-control" value="" placeholder="'.$this->'.
- 'trans('Tag name').'" />'.
- '<label class="" for="new_tag_name">'.$tag_name.'</label>'.
- '</div>'.
- '<input type="submit" class="btn btn-primary px-5" value="'.$this->.
- trans('Add').'" name="submit_tag" />'.
- '</form>'.
- '</div>'.
- '</div>'.
- '</div>';
- }
- } - - -

Result before:

- -

Result after:

- - -

Practical Example: 2. How to add new settings

-

Let's start by adding a simple parameter and then we'll see how to add another section after.

- -

We will add our setting after this content:

-

On page settings

- - Default message sort order - - - -

We will need a handle and an output for that:

- -

In core/setup.php:

- - add_handler('settings', 'process_test_enable_tag_with_parent', true, 'tags', 'save_user_settings', 'before');
- add_output('settings', 'test_enable_tag_with_parent_setting', true, 'tags', 'default_sort_order_setting', 'after'); - - -

default_sort_order_setting is the output for 'Default message sort order.' When adding an output, we need - to specify its position. In this case, we want to place it after default_sort_order_setting. The - process_test_enable_tag_with_parent_setting must come before save_user_settings since we need to save it - as well. Thus, our configuration process will be applied and saved before handling save_user_settings. -

- -

Now that we’ve defined our routes, we need to write the module for processing: - process_test_enable_tag_with_parent_setting for the handle and test_enable_tag_with_parent_setting for - the output.

- -

In module.php:

- - /**
- * @subpackage tags/handler
- */
- class Hm_Handler_process_test_enable_tag_with_parent_setting extends Hm_Handler_Module {
- public function process() {
- function test_tag_with_parent_enabled_callback($val) { return $val; }
- process_site_setting('test_enable_tag_with_parent', $this, 'test_tag_with_parent_enabled_callback', true, true);
- }
- } - - -

and this is the corresponding output:

- -

In module.php:

- - /**
- * @subpackage tags/output
- */
- class Hm_Output_test_enable_tag_with_parent_setting extends Hm_Output_Module {
- protected function output() {
- $settings = $this->get('user_settings');
- if (array_key_exists('test_enable_tag_with_parent', $settings) && $settings['test_enable_tag_with_parent']) {
- $checked = ' checked="checked"';
- $reset = '';
- }
- else {
- $checked = '';
- $reset = '';
- }
- return '<tr class="general_setting"><td><label class="form-check-label" for="test_enable_tag_with_parent">'.
- $this->trans('Test Tag enable parent').''.
- '<td><input class="form-check-input" type="checkbox" '.$checked.
- ' value="1" id="test_enable_tag_with_parent" name="test_enable_tag_with_parent" />'.$reset.'
- }
- } - - -

reset_default_value_checkbox class here is being used - in js (module core site.js) to restore the default value at line:

- -

In core/site.js:

- - $('.reset_default_value_checkbox').on("click", reset_default_value_checkbox); - - -

Remember, if you make changes, you need to define the restore action in JavaScript, as this can occur in - various scenarios.

-

You can now refresh your page to see the result:

- - -

You might be wondering why updating our parameter gives an unexpected result; this is normal. Let me - explain: remember the crucial concepts in Cypht related to authorizations and validations (such as - allowed_pages, allowed_output, allowed_post, etc.). In this case, we need to authorize our - test_enable_tag_with_parent field in POST.

- -

In core/setup.php:

- - 'allowed_post' => array(
- 'test_enable_tag_with_parent' => FILTER_VALIDATE_INT
- ) - -

By adding this permission, the display will remain unchanged, but the update will work as intended. To - access this setting in Cypht, use the usual syntax:

-

In core/setup.php:

- - $this->user_config->get('test_enable_tag_with_parent_setting') - - -

Now that we know how to add a simple setting, let's explore how to add a section to the settings page: -

- - -

The goal is to add a new section to our settings page. Here’s how:

- - - -

In the image above, our section contains two elements, so we will define two handles to process them, - along with three outputs: one for the section title, one for the first element, and another for the - second element.

- -

In tags/setup.php:

- - add_handler('settings', 'process_tag_source_max_setting', true, 'tags', 'load_user_data', 'after');
- add_handler('settings', 'process_tag_since_setting', true, 'tags', 'load_user_data', 'after');
- add_output('settings', 'start_tag_settings', true, 'tags', 'sent_source_max_setting', 'after');
- add_output('settings', 'tag_since_setting', true, 'tags', 'start_tag_settings', 'after');
- add_output('settings', 'tag_per_source_setting', true, 'tags', 'tag_since_setting', 'after'); - - -

We can now add modules, let's start with process_tag_source_max_setting:

-

In tags/modules.php:

- - /**
- * Process "tag_per_source" setting for the tag page in the settings page
- * @subpackage core/handler
- */
- class Hm_Handler_process_tag_source_max_setting extends Hm_Handler_Module {
- /**
- * Allowed values are greater than zero and less than MAX_PER_SOURCE
- */
- public function process() {
- process_site_setting('tag_per_source', $this, 'max_source_setting_callback', DEFAULT_PER_SOURCE);
- }
- } - - -

and for process_tag_since_setting:

-

In tags/modules.php:

- - /**
- * Process "since" setting for the junk page in the settings page
- * @subpackage core/handler
- */
- class Hm_Handler_process_tag_since_setting extends Hm_Handler_Module {
- /**
- * valid values are defined in the process_since_argument function
- */
- public function process() {
- process_site_setting('tag_since', $this, 'since_setting_callback');
- }
- } - - -

That's all for our handles, we need to add output modules too; let's start with "start_tag_settings":

-

In tags/modules.php:

- - /**
- * Starts the Tag section on the settings page
- * @subpackage core/output
- */
- class Hm_Output_start_tag_settings extends Hm_Output_Module {
- /**
- * Settings in this section control the tag messages view
- */
- protected function output() {
- $res = ''.
- ''.
- $this->trans('Tags').'';
- print_r($res);
- return $res;
- }
- } - - -

for "tag_since_setting" add:

-

In tags/modules.php:

- - /**
- * Option for the "junk since" date range for the Junk page
- * @subpackage core/output
- */
- class Hm_Output_tag_since_setting extends Hm_Output_Module {
- /**
- * Processed by Hm_Handler_process_tag_since_setting
- */
- protected function output() {
- $since = DEFAULT_SINCE;
- $settings = $this->get('user_settings', array());
- if (array_key_exists('tag_since', $settings) && $settings['tag_since']) {
- $since = $settings['tag_since'];
- }
- return '
- $this->trans('Show junk messages since').''.
- ''.message_since_dropdown($since, 'tag_since', $this).'';
- }
- } - - -

and for "tag_per_source_setting" add:

-

In tags/modules.php:

- - /**
- * Option for the maximum number of messages per source for the Junk page
- * @subpackage core/output
- */
- class Hm_Output_tag_per_source_setting extends Hm_Output_Module {
- /**
- * Processed by Hm_Handler_process_tag_source_max_setting
- */
- protected function output() {
- $sources = DEFAULT_PER_SOURCE;
- $settings = $this->get('user_settings', array());
- $reset = '';
- if (array_key_exists('tag_per_source', $settings)) {
- $sources = $settings['tag_per_source'];
- }
- if ($sources != 20) {
- $reset = '';
- }
- return '<tr class="tag_setting"><td><label for="tag_per_source">'.
- $this->trans('Max messages per source').'</label></td>'.
- '<td class="d-flex"><input type="text" size="2" class="form-control form-control-sm w-auto" - id="tag_per_source" name="tag_per_source" value="'.$this->html_safe($sources).'" />'.$reset.'</td></tr>';
- }
- } - - -

And there you have it! Refresh your page to see the result:

- - -
-

-

Related links:

- https://github.com/dovecot/imaptest/wiki/About
- https://jmap.io/spec.html
- http://sieve.info/
- https://p5r.uk/blog/2011/sieve-tutorial.html
- https://www.fastmail.com/help/technical/sieve.html
- https://docs.gandi.net/en/gandimail/sieve/sieve_tutorial.html -
- - - - - - - - - \ No newline at end of file diff --git a/email-filters.html b/email-filters.html deleted file mode 100644 index 49b5c2b..0000000 --- a/email-filters.html +++ /dev/null @@ -1,215 +0,0 @@ - - - - - - Email filters - - - - - - -
- -
- -
-

Email filters

-

Cypht now supports Sieve, a powerful email filtering language that gives you complete control over your inbox. With Sieve, you can create complex filters to sort, move, delete, and flag your emails automatically. You can also use Sieve to create custom notifications and alerts.

-

One key feature of Sieve is that filters run server-side, so they work even when you are not currently logged in. However, it is important to note that your email server must support Sieve for these filters to function properly.

-

Here are just a few of the things you can do with Sieve:

-
-
    -
  • - Filter out spam and unwanted emails. Sieve filters can be used to filter out spam and unwanted emails based on their sender, subject, or content. -
    • -
    -
  • - Organize your inbox automatically. Sieve filters can be used to automatically move or copy your emails into different folders based on their sender, subject, or content. -
    • -
    -
  • - Forward important emails to specific people. Sieve filters can be used to automatically forward important emails to specific people, such as your manager or your assistant. -
    • -
    -
  • - Sieve filters can be used to create custom notifications and alerts for important emails, such as those from your boss or clients. Unlike simply forwarding the email, these notifications and alerts can provide immediate and specific information, ensuring you stay updated without needing to sift through your inbox. -
    • -
    -
-
-

To get started with Sieve in Cypht, simply go to your config file (hm3.ini for Cypht 1.4.x or .env for Cypht 2.0.x) and enable the Sieve filter engine by enabling modules[ ]=sievefilters or by adding sievefilters on CYPHT_MODULES variable like: - - 

modules[]=sievefilters #For Cypht 1.4.x
-CYPHT_MODULES="sievefilters" #For Cypht 2.0.x
- Once you have enabled the Sieve filter engine, you can create and manage your filters in the Filters section of the Cypht interface. You can create new filters, edit existing filters, and delete filters as needed. -

-

How to create a Sieve filter in Cypht?

-

- To create a Sieve filter in Cypht follow these steps: -

- -
    -
  • - Go to Settings tab in the sidebar.
    Then click on Filters tab, select the E-mail account you want for filters and click on the "Add Filter" button. -
    • -
  • - In the "Filter name" field, enter a name for your new filter. Then, provide other details of the filter:
    -
      -
    • Priority: It defines an order value (or priority value) for your filter. Note that filters will run from the lowest to the highest priority value.
      • -
    • Test: This will help to combine two or more conditions.
      • -
    -
    • -
  • - In the "Conditions section",
    - you can add one or many conditions to your filter. You can add conditions based on the sender, subject, body, etc. Check out the documentation page for other information. -
    • -
-
-

- And there you go: 😄Enjoy filters with Cypht. -

-

Creating custom notifications and alerts: -

-

You can also use Sieve to create custom notifications and alerts for important emails. For example, you could create a filter that sends you a notification every time you receive an email from your boss. - - To create a custom notification or alert in Cypht, simply go to your settings and click on the "Filters" tab. Then, select the E-mail account you want for filters and click on the "Add Script" button. - In the "Filter name" field, enter a name for your new filter. In the "Filter script" field, enter your Sieve code. - - In addition to the Sieve code for filtering emails, you will also need to add the following code to your filter script: - 

require ["fileinto", "imap4flags", "notify"];
-
-# Set variables
-set "boss_email" "boss@example.com";
-
-# Rule to match emails from your boss
-if address :is "from" "${boss_email}" {
-    # Notify you of the new email
-    notify :message "You have a new email from your boss!" :options ["Important"] :method "mailto:your-email@example.com";
-}
-

-

Some examples of Sieve filters: -

-

- The following are some examples of Sieve filters that you can use in Cypht: - 

# Filter out spam and unwanted emails
-require ["fileinto"];
-# Move all emails from the sender "spam@example.com" to the "Spam" folder
-if address :from "spam@example.com" {
-    fileinto "Spam";
-}
-
- 
# Organize your inbox automatically
-require ["fileinto"];
-# Move all emails from the sender "john.doe@example.com" to the "Work" folder
-if address :from "john.doe@example.com" {
-    fileinto "Work";
-}
-# Move all emails with the subject "Important" to the "Important" folder
-if header :subject "Important" {
-  fileinto "Important";
-}
-
-

-

Related links:

- http://sieve.info/
- https://p5r.uk/blog/2011/sieve-tutorial.html
- https://www.fastmail.com/help/technical/sieve.html
- https://docs.gandi.net/en/gandimail/sieve/sieve_tutorial.html -

-
- - - - - - - diff --git a/features.html b/features.html deleted file mode 100644 index ada90c5..0000000 --- a/features.html +++ /dev/null @@ -1,253 +0,0 @@ - - - - - - Features - - - - - - -
- -
- -
-

List of Features

-
-
    -
  • - Combined inbox, unread, sent, and flagged message views for all your E-mail accounts (and - RSS feeds), as well as standard E-mail client folder navigation -
    • -
    -
  • - Flexible profiles to combine IMAP accounts with SMTP accounts and setup signatures and - reply-to details -
    • -
    -
  • - Search all your E-mail accounts and RSS feeds at once with a simple form., or do complex searches across - your accounts with the advanced search module set -
    • -
    -
  • - Move or copy emails from one account to another -
    • -
    -
  • - Compose messages in plain text, HTML, or Markdown -
    • -
    -
  • - Pages are comprised of only 3 HTTP requests totaling ~50KB (gzipped). Data to - populate a page from different sources is collected with parallel AJAX - requests. Output is validated HTML5 and local storage (session only) is used to - cache content for speedier reloads. All the little interface icons use - data-urls so they are served inline (and they can all be disabled). With - standard browser caching, pages tend to transfer 10 to 20 KB -
    • -
    -
  • - Simple interface translation system that does not use gettext or .po files, just - arrays of translated strings defined in PHP. Right to left languages are supported. -
    • -
    -
  • - Module sets for IMAP, SMTP, LDAP or local contacts, WordPress, Github, - and lots more! Check out the Modules page for a - complete list -
    • -
    -
  • - Sessions and user data can be stored in any PDO compatible database or flat - files on the server -
    • -
    -
  • - Authentication is flexible and currently supports IMAP, LDAP, an included - database schema, dynamic authentication using popular E-mail providers, - auto-discovery based on the user's E-mail domain, or you can roll your own with - the site module set -
    • -
    -
  • - Sessions and Authentication can be customized without breaking any modules using - the site module set -
    • -
    -
  • - On the server, page request processing peaks at around 4-5MB of memory. The module system only includes PHP - files required to process the - current request, so time is not wasted parsing unused code paths -
    • -
    -
  • - All the work of processing a request and providing a response is done with - module sets. The application framework manages module assignment and provides a - controlled execution environment, but modules are where the actual work is done -
    • -
    -
  • - There is a build process that pre-calculates module assignments and combines - and compresses page assets, making the production version of your site as fast - as possible. There is also a developer mode in which individual components are - included directly for easy debugging and module development -
    • -
    -
  • - The HTML5 Page structure is semantic and simple, with attention paid to - accessibility best-practices -
    • -
    -
  • - Save the parameters of a search so that you can quickly access them later from - the menu without having to enter them again. This is particularly useful for parameters of - searches that are used frequently. Saved search parameters can also be deleted later. -
    • -
  • - Sieve filters can be created to automatically move, copy, or delete messages based on specific criteria such as sender, subject, keywords, or recipient. This allows for efficient organization and management of incoming emails, saving time and improving productivity. Sieve filters can be easily edited or deleted as needed. For more information on how to create and manage Sieve filters, see Email filters. -
    • -
    -
  • - JMAP (JSON Meta Application Protocol) support for faster, more efficient synchronization of emails across devices. -
    • -
    -
  • - Snooze feature to temporarily hide emails and bring them back at a more convenient time. -
    • -
    -
  • - Screen emails to help manage unwanted or irrelevant communications by filtering or prioritizing certain types of messages. -
    • -
    -
  • - IMAP capabilities for sharing folders to allow collaboration by sharing email folders between accounts. -
    • -
    -
  • - Delivery receipt to get confirmation when your emails are delivered to the recipient's inbox. -
    • -
    -
  • - Support for setting and managing environment variables to customize server-side configurations. -
    • -
    -
  • - IMAP folder subscriptions for managing which folders you want to subscribe to and view in your mail client. -
    • -
    -
  • - Collected Recipients and Trusted Senders feature to track commonly contacted people and trusted email addresses for enhanced security and efficiency. -
    • -
    -
  • - A simpler way to show the source of an email for better understanding of its origin and security analysis. -
    • -
    -
  • - Tags/Labels support to organize and categorize emails easily for better management and quick access to relevant content. -
    • -
    -
  • - Exchange Web Services (EWS) support is in development. For more details and updates, check out the progress here. -
    • -
-
-
- - - - - - - diff --git a/how-to-join.html b/how-to-join.html deleted file mode 100644 index bebb74e..0000000 --- a/how-to-join.html +++ /dev/null @@ -1,177 +0,0 @@ - - - - - - - How to join - - - - - - - -
- -
-
-
-

Getting Started with Cypht Community

-

Introduction

-

- Welcome to the Cypht community! We are excited to have you join us and become a part of our mission to - develop and improve Cypht. This documentation is designed to help you get started with our community, - understand the development process, and contribute effectively to the project. -

-

About the Cypht Community

-

What is Cypht?

-

- Cypht is an open-source email client and news aggregator with a modular design. Unlike traditional - applications, Cypht is built entirely from plugins, or "module sets," with the core modules being - essential. Users can customize their experience by adding or replacing modules to suit specific site - requirements. This modular approach offers flexibility and easy customization, although it may introduce - complexity. -

-

Our Values

-

- As a community, we prioritize collaboration, inclusivity, and transparency. We encourage respect for - others and open communication. Our goal is to create a welcoming environment for all developers, - regardless of experience levels. -

-

Joining the Community

-

Getting Involved

-

- To start your journey with the Cypht community, - - Connect with us on gitter. -

-

Setting up Your Development Environment

-

Tools and Software

-
-

- Before you can contribute to Cypht, you need to set up your development environment. You will need - the - following tools and software: -

-
    -
  • A code editor of your choice (e.g., VSCode, Sublime Text)
    • -
  • Git for version control
    • -
  • PHP for developing Cypht
    • -
  • A web server (e.g., Apache, Nginx) for testing
    • -
-
-

Configuration and Setup

-

For installation, configuration, and setup, please check the installation - page

-

Contributing to Cypht

-

When contributing to Cypht, follow these practices

-

Community Resources

-

For more information and resources, explore the following:

- - -

- Don't hesitate to ask for help or guidance. We have experienced community members who are willing to mentor - and support newcomers. Feel free to reach out on Gitter. -

-
-
- - - - - - - - diff --git a/install-1x.html b/install-1x.html deleted file mode 100644 index 2fae29c..0000000 --- a/install-1x.html +++ /dev/null @@ -1,438 +0,0 @@ - - - - - - - Install - - - - - - - -
- -
- -
-

Install Cypht v1.4.x

-

You can install specific versions of Cypht:

-

- - - - - - - - Cypht v2.x - -

-

Cypht has four differents installation ways:

-
    -
  • Manual installation
    • -
  • Installation within Tiki
    • -
  • install using Docker (use cypht docker image)
    • -
  • Install cypht on a YunoHost server
    • -
-

Please read the bellow explanations about each way and pick one of your choice.

-
-

1. Manual installation

-

Requirements

-

Cypht 1.4.x requires PHP 5.6 or 7.0 or 7.1 or 7.2 or 7.3 or 7.4 (for PHP 8.1+, please use Cypht 2.1+), Composer 2, and at minimum the - OpenSSL, mbstring and cURL extensions. Cypht can also leverage several other - extensions as defined in composer.json. - Testing is done on Debian and Ubuntu - platforms with Nginx and Apache. -

-

Before proceeding please make sure your system meets minimal requirements

-

Steps

-

1. Check minimum requirements

-

- 

-#!/bin/bash
-
-# You need to check php version which should be >=5.6 for version 1.4.x and 7.4 for upcoming Cypht version 2.0
-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
-

-

2. Download and prepare the code

-

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: - - -

- 
-#!/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/cypht-org/cypht/archive/1.4.x.zip
-
-# unpack the archive
-unzip 1.4.x.zip
-
-# run composer
-cd cypht-1.4.x && composer install && cd ..
-
-# create a vanilla ini file
-cp cypht-1.4.x/hm3.sample.ini cypht-1.4.x/hm3.ini
-
-# fix permissions and ownership
-find cypht-1.4.x -type d -print | xargs chmod 755
-find cypht-1.4.x -type f -print | xargs chmod 644
-sudo chown -R root:root cypht-1.4.x
-
-# copy to destination folder
-sudo mv cypht-1.4.x/* $DESTINATION
-
-# remove working directory
-cd ..
-sudo rm -rf cypht-temp
-

3. Configure the program

-

To configure Cypht for your environment, you must first edit the hm3.ini file to your liking, - then - run the config_gen.php script to generate the optimized configuration file and assets used at run-time.

- -

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.

- -

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).

- - 
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/
-

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. -

-

4. Generate the run-time configuration

-

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:

- - 
cd /usr/local/share/cypht  (or wherever you put the code in section 1)
-sudo php ./scripts/config_gen.php
- -

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.

- - -

5. Enable the program in your web-server

-

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:

- - 
sudo ln -s /usr/local/share/cypht/site /var/www/html/mail
- -

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.

-

6. Users

-

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: - 

-            # 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
-
-

-

7. Debug mode

-

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:

- - 
sudo ln -s /usr/local/share/cypht /var/www/html/mail-debug
- -

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.

-

8. Other INI files

-

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. -

- -

2. Install cypht using Docker

-

- 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.
- Here is the cypht docker repository: https://hub.docker.com/r/sailfrog/cypht-docker
- 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: -

-
    -
  • Create a new directory on your system named as you want.
    • -
  • In the directory created previously, create a file named "docker-compose.yaml" then copy and paste the content of the example docker-compose section in the created file .
    • -
  • Open your CLI/terminal and move to the directory containing the docker-compose file and run the command - to run containers - 
    docker-compose up -d
    -
    • -
  • 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.
    • -
-

- NOTE: Please change usernames and passwords before using the given docker-compose code in your production - environment. -

- -

3. Install Cypht on a YunoHost server

-

This is an other easy way of installing and use Cypht.
- 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.
- To learn more about YunoHost, visit https://yunohost.org/en/whatsyunohost -

-

To install Cypht on YunoHost, please follow these steps:

-
    -
  • If you don't have an installed YunoHost server, please consult the guide to learn how to install it. If you have it, - please go directly to the next step.
    • -
  • If you just installed YunoHost or had it installed before, access your server and go to the admin - dashboard, then click on "Applications"
    • -
  • In the next page, click on the "install" button
    • -
  • In the search area, enter "cypht"
    • -
  • In the search result, click on cypht app
    • -
  • 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. -
    • -
  • Once clicked on the "install" button, wait for the installation to complete, it may take while.
    • -
  • Once the installation completed, you will be taking back to the dashboard.
    • -
  • 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.
    • -
  • 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.
    • -
-

4. Install Cypht within Tiki

-

If you have tiki installed, you can use Cypht within tiki. This is an easy way of installing Cypht.
- Please follow the following link for a complete guide of how to install and use cypht within Tiki.
- https://doc.tiki.org/Webmail -


-

Having problems?

- We are happy to help trouble-shoot any installation issues you run into. Chat with us at Gitter Cypht at Gitter and We'll get back to you as soon as we can. -
- - - - - - - - diff --git a/install-2x.html b/install-2x.html deleted file mode 100644 index 34ed063..0000000 --- a/install-2x.html +++ /dev/null @@ -1,429 +0,0 @@ - - - - - - - Install - - - - - - - -
- -
- -
-

Install Cypht v2.x

-

You can install specific versions of Cypht:

-

- - - - - - - - Cypht v2.x - -

-

Cypht has four differents installation ways:

-
    -
  • Manual installation
    • -
  • Installation within Tiki
    • -
  • install using Docker (use cypht docker image)
    • -
  • Install cypht on a YunoHost server
    • -
-

Please read the bellow explanations about each way and pick one of your choice.

-
-

1. Manual installation

- -

Requirements

-

Cypht 2.x requires at least PHP 8.1,Composer 2, and at minimum the OpenSSL, mbstring and cURL extensions. Cypht can also leverage several other - extensions as defined in composer.json. - Testing is done on Debian and Ubuntu - platforms with Nginx and Apache. -

-

Before proceeding please make sure your system meets minimal requirements

-

Steps

-

1. Check minimum requirements

-

- 

-#!/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
-

-

2. Download and prepare the code

-

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: - - -

- 
-#!/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
-
-
-

3. Configure the program

-

To configure Cypht for your environment, make adjustments to the .env file according to your preferences. - The .env file serves as the primary configuration file.

- -

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.

- -

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.

- -

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).

- - 
-          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/
-
-

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. -

-

4. Generate Dynamic Run-Time Configuration

-

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:

- - 
cd /usr/local/share/cypht  (or wherever you put the code in section 1)
-sudo php ./scripts/config_gen.php
- -

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.

- -

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.

- - -

5. Enable the program in your web-server

-

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:

- - 
sudo ln -s /usr/local/share/cypht/site /var/www/html/mail
- -

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.

-

6. Users

-

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: - 

-# 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
-
-

-

7. Debug mode

-

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:

- - 
sudo ln -s /usr/local/share/cypht /var/www/html/mail-debug
- -

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.

-

8. Other Configs files

-

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. -

- -

2. Install cypht using Docker

-

- 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.
- Here is the cypht docker repository: https://hub.docker.com/r/cypht/cypht
- 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: -

-
    -
  • Create a new directory on your system named as you want.
    • -
  • In the directory created previously, create a file named "docker-compose.yaml" then copy and paste the content of the example docker-compose file in the created file or just download the example docker-compose file in the previously created directory.
    • -
  • Open your CLI/terminal and move to the directory containing the docker-compose file and run the command to - run containers - 
    docker-compose up -d
    -
    • -
  • 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.
    • -
-

- NOTE: Please change usernames and passwords before using the given docker-compose code in your production - environment. -

- -

3. Install Cypht on a YunoHost server

-

This is an other easy way of installing and use Cypht.
- 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.
- To learn more about YunoHost, visit https://yunohost.org/en/overview/what_is_yunohost -

-

To install Cypht on YunoHost, please follow these steps:

-
    -
  • If you don't have an installed YunoHost server, please consult the - guide to learn how to install it. If you have it, please go directly to the next step.
    • -
  • If you just installed YunoHost or had it installed before, access your server and go to the admin dashboard, - then click on "Applications"
    • -
  • In the next page, click on the "install" button
    • -
  • In the search area, enter "cypht"
    • -
  • In the search result, click on cypht app
    • -
  • 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. -
    • -
  • Once clicked on the "install" button, wait for the installation to complete, it may take while.
    • -
  • Once the installation completed, you will be taking back to the dashboard.
    • -
  • 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.
    • -
  • 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.
    • -
-

4. Install Cypht within Tiki

-

If you have tiki installed, you can use Cypht within tiki. This is an easy way of installing Cypht.
- Please follow the following link for a complete guide of how to install and use cypht within Tiki.
- https://doc.tiki.org/Webmail -


- -

Having problems?

- We are happy to help trouble-shoot any installation issues you run into. Chat with us at Gitter Cypht at Gitter and We'll get back to you as soon as we can. -
- - - - - - - - diff --git a/install.html b/install.html deleted file mode 100644 index 50bfca7..0000000 --- a/install.html +++ /dev/null @@ -1,426 +0,0 @@ - - - - - - - Install - - - - - - - -
- -
- -
-

Install Cypht master

-

You can install specific versions of Cypht:

-

- - - - - - - - Cypht v2.x - -

-

Cypht has four differents installation ways:

-
    -
  • Manual installation
    • -
  • Installation within Tiki
    • -
  • install using Docker (use cypht docker image)
    • -
  • Install cypht on a YunoHost server
    • -
-

Please read the bellow explanations about each way and pick one of your choice.

-
-

1. Manual installation

-

Requirements

-

Cypht master requires at least PHP 8.1, Composer 2, and at minimum the - OpenSSL, mbstring and cURL extensions. Cypht can also leverage several other - extensions as defined in composer.json. - Testing is done on Debian and Ubuntu - platforms with Nginx and Apache. -

-

Before proceeding please make sure your system meets minimal requirements

-

Steps

-

1. Check minimum requirements

-

- 

-            #!/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
-
-

-

2. Download and prepare the code

-

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: - - -

- 
-#!/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/cypht-org/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/.env.example.ini cypht-master/.env
-
-# 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
-

3. Configure the program

-

To configure Cypht for your environment, make adjustments to the .env file according to your - preferences. The .env file serves as the primary configuration file.

- -

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.

- -

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.

- -

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).

- - 
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/
-

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. -

-

4. Generate the run-time configuration

-

Cypht uses a build process to create an optimized configuration, and to combine and minimize page assets. - Once - you have edited your .env file, generate the configuration with:

- - 
cd /usr/local/share/cypht  (or wherever you put the code in section 1)
-sudo php ./scripts/config_gen.php
- -

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.

- - -

5. Enable the program in your web-server

-

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:

- - 
sudo ln -s /usr/local/share/cypht/site /var/www/html/mail
- -

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.

-

6. Users

-

Setting up users depends on what type of authentication you configure in the .env file. If you are using the - local database configuration for users, there are scripts in the scripts/ directory to help manage them: - 

-# 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
-
-

-

7. Debug mode

-

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:

- - 
sudo ln -s /usr/local/share/cypht /var/www/html/mail-debug
- -

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.

-

8. Other Configs files

-

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. -

- - -

2. Install cypht using Docker

-

- 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.
- Here is the cypht docker repository: https://hub.docker.com/r/cypht/cypht
- 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: -

-
    -
  • Create a new directory on your system named as you want.
    • -
  • In the directory created previously, create a file named "docker-compose.yaml" then copy and paste the content of the example docker-compose file in the created file or just download the example docker-compose file in the previously created directory.
    • -
  • Open your CLI/terminal and move to the directory containing the docker-compose file and run the command - to run containers - 
    docker-compose up -d
    -
    • -
  • 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.
    • -
-

- NOTE: Please change usernames and passwords before using the given docker-compose code in your production - environment. -

- -

3. Install Cypht on a YunoHost server

-

This is an other easy way of installing and use Cypht.
- 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.
- To learn more about YunoHost, visit https://yunohost.org/en/whatsyunohost -

-

To install Cypht on YunoHost, please follow these steps:

-
    -
  • If you don't have an installed YunoHost server, please consult the guide to learn how to install it. If you have it, - please go directly to the next step.
    • -
  • If you just installed YunoHost or had it installed before, access your server and go to the admin - dashboard, then click on "Applications"
    • -
  • In the next page, click on the "install" button
    • -
  • In the search area, enter "cypht"
    • -
  • In the search result, click on cypht app
    • -
  • 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. -
    • -
  • Once clicked on the "install" button, wait for the installation to complete, it may take while.
    • -
  • Once the installation completed, you will be taking back to the dashboard.
    • -
  • 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.
    • -
  • 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.
    • -
-

4. Install Cypht within Tiki

-

If you have tiki installed, you can use Cypht within tiki. This is an easy way of installing Cypht.
- Please follow the following link for a complete guide of how to install and use cypht within Tiki.
- https://doc.tiki.org/Webmail -


-

Having problems?

- We are happy to help trouble-shoot any installation issues you run into. Chat with us at Gitter Cypht at Gitter and We'll get back to you as soon as we can. -
- - - - - - - - - diff --git a/layouts/page.html.twig b/layouts/page.html.twig new file mode 100644 index 0000000..1bdb736 --- /dev/null +++ b/layouts/page.html.twig @@ -0,0 +1,108 @@ + + + + + + + {{page.title}} + + + + + + + +
+ +
+ {% if page.nocontainer is defined %} + {{page.content}} + {% elseif page.path == 'config-generator' %} + {{- include('partials/config-generator.html.twig') ~}} + {% else %} +
+ {{page.content}} +
+ {% endif %} + + + + + + + {% if page.loadScriptAfter is defined %} + + {% endif %} + + + diff --git a/layouts/partials/config-generator.html.twig b/layouts/partials/config-generator.html.twig new file mode 100644 index 0000000..9e4ae14 --- /dev/null +++ b/layouts/partials/config-generator.html.twig @@ -0,0 +1,84 @@ + +
+

Cypht Config Generator

+
+ Click any of the options below to configure Cypht!
+ On the bottom of the page you can find a button to generate your .env +
+ {% for file in site.data.configFiles %} +
+ + {{file | replace({".php": ""})}} + + {% for option in site.data.configOptions[file] %} + {% set select = option.inputType == "select" %} + {% set inputId = option.key ~ "_CCGINPUT" %} +
+ +

{{option.key}}

+ + + {% if option.valueDefault %}

Default: {{option.valueDefault}}

{% endif %} + + {% if not select %} + + {% else %} + + {% endif %} + + + +
+ {% endfor %} +
+
+ {% endfor %} + +
+ + + +

+ Please note that neither allow_session_cache & cache_class are configurable + through here, + as it is not recommended and as such quite advanced usage. + Check + app.php (@github:cypht-org/cypht) + for more info +

+ + +
\ No newline at end of file diff --git a/license.html b/license.html deleted file mode 100644 index aa5e364..0000000 --- a/license.html +++ /dev/null @@ -1,174 +0,0 @@ - - - - - - License - - - - - - -
- -
- -
-

Cypht source code is distributed under the LGPL V2.1 license:

-

Go to the license

-

Cypht will always be both free and Open Source. Cypht uses a handful of third party libraries both indirectly - and directly. Compatible version of direct dependencies are always included in the Cypht source or installed via - PHP composer. -

-
-

Directly Used

- -

Indirectly Used

- -
- - - - - - - diff --git a/modules.html b/modules.html deleted file mode 100644 index a059d1d..0000000 --- a/modules.html +++ /dev/null @@ -1,362 +0,0 @@ - - - - - - Modules - - - - - - -
- -
- -
-

Overview

-

Cypht has a modular design. Instead of an application with a plugin API, Cypht is an application comprised - entirely of plugins, or as we call them, "module sets". There is only one required set, the "core" modules. The - components of any module set can be added to, or even replaced, by site specific modules. All the functionality - of Cypht is broken out into module sets, and each set is built from small pieces that are also easy to override. - The module system is powerful, but also a bit complex. First let's take a look at the module sets that come with - Cypht:

-
-
    -
  • 2faissues
    TOTP - based 2 factor authentication using the Google Authenticator mobile app -
    • -
  • accountissues
    UI - features for admins to create accounts, and for users to update passwords (when using the built-in DB - authentication). Functional, but could use more admin features -
    • -
  • - advanced_searchissues
    Support - for advanced search -
    • -
  • api_loginissues
    Login - using an API to provide single sign on ability -
    • -
  • calendarissues
    Basic - calendar. -
    • -
  • contactsissues
    Contact - management. Requires at least one contact backend module set to be enabled -
    • -
  • - carddav_contactsissues
    Support - for contacts stored in CardDav -
    • -
  • local_contactsissues
    Simple - locally stored contact support -
    • -
  • ldap_contactsissues
    Support - for contacts stored in LDAP -
    • -
  • gmail_contactsissues
    Read-only - support for Gmail contacts with an Oauth2 enabled Gmail account -
    • -
  • coreissues
    - Handles page layout, login/logout, and the default settings pages -
    • -
  • desktop_notificationsissues
    Desktop - notifications for new messages -
    • -
  • developerissues
    - For development, provides resources and installation details. Only available in "debug mode" -
    • -
  • dynamic_loginissues
    Allows - user to authenticate against a list of popular mail services, or to auto-discover the services for the - specified E-mail address -
    • -
  • feedsissues
    - RSS/ATOM feed support -
    • -
  • githubissues
    - Github repository tracking -
    • -
  • hello_worldissues
    - Example module set with lots of comments -
    • -
  • highlightsissues
    - Color highlighting for message lists -
    • -
  • historyissues
    - Simple list of messages read since login -
    • -
  • idle_timerissues
    - Controls idle time and automatic logout -
    • -
  • imapissues
    - IMAP E-mail account support -
    • -
  • imap_foldersissues
    - IMAP E-mail folder management support -
    • -
  • inline_messageissues
    - View messages inline in a reading pane instead of on a new page -
    • -
  • jmapissues
    - JMAP (JSON Meta Application Protocol) It uses a JSON-based structure to streamline communication and optimize performance. By reducing the number of network round-trips compared to traditional protocols like IMAP and SMTP, JMAP enhances responsiveness and reduces resource usage. With its real-time updates and simplified structure. It is designed to improve the user experience by providing faster, more reliable access to data, making it ideal for modern applications. -
    • -
  • - keyboard_shortcutsissues
    Adds - support for site navigation and actions using the keyboard -
    • -
  • nasaissues
    Access - the NASA APOD API content -
    • -
  • nuxissues
    - Friendly new user experience. Quickly add common E-mail services, and view development updates. Needs help - text added -
    • -
  • PGPissues
    - Encryption using Pretty Good Privacy -
    • -
  • profilesissues
    - Profiles to set reply-to, name, and signature to associated E-mail accounts -
    • -
  • recaptchaissues
    - Enable Recaptcha on the login form -
    • -
  • - recover_settingsissues
    - Ability to recover user settings after an external password change -
    • -
  • saved_searchesissues
    - Save and re-run searches easily -
    • -
  • sievefiltersissues
    - Message filtering -
    • -
  • siteissues
    - Site specific overrides. Used to control other module sets without hacking the code -
    • -
  • smtpissues
    - Send outbound E-mail using SMTP servers -
    • -
  • tagsissues
    - Allows users to organize content effectively by utilizing tags or labels. It is designed to enhance content management by enabling users to assign relevant tags, facilitating easy categorization, filtering, and retrieval of content. The tagging feature is fully implemented, allowing for seamless interaction where users can add, edit, or remove tags as needed. -
    • -
  • themesissues
    - Change the UI using CSS -
    • -
  • wordpressissues
    - WordPress.com notifications and freshly pressed lists -
    • -
-
-

Module sets are setup in the hm3.ini file. With the exception of the core module, they can all be enabled or - disabled independently (though module sets can rely on each other, like the nux module). When the site build - process is run, module assignments are calculated and saved in the configuration file (so they don't need to be - re-calculated at run-time). There is also a debug mode in which modules are activated dynamically (for the most - part) to make development easier.

-

File Structure

-

Module set names in the ini file match the directory the module code is in under modules/. Files in a module - have pre-defined names. Any other required code should be included from one of these files. -

-

-
    -
  • setup.php
    This is where a module set defines it's own modules and assigns them to request - identifiers. This file must return an array of valid input and associated types in order for the module code - to have access to it. -
    • -
  • modules.php
    This is where the actual module code lives. If you have external libraries to include - this is a good place to do so. -
    • -
  • site.js
    Optional file to include JavaScript for the module set.
    • -
  • site.css
    Optional file to include CSS for the module set.
    • -
-
-

A module set can also include an assets sub-directory. Anything in that directory will be made availble in the - browser. An example of this is the HTML WSIWYG editor for the smtp module set. In debug mode the module site.css - and site.js files are included directly if they exist. In production mode combined and optionally minified - versions are used consisting of a single js file and a single CSS file generated by the build process. Minifying - programs can be specified in the hm3.ini file. -

-

Input and Output

-

There are two kinds of modules: Input processing modules called "handler modules", and output formatting modules - called "output modules". Modules can pass data to each other, and output modules have access to all the data - input modules create. By default, module output is immutable and can't be stepped on by other modules. Data can - be marked writable and an "appendable" data type is also supported. The typical job of a handler module is to - analyze user input and do some work based on it, which it then sends to the output modules. The typical job of - an output module is to take the results of an input module and format it for the browser. -

-

Hello World

-

For more information, check out the "hello world" module set. It illustrates how modules work and has loads of - comments that explain what is going on:

-

- https://github.com/cypht-org/cypht/tree/master/modules/hello_world -

-
- - - - - - - diff --git a/pages/config-generator.md b/pages/config-generator.md new file mode 100644 index 0000000..4c43ba0 --- /dev/null +++ b/pages/config-generator.md @@ -0,0 +1,4 @@ +--- +title: Config generator +loadScriptAfter: /config-generator.js +--- diff --git a/pages/contribute.md b/pages/contribute.md new file mode 100644 index 0000000..4529486 --- /dev/null +++ b/pages/contribute.md @@ -0,0 +1,62 @@ +--- +title: Contribute +weight: 8 +nocontainer: true +--- +
+
+

Want to contribute?

+

First of all, thank you for interest to cypht! The goal of this page is to provide everything you need to know in order to contribute to cypht-website and its different integrations.

+ +

Development Workflow

+

The project, particularly version 1.4.x, has been designed with plain HTML and CSS, focusing on front-end and back-end development without the use of extra features or frameworks.

+

However, it's worth noting that in version 2.1.x, while there's no PHP back-end framework utilized for its back-end, Bootstrap is adopted as the front-end framework, enhancing the project's user interface and experience.

+

Requirements

+
    +
  1. You're familiar with GitHub and the + Pull Request (PR) workflow. +
    2. +
  2. You've read the Cypht documentation and the README. +
    3. +
  3. You know about the Cypht community. Please use this as help and check how to join the community. +
    4. +
+

Git Guidelines

+
    +
  1. Make sure that the contribution you want to make is explained or detailed in a GitHub issue! Find an + existing issue or + open a new one. +
    2. +
  2. Once done, + fork the cypht website repository to your own GitHub account. + You can request a maintainer to check your issue before making a PR. +
    3. +
  3. Create a new Git branch.
    4. +
  4. Review the Development Workflow section that describes the project's technology used. +
    5. +
  5. Implement the changes on your branch.
    6. +
  6. + Submit the branch as a PR pointing to the master branch of cypht-website repository. + A maintainer will comment and/or review your Pull Request. Depending on the circumstances, this process may take some time.
    +
    7. +
+

Have a question?

+

We love feedback so let us know what you think!
Leave a comment, submit your problem or contribute to + the project
by joining the community first. +

+ + + + + + + + + +
+
\ No newline at end of file diff --git a/pages/developers-documentation.md b/pages/developers-documentation.md new file mode 100644 index 0000000..ab4a109 --- /dev/null +++ b/pages/developers-documentation.md @@ -0,0 +1,869 @@ +--- +title: Devs-doc +weight: 7 +nocontainer: true +--- + + +
+
+

Folder structure

+

.github

+

This folder contains files used for CI/CD on GitHub, such as running tests during merge requests and + building Docker images. It streamlines collaboration, automates processes, and ensures consistency + across the repository. You'll also find templates for pull requests, issues, and bug reports. To edit + the default text in a merge request description, simply modify the relevant file in this folder.

+

.travis

+

Refer to https://docs.travis-ci.com/user/for-beginners/

+

Config

+

This was introduced with the support of .env files in Cypht

+

It contains all the contents of the .env file grouped by semantics within the files. Files in this folder + return an array. They simply take the values from the .env file and set a default value if it is not + defined in .env.

+

A special case is that the Dynamic.php file (not tracked by git) is automatically generated every time + you change something in the .env file. After compiling all other files in this folder, this is the + configuration file used by Cypht at runtime.

+

Related PR: Switching cypht config hm3.* to dotenv

+

https://github.com/cypht-org/cypht/pull/823/

+

language

+

Contain translation files

+

lib

+

Contain the core of Cypht

+

modules

+
    +
  • site.js: contains module-specific javascript code
    • +
  • site.css: contains module-specific CSS code
    • +
  • setup.php: These are management modules, output modules, pages, allowed post variables, allowed get + variables, allowed output variables, allowed cookies are set.
    • +
  • modules.php: This file contains handlers and output classes. Some modules with multiple handlers, + outputs and functions may use this file to simply include other files. Take a look at + modules/core/modules.php to get an idea.
    • +
  • Assets folder: some modules have assets (fonts, images, samples). Please see the core or local_contacts + modules.
    • +
+

Contains all modules. Each module contains the files below:

+

You will get a detailed explanation of how each module works in config/app.php.

+

scripts

+

Contains script files to generate configuration (done once after installation), create/delete/update user + accounts, generate necessary tables to manage users, sessions, or settings based on values in the + environment file and finally others script for development purpose.

+

site

+

The site folder contains production files generated by scripts/config_gen.php

+

tests

+

contains PHPUnit and selenium tests

+

third_party

+

Contains third party minified files used in Cypht

+

.env

+

The .env file is for high-level configuration. For any variables you're unsure about, check the + configuration folder for detailed explanations.

+

How to

+

See the new link in the left menu

+

Sometimes you can add a link to the left menu without seeing it. Cypht caches all menus. You need to + click on the reload link below the navigation menu.

+

Create a page

+

Cypht supports two types of pages: basic and AJAX. Basic pages are accessible via URL and require a page + reload, while AJAX pages load asynchronously.

+

To create a page called list_messages that displays all messages from the database, navigate to the + correct module (e.g., the nux module) and insert the following code just before the return array:

+

In nux/setup.php:

+ + setup_base_page('all_messages', 'core');
+ add_handler('all_messages', 'load_messages', true);
+ add_output('all_messages', 'print_messages', true); + +

- setup_base_page adds your new page to the routes, the first argument is the name of the page accessible + by typing /?page=all_messages in the browser in this case

+

- add_handler adds a handler to the page. A handler class contains logic, validates forms, binds alert + messages, and passes output variables for use in the output.

+

- add_output adds output to the page. An output class contains HTML that will be returned to the client by typing /?page=all_messages

+

Handler and Output Modules

+

In nux/modules.php:

+ + class Hm_Handler_load_messages extends Hm_Handler_Module {
+ public function process() {
+ // Do some logic here
+ // Get the list of messages
+ // Pass the list to the output
+ }
+ }

+ class Hm_Output_print_messages extends Hm_Output_Module {
+ protected function output() {
+ // Get the list of message passed by Hm_Handler_load_messages
+ // Build the html that will be returned
+ // Use return statement to return the html
+ }
+ } + +

Let's say you want to add an ajax page called ajax_load_new_messages which will receive new messages sent + to the user and update the message list every 15 seconds.

+

In nux/setup.php:

+ + setup_base_ajax_page('ajax_load_new_messages', 'core');
+ add_handler('ajax_load_new_messages', 'get_new_messages', true);
+ add_output('ajax_load_new_messages', 'print_new_messages', true); + +

In nux/modules.php:

+ + class Hm_Handler_get_new_messages extends Hm_Handler_Module {
+ public function process() {
+ // Do some logic here
+ // Get the list of new messages
+ // Pass the list to the output
+ }
+ }

+ class Hm_Output_print_new_messages extends Hm_Output_Module {
+ protected function output() {
+ // Get the list of messages passed by Hm_Handler_get_new_messages
+ // Build the HTML that will be returned
+ // Use the out to return data
+ $this->out('ajax_messages', $new_messages);
+ }
+ } + +

Add this code in nux/site.js to run your ajax page every 15 seconds: +

+ + $(function() {
+ if (hm_page_name() === 'all_messages') {
+ setInterval(function() {
+ Hm_Ajax.request(
+ [{'name': 'hm_ajax_hook', 'value': 'ajax_load_new_messages'}],
+ function(res) {
+ if (res.ajax_messages) {
+ // Append new messages to the list of messages
+ $('#messages_list').append(res.messages);
+ }
+ }
+ );
+ }, 15000);
+ }
+ }); + +

Note: If setup_base_ajax_page does not have output modules, the + values returned with $this->out() will be accessible in res in JavaScript.

+

Finally, add the following code to nux/setup.php:

+ + return array(
+ 'allowed_pages' => array(
+ ...
+ 'ajax_load_new_messages',
+ 'all_messages'
+ ),
+ 'allowed_get' => array(
+ ...
+ ),
+ 'allowed_output' => array(
+ ...
+ 'ajax_messages'
+ ),
+ 'allowed_post' => array(
+ ...
+ )
+ ); + +

Add all_messages and ajax_load_new_messages to the list of allowed pages.

+

Add ajax_messages to the list of allowed outputs.

+

Add post/get variables if they exist in the list of allowed get/posts.

+

Note: A page can have multiple handlers/outputs. A full list of all handlers and outputs attached to + a page can be seen by accessing ?page=info page on your instance in + the configuration map section.

+

Add third party

+

Copy the minified file to the third-party directory

+

Add the file path in Hm_Output_page_js~np~::~/np~output or Hm_Output_header_css~np~::~/np~output if it is + a CSS file.

+

Finally, add the file in the combine_includes function in scripts/config_gen.php so that it is added when + generating the production site.

+

Enable a module

+

Edit .env file and add your module to CYPHT_MODULES variable

+

Create a module

+

In the modules folder, you'll find a hello_world module with the necessary scaffolding for creating a + new module. Customize your module by following the code explained above.

+

Translate string

+

If you need to translate a string in:

+

Handler module:

+

Most strings in handlers are only intended to alert the user of success/information/failure operations. + And so they are all written without a translation method but they are all translated later in the + Hm_Output_msgs::output function.

+

Output module:

+ + $this->trans("Your text here"); + +

JS file:

+ + hm_trans("Your text here", "en"); + +

The second parameter here is optional because the default language is the user's language in the settings + page.

+

Add new translation string

+

Add your string to each file contained in the language folder.

+

The file names in this folder are language codes. And all return an array. Just add your new string to + the end of the array. If you know the translation of the text in a language, add it as a value, + otherwise add false as a value.

+

Add new language

+

Duplicate the en.php file into the language folder

+

Rename it (Cypht uses 2 digit code, please refer to https://en.wikipedia.org/wiki/List_of_ISO_639_lingual_codes)

+

In the renamed file, modify interface_lang and interface_direction in the array accordingly.

+

Add your language in the interface_langs() function.

+

Update this test to add your language: Hm_Test_Core_Output_Modules::test_lingual_setting

+

Run test

+

Cypht has PHPUnit tests and selenium

+

PHPUnit

+

To run all tests:

+ + php vendor/phpunit/phpunit/phpunit --configuration tests/phpunit/phpunit.xml + +

To run tests contained in a class or a single test method:

+

To run tests contained in a class or a single test method:

+ + php vendor/phpunit/phpunit/phpunit --configuration tests/phpunit/phpunit.xml --filter classOrMethodName + +

To run Selenium tests, make sure you have Python installed (https://www.python.org/downloads/). Once Python is + installed, you should be able to run the following command:

+ + pip install -r requirements.txt + +

This command will install all required packages. The + requirements.txt file is located at tests/selenium, so make sure to specify the correct path in the + command line, or navigate to that location.

+

Once all packages are installed, you can run Selenium tests + using this command:

+ + sh runall.sh + +

Fix PHPUnit failing tests

+

Run all tests or filter specific ones, and the console will show the results. In VSCode or similar, click + on the file path to go directly to the line causing the issue. Check recent changes to classes, divs, or + logic in the handlers that may be causing the failure.

+ + There was 1 failure: + 1) Hm_Test_Uid_Cache::test_uid_is_read + Failed asserting that true is false. + /Applications/MAMP/htdocs/cypht/tests/phpunit/cache.php:19 + +

Debug AJAX requests

+

Cypht relies heavily on AJAX requests. To debug, add var_dump and exit in your code. Open your browser's + developer tools, go to the Network tab, filter by Fetch/XHR to see AJAX requests, then run the code. + Click on the request you want to inspect and view the preview or response.

+

The core module

+

The core module handles:

+

- Rendering CSS headers

+

- Displaying alert messages

+

- Loading JS files and defining shared JS functions

+

- Configuring basic features like backups, server pages, settings, etc.

+

Practical Example: 1. Add a test page

+

As mentioned earlier, we use the setup_base_page function to add a new page. We'll call this function to + make our test page available:

+

In core/setup.php:

+ + setup_base_page('test'); + +

My Cypht project is available locally at cypht.test. Once we have added this page, we should be able to + access cypht.test as follows: cypht.test?page=test

+ +

You might find it strange that we see "Page Not Found!" 😔, but understand that this is completely normal + because we have explained the concept of authorizing pages, forms, etc.

+

In core/setup.php:

+ + /* allowed input */
+ return array(
+ 'allowed_pages' => array(
+ ...
+ 'test'
+ ),
+ 'allowed_output' => array(
+ ...
+ ),
+ 'allowed_cookie' => array(
+ ...
+ ),
+ 'allowed_server' => array(
+ ...
+ ),
+ 'allowed_get' => array(
+ ...
+ ),
+ 'allowed_post' => array(
+ ...
+ )
+ ); + +

After authorizing our page, we can now see a blank page. At least we are getting a result, even if it's + not yet what we expected 😁.

+ +

As mentioned earlier, the concepts of output and handle are important. At this stage, we define outputs + to display the content of our pages. To show content to the user, create outputs containing HTML.

+

In core/setup.php:

+ + add_output('test', 'test_heading', true, 'core', 'content_section_start', 'after'); + +

The first parameter refers to the page that we defined above: test. The second parameter refers to the + class (module) that we need to define in core/modules.php with the name Hm_Output_test_heading (In the + definition of the output in setup.php, we are not going to include Hm_Output_ because it is a prefix + that will be detected automatically). The third parameter allows you to indicate whether this content + will be displayed based on the user's authentication status. The fourth parameter indicates the module + that contains the module (output) code. The fifth parameter indicates the position on our page where + this content will be displayed, and the sixth parameter, which goes with the fifth, determines whether + this content will be before or after the fifth parameter.

+

Here is Hm_Output_content_section_start, the content after which we want to display our header.

+

In core/output_modules.php:

+ + class Hm_Output_content_section_start extends Hm_Output_Module {
+ /**
+ * Opens a main tag for the primary content section
+ */
+ protected function output() {
+ return '.$this->trans('Offline').' + }
+ +

In our case, we want to place our html content before closing:

+

In core/output_modules.php: +

+ + <div class="row m-0 position-relative">
+ <main class="container-fluid content_cell"> + +

Here is the definition of the module: test_heading which will display the title Test in the header

+

In core/output_modules.php: +

+ + class Hm_Output_test_heading extends Hm_Output_Module {
+ /**
+ */
+ protected function output() {
+ return '<div class="content_title">'.$this->trans('Test').'</div>';
+ }
+ } + +

And here is the result we get; we start to see the result that we are looking for 👌.

+ +

Now that we know how to add content, let's add another section after the header.

+

Define the output in core/setup.php to display it right after the header. You should already know what + the penultimate and last parameters will be.

+

In core/setup.php:

+ + add_output('test', 'test_first_div', true, 'core', 'test_heading', 'after'); + +

Let's define our class(module): test_first_div

+

In core/output_modules.php: +

+ + class Hm_Output_test_first_div extends Hm_Output_Module {
+ protected function output() {
+ return '<div class="mt-3 col-lg-6 col-md-12 col-sm-12"> + <div class="card"> + <div class="card-body"> + <div class="card_title"> + <h4>'.$this->trans('Test').'</h4> + </div> + '.$this->trans('We are just testing').' + </div> + </div> + </div>'; + }
+ } + +

And here is the result we hope for:

+ +

Let's add another element to our page just after our second + element:

+

In core/setup.php:

+ + add_output('test', 'test_second_div', true, 'core', 'test_first_div', 'after'); + +

In core/output_modules.php: +

+ + class Hm_Output_test_second_div extends Hm_Output_Module {
+ protected function output() {
+ return '<div class="mt-3 col-lg-6 col-md-12 col-sm-12">'.
+ '<div class="card">'.
+ '<div class="card-body">'.
+ '<div class="card_title">'.
+ '<h4>'.$this->trans('Test again').'</h4></div>'.
+ $this->trans('We are again just testing').' '.
+ '</div>'.
+ '</div>'.
+ '</div>';
+ }
+ } + +

And here is the result:

+ +

Now that we know how to add content, let's add a form element to + the page. We'll submit the form and handle its processing in the backend

+

In core/setup.php:

+ + add_output('test', 'test_third_div', true, 'core', 'test_second_div', 'after'); + +

In core/output_modules.php: +

+ + class Hm_Output_test_third_div extends Hm_Output_Module { + protected function output() { + return '<div class="nux_help mt-3 col-lg-12 col-md-12 col-sm-12">' + + '<div class="card">' + + '<div class="card-body">' + + '<div class="card_title"><h4>' + + $this->trans('Test Our Form') + '</h4></div>' + + '<form class="add_server me-0" method="POST" action="?page=test">' + + '<input type="hidden" name="hm_page_key" value="' + + $this->html_safe(Hm_Request_Key::generate()) + '" />' + + '<div class="subtitle mt-4">Tag name</div>' + + '<div class="form-floating mb-3">' + + '<input required type="text" id="new_tag_name" name="new_tag_name" class="txt_fld' + 'form-control" value="" placeholder="' + $this->trans('Tag name') + '" />' + + '<label class="" for="new_tag_name">' + + $this->trans('Tag name') + '</label>' + + '</div>' + + '<input type="submit" class="btn btn-primary px-5" value="' + + $this->trans('Add') + '" name="submit_tag" />' + + '</form>' + + '</div>' + + '</div>' + + '</div>'; + } + } + +

Here is the result:

+ +

We learned that add_output allows us to add HTML content to the page, while add_handler is used for + backend processing (like a controller). Both accept similar parameters, with the concepts of 'before' + and 'after' applying to handlers instead of outputs. Remember that these refer to other handlers, and + the class will extend Hm_Handler_Module

+

In core/setup.php:

+ + add_handler('test', 'process_test_third_div', true, 'core', 'load_user_data', 'after'); + +

Don't forget to authorize the form field in 'allowed_post'; otherwise, you won't be able to access it. +

+

In core/setup.php:

+ + /* allowed input */
+ return array(
+ 'allowed_pages' => array(
+ '...',
+ 'test'
+ ),
+ 'allowed_output' => array(
+ '...',
+ ),
+ 'allowed_cookie' => array(
+ '...',
+ ),
+ 'allowed_server' => array(
+ '...',
+ ),
+ 'allowed_get' => array(
+ '...',
+ ),
+ 'allowed_post' => array(
+ '...',
+ 'new_tag_name' => FILTER_DEFAULT
+ )
+ ); + +

We can now define our handler:

+

In core/handler_modules.php:

+ + class Hm_Handler_process_test_third_div extends Hm_Handler_Module {
+ /**
+ * If "stay logged in" is checked, set the session lifetime
+ */
+ public function process() {
+ list($success, $form) = $this->process_form(array('new_tag_name'));
+ if ($success && $form['new_tag_name']) {
+ // var_dump($form);die();
+ }
+ }
+ } + +

In this documentation, we've discussed how to pass data from POST to GET. Let's consider a scenario where + we want to display the entered data as the label for a field in our form. This involves using sessions + in Cypht:

+

In core/handler_modules.php:

+ + $this->session->set('key', 'value'); + +

Our code will look like this:

+

In core/handler_modules.php:

+ + class Hm_Handler_process_test_third_div extends Hm_Handler_Module {
+ /**
+ * If "stay logged in" is checked, set the session lifetime
+ */
+ public function process() {
+ list($success, $form) = $this->process_form(array('new_tag_name'));
+ if ($success && $form['new_tag_name']) {
+ $this->session->set('tag_name', $form['new_tag_name']);
+ }
+ }
+ } + +

Remember: to retrieve our stored data, we need another handler, and it must be placed after the handlers + that store the data; otherwise, it may cause malfunctions.

+

In core/setup.php:

+ + add_handler('test', 'get_test_third_div', true, 'core', 'load_user_data', 'after'); + +

To retrieve an element from the session, we will do it like this:

+ + $res = $this->session->get('key', 'Default Value'); + +

Let's also define the module in handler_modules.php

+

In core/handler_modules.php:

+ + class Hm_Handler_get_test_third_div extends Hm_Handler_Module {
+ /**
+ * If "stay logged in" is checked, set the session lifetime
+ */
+ public function process() {
+ $res = $this->session->get('tag_name', 'Tag name');
+ if(!is_null($res)) {
+ $this->out('tag_name', $res);
+ // we can now delete session as we do not need no more
+ $this->session->del('tag_name');
+ }
+ }
+ } + +

This is how you can delete an element from the session

+ + $this->session->del('key'); + +

In the Hm_Handler_get_test_third_div module, we will never encounter a null value because we provided a + default. Therefore, the is_null condition is unnecessary. We use $this->out('tag_name', $res); to pass + our data to the output. To retrieve it from the output, we will do it like this:

+ + $this->get('key'); + +

We will have to edit our class Hm_Output_test_third_div like this:

+

In core/output_modules.php: +

+ + class Hm_Output_test_third_div extends Hm_Output_Module {
+ protected function output() {
+ $tag_name = $this->get('tag_name');
+ return '<div class="nux_help mt-3 col-lg-12 col-md-12 col-sm-12">'.
+ '<div class="card">'.
+ '<div class="card-body">'.
+ '<div class="card_title"><h4>'.$this->trans('Test Our Form').'</h4></div>'.
+ '<form class="add_server me-0" method="POST" action="?page=test">'.
+ '<input type="hidden" name="hm_page_key" value="'.$this->'.
+ 'html_safe(Hm_Request_Key::generate()).'" />'.
+ '<div class="subtitle mt-4">'.$tag_name.'</div>'.
+ '<div class="form-floating mb-3">'.
+ '<input required type="text" id="new_tag_name" name="new_tag_name".
+ 'class="txt_fld form-control" value="" placeholder="'.$this->'.
+ 'trans('Tag name').'" />'.
+ '<label class="" for="new_tag_name">'.$tag_name.'</label>'.
+ '</div>'.
+ '<input type="submit" class="btn btn-primary px-5" value="'.$this->.
+ trans('Add').'" name="submit_tag" />'.
+ '</form>'.
+ '</div>'.
+ '</div>'.
+ '</div>';
+ }
+ } + +

Result before:

+ +

Result after:

+ +

Practical Example: 2. How to add new settings

+

Let's start by adding a simple parameter and then we'll see how to add another section after.

+

We will add our setting after this content:

+

On page settings

+ + Default message sort order + + +

We will need a handle and an output for that:

+

In core/setup.php:

+ + add_handler('settings', 'process_test_enable_tag_with_parent', true, 'tags', 'save_user_settings', 'before');
+ add_output('settings', 'test_enable_tag_with_parent_setting', true, 'tags', 'default_sort_order_setting', 'after'); + +

default_sort_order_setting is the output for 'Default message sort order.' When adding an output, we need + to specify its position. In this case, we want to place it after default_sort_order_setting. The + process_test_enable_tag_with_parent_setting must come before save_user_settings since we need to save it + as well. Thus, our configuration process will be applied and saved before handling save_user_settings. +

+

Now that we’ve defined our routes, we need to write the module for processing: + process_test_enable_tag_with_parent_setting for the handle and test_enable_tag_with_parent_setting for + the output.

+

In module.php:

+ + /**
+ * @subpackage tags/handler
+ */
+ class Hm_Handler_process_test_enable_tag_with_parent_setting extends Hm_Handler_Module {
+ public function process() {
+ function test_tag_with_parent_enabled_callback($val) { return $val; }
+ process_site_setting('test_enable_tag_with_parent', $this, 'test_tag_with_parent_enabled_callback', true, true);
+ }
+ } + +

and this is the corresponding output:

+

In module.php:

+ + /**
+ * @subpackage tags/output
+ */
+ class Hm_Output_test_enable_tag_with_parent_setting extends Hm_Output_Module {
+ protected function output() {
+ $settings = $this->get('user_settings');
+ if (array_key_exists('test_enable_tag_with_parent', $settings) && $settings['test_enable_tag_with_parent']) {
+ $checked = ' checked="checked"';
+ $reset = '';
+ }
+ else {
+ $checked = '';
+ $reset = '';
+ }
+ return '<tr class="general_setting"><td><label class="form-check-label" for="test_enable_tag_with_parent">'.
+ $this->trans('Test Tag enable parent').''.
+ '<td><input class="form-check-input" type="checkbox" '.$checked.
+ ' value="1" id="test_enable_tag_with_parent" name="test_enable_tag_with_parent" />'.$reset.'
+ }
+ } + +

reset_default_value_checkbox class here is being used + in js (module core site.js) to restore the default value at line:

+

In core/site.js:

+ + $('.reset_default_value_checkbox').on("click", reset_default_value_checkbox); + +

Remember, if you make changes, you need to define the restore action in JavaScript, as this can occur in + various scenarios.

+

You can now refresh your page to see the result:

+ +

You might be wondering why updating our parameter gives an unexpected result; this is normal. Let me + explain: remember the crucial concepts in Cypht related to authorizations and validations (such as + allowed_pages, allowed_output, allowed_post, etc.). In this case, we need to authorize our + test_enable_tag_with_parent field in POST.

+

In core/setup.php:

+ + 'allowed_post' => array(
+ 'test_enable_tag_with_parent' => FILTER_VALIDATE_INT
+ ) + +

By adding this permission, the display will remain unchanged, but the update will work as intended. To + access this setting in Cypht, use the usual syntax:

+

In core/setup.php:

+ + $this->user_config->get('test_enable_tag_with_parent_setting') + +

Now that we know how to add a simple setting, let's explore how to add a section to the settings page: +

+ +

The goal is to add a new section to our settings page. Here’s how:

+ +

In the image above, our section contains two elements, so we will define two handles to process them, + along with three outputs: one for the section title, one for the first element, and another for the + second element.

+

In tags/setup.php:

+ + add_handler('settings', 'process_tag_source_max_setting', true, 'tags', 'load_user_data', 'after');
+ add_handler('settings', 'process_tag_since_setting', true, 'tags', 'load_user_data', 'after');
+ add_output('settings', 'start_tag_settings', true, 'tags', 'sent_source_max_setting', 'after');
+ add_output('settings', 'tag_since_setting', true, 'tags', 'start_tag_settings', 'after');
+ add_output('settings', 'tag_per_source_setting', true, 'tags', 'tag_since_setting', 'after'); + +

We can now add modules, let's start with process_tag_source_max_setting:

+

In tags/modules.php:

+ + /**
+ * Process "tag_per_source" setting for the tag page in the settings page
+ * @subpackage core/handler
+ */
+ class Hm_Handler_process_tag_source_max_setting extends Hm_Handler_Module {
+ /**
+ * Allowed values are greater than zero and less than MAX_PER_SOURCE
+ */
+ public function process() {
+ process_site_setting('tag_per_source', $this, 'max_source_setting_callback', DEFAULT_PER_SOURCE);
+ }
+ } + +

and for process_tag_since_setting:

+

In tags/modules.php:

+ + /**
+ * Process "since" setting for the junk page in the settings page
+ * @subpackage core/handler
+ */
+ class Hm_Handler_process_tag_since_setting extends Hm_Handler_Module {
+ /**
+ * valid values are defined in the process_since_argument function
+ */
+ public function process() {
+ process_site_setting('tag_since', $this, 'since_setting_callback');
+ }
+ } + +

That's all for our handles, we need to add output modules too; let's start with "start_tag_settings":

+

In tags/modules.php:

+ + /**
+ * Starts the Tag section on the settings page
+ * @subpackage core/output
+ */
+ class Hm_Output_start_tag_settings extends Hm_Output_Module {
+ /**
+ * Settings in this section control the tag messages view
+ */
+ protected function output() {
+ $res = ''.
+ ''.
+ $this->trans('Tags').'';
+ print_r($res);
+ return $res;
+ }
+ } + +

for "tag_since_setting" add:

+

In tags/modules.php:

+ + /**
+ * Option for the "junk since" date range for the Junk page
+ * @subpackage core/output
+ */
+ class Hm_Output_tag_since_setting extends Hm_Output_Module {
+ /**
+ * Processed by Hm_Handler_process_tag_since_setting
+ */
+ protected function output() {
+ $since = DEFAULT_SINCE;
+ $settings = $this->get('user_settings', array());
+ if (array_key_exists('tag_since', $settings) && $settings['tag_since']) {
+ $since = $settings['tag_since'];
+ }
+ return '
+ $this->trans('Show junk messages since').''.
+ ''.message_since_dropdown($since, 'tag_since', $this).'';
+ }
+ } + +

and for "tag_per_source_setting" add:

+

In tags/modules.php:

+ + /**
+ * Option for the maximum number of messages per source for the Junk page
+ * @subpackage core/output
+ */
+ class Hm_Output_tag_per_source_setting extends Hm_Output_Module {
+ /**
+ * Processed by Hm_Handler_process_tag_source_max_setting
+ */
+ protected function output() {
+ $sources = DEFAULT_PER_SOURCE;
+ $settings = $this->get('user_settings', array());
+ $reset = '';
+ if (array_key_exists('tag_per_source', $settings)) {
+ $sources = $settings['tag_per_source'];
+ }
+ if ($sources != 20) {
+ $reset = '';
+ }
+ return '<tr class="tag_setting"><td><label for="tag_per_source">'.
+ $this->trans('Max messages per source').'</label></td>'.
+ '<td class="d-flex"><input type="text" size="2" class="form-control form-control-sm w-auto" + id="tag_per_source" name="tag_per_source" value="'.$this->html_safe($sources).'" />'.$reset.'</td></tr>';
+ }
+ } + +

And there you have it! Refresh your page to see the result:

+ +
+

+

Related links:

+ https://github.com/dovecot/imaptest/wiki/About
+ https://jmap.io/spec.html
+ http://sieve.info/
+ https://p5r.uk/blog/2011/sieve-tutorial.html
+ https://www.fastmail.com/help/technical/sieve.html
+ https://docs.gandi.net/en/gandimail/sieve/sieve_tutorial.html +
+ + + \ No newline at end of file diff --git a/documentation.html b/pages/documentation.md similarity index 57% rename from documentation.html rename to pages/documentation.md index 92045a2..8446b8c 100644 --- a/documentation.html +++ b/pages/documentation.md @@ -1,76 +1,14 @@ - - - - - - Documentation - - - - - - -
- -
+--- +title: "Documentation" +weight: 6 +nocontainer: true +---
- login + login

Welcome to Cypht

@@ -84,12 +22,11 @@

Welcome to Cypht

-

After successfully logging in the webmail, the users will be redirected to the following home page of the webmail where the interactive interface allows user to perform multiple actions,

- login + login
@@ -98,7 +35,7 @@

Welcome to Cypht

- add + add

The users can Add an E-mail Account of any service provider to be able to access multiple inboxes from Cypht.

@@ -108,20 +45,18 @@

Welcome to Cypht

-

Adding Servers and ATOM/RSS Feed

Enhanced customization capabilities allow user to setup, configure, and manage IMAP and SMTP or SMTP and JMAP servers and setup the ATOM/RSS Feed. Adding servers in Cypht is a straightforward process that involves two main steps. These steps are illustrated in the following image for your reference.

- login + login
-

Combined Inbox

The advanced and most efficient service of the Cypht enables users to access multiple email accounts at the same time. @@ -129,16 +64,15 @@

Combined Inbox

Also, the webmail allows provides the functionality to search, sort, and filter emails.

- login + login
-
- Contact + Contact

Contact Book

@@ -154,30 +88,28 @@

Contact Book

Or simply by clicking on the “one-person” icon in the message you receive.

- Add a contact + Add a contact
-

Calendar

The calendar feature allows user to create different events by clicking the “+” icon on top-right corner. The created reminders and events will be shown in the calendar making it easier for user to keep track of the special events.

- Calendar + Calendar
-
- Compose + Compose

Compose Email

@@ -195,7 +127,7 @@

User Profiles

From webmail settings options, the user can access the feature to add numerous profiles in the webmail allowing users to combine IMAP accounts with SMTP accounts and setup signatures and reply-to details.

- profile + profile
@@ -203,7 +135,7 @@

User Profiles

- developer + developer

Developer Options

@@ -220,14 +152,13 @@

Sieve filters

Sieve filters can be set up to automatically move, copy, or delete messages based on specific criteria such as sender, subject, keywords, or recipient. To add a Sieve filter, navigate to the Sieve Filters menu located in the Settings tab sidebar, select the email account for which you want to create a filter, and click the "Add Filter" button. Refer to the following image for a visual guide.

- Sieve filters + Sieve filters
-

Block List

@@ -235,7 +166,7 @@

Block List

- Block List + Block List
@@ -243,7 +174,7 @@

Block List

- snooze + snooze

Snooze

@@ -256,56 +187,13 @@

Snooze

-

Archive

To archive emails in Cypht, you'll need to create an archive folder. The 'Archive' button is always available, but you won't be able to use it until you've set up a destination folder. Once you've done that, clicking 'Archive' will move the email to the designated folder and display a confirmation message.

- Sieve filters -
-
-
- - - - - - - diff --git a/pages/email-filters.md b/pages/email-filters.md new file mode 100644 index 0000000..907b4f6 --- /dev/null +++ b/pages/email-filters.md @@ -0,0 +1,119 @@ +--- +title: Email filters +exclude: true +--- +

Email filters

+

Cypht now supports Sieve, a powerful email filtering language that gives you complete control over your inbox. With + Sieve, you can create complex filters to sort, move, delete, and flag your emails automatically. You can also use + Sieve to create custom notifications and alerts.

+

One key feature of Sieve is that filters run server-side, so they work even when you are not currently logged in. + However, it is important to note that your email server must support Sieve for these filters to function properly.

+

Here are just a few of the things you can do with Sieve:

+
+
    +
  • + Filter out spam and unwanted emails. Sieve filters can be used to filter out spam and unwanted emails based on + their sender, subject, or content. +
    • +
    +
  • + Organize your inbox automatically. Sieve filters can be used to automatically move or copy your emails into + different folders based on their sender, subject, or content. +
    • +
    +
  • + Forward important emails to specific people. Sieve filters can be used to automatically forward important emails + to specific people, such as your manager or your assistant. +
    • +
    +
  • + Sieve filters can be used to create custom notifications and alerts for important emails, such as those from + your boss or clients. Unlike simply forwarding the email, these notifications and alerts can provide immediate + and specific information, ensuring you stay updated without needing to sift through your inbox. +
    • +
    +
+

To get started with Sieve in Cypht, simply go to your config file (hm3.ini for Cypht 1.4.x or .env for Cypht 2.0.x) + and enable the Sieve filter engine by enabling modules[ ]=sievefilters or by adding sievefilters on CYPHT_MODULES + variable like:

+
modules[]=sievefilters #For Cypht 1.4.x
+CYPHT_MODULES="sievefilters" #For Cypht 2.0.x
+Once you have enabled the Sieve filter engine, you can create and manage your filters in the Filters section of the +Cypht interface. You can create new filters, edit existing filters, and delete filters as needed. +

How to create a Sieve filter in Cypht?

+

+ To create a Sieve filter in Cypht follow these steps: +

+ +
    +
  • + Go to Settings tab in the sidebar.
    Then click on Filters tab, select the E-mail account you + want for filters and click on the "Add Filter" button. +
    • +
  • + In the "Filter name" field, enter a name for your new filter. Then, provide other details of the filter:
    +
      +
    • Priority: It defines an order value (or priority value) for your filter. Note that filters will + run from the lowest to the highest priority value.
      • +
    • Test: This will help to combine two or more conditions.
      • +
    +
    • +
  • + In the "Conditions section",
    + you can add one or many conditions to your filter. You can add conditions based on the sender, subject, body, + etc. Check out the documentation page for other information. +
    • +
+

+ And there you go: 😄Enjoy filters with Cypht. +

+

Creating custom notifications and alerts: +

+

You can also use Sieve to create custom notifications and alerts for important emails. For example, you could create + a filter that sends you a notification every time you receive an email from your boss. + To create a custom notification or alert in Cypht, simply go to your settings and click on the "Filters" tab. Then, + select the E-mail account you want for filters and click on the "Add Script" button. + In the "Filter name" field, enter a name for your new filter. In the "Filter script" field, enter your Sieve code. + In addition to the Sieve code for filtering emails, you will also need to add the following code to your filter + script: +

+
require ["fileinto", "imap4flags", "notify"];
+
+# Set variables
+set "boss_email" "boss@example.com";
+
+# Rule to match emails from your boss
+if address :is "from" "${boss_email}" {
+    # Notify you of the new email
+    notify :message "You have a new email from your boss!" :options ["Important"] :method "mailto:your-email@example.com";
+}
+

Some examples of Sieve filters: +

+

The following are some examples of Sieve filters that you can use in Cypht:

+
+# Filter out spam and unwanted emails
+require ["fileinto"];
+
+# Move all emails from the sender "spam@example.com" to the "Spam" folder
+if address :from "spam@example.com" {
+    fileinto "Spam";
+}
+
+
+# Organize your inbox automatically
+require ["fileinto"];
+# Move all emails from the sender "john.doe@example.com" to the "Work" folder
+if address :from "john.doe@example.com" {
+    fileinto "Work";
+}
+# Move all emails with the subject "Important" to the "Important" folder
+if header :subject "Important" {
+  fileinto "Important";
+}
+
+

Related links:

+http://sieve.info/
+https://p5r.uk/blog/2011/sieve-tutorial.html
+https://www.fastmail.com/help/technical/sieve.html
+https://docs.gandi.net/en/gandimail/sieve/sieve_tutorial.html +
\ No newline at end of file diff --git a/pages/features.md b/pages/features.md new file mode 100644 index 0000000..a40a86d --- /dev/null +++ b/pages/features.md @@ -0,0 +1,145 @@ +--- +title: Features +weight: 2 +--- +

List of Features

+
+
    +
  • + Combined inbox, unread, sent, and flagged message views for all your E-mail accounts (and + RSS feeds), as well as standard E-mail client folder navigation +
    • +
    +
  • + Flexible profiles to combine IMAP accounts with SMTP accounts and setup signatures and + reply-to details +
    • +
    +
  • + Search all your E-mail accounts and RSS feeds at once with a simple form., or do complex searches across + your accounts with the advanced search module set +
    • +
    +
  • + Move or copy emails from one account to another +
    • +
    +
  • + Compose messages in plain text, HTML, or Markdown +
    • +
    +
  • + Pages are comprised of only 3 HTTP requests totaling ~50KB (gzipped). Data to + populate a page from different sources is collected with parallel AJAX + requests. Output is validated HTML5 and local storage (session only) is used to + cache content for speedier reloads. All the little interface icons use + data-urls so they are served inline (and they can all be disabled). With + standard browser caching, pages tend to transfer 10 to 20 KB +
    • +
    +
  • + Simple interface translation system that does not use gettext or .po files, just + arrays of translated strings defined in PHP. Right to left languages are supported. +
    • +
    +
  • + Module sets for IMAP, SMTP, LDAP or local contacts, WordPress, Github, + and lots more! Check out the Modules page for a + complete list +
    • +
    +
  • + Sessions and user data can be stored in any PDO compatible database or flat + files on the server +
    • +
    +
  • + Authentication is flexible and currently supports IMAP, LDAP, an included + database schema, dynamic authentication using popular E-mail providers, + auto-discovery based on the user's E-mail domain, or you can roll your own with + the site module set +
    • +
    +
  • + Sessions and Authentication can be customized without breaking any modules using + the site module set +
    • +
    +
  • + On the server, page request processing peaks at around 4-5MB of memory. The module system only includes PHP + files required to process the + current request, so time is not wasted parsing unused code paths +
    • +
    +
  • + All the work of processing a request and providing a response is done with + module sets. The application framework manages module assignment and provides a + controlled execution environment, but modules are where the actual work is done +
    • +
    +
  • + There is a build process that pre-calculates module assignments and combines + and compresses page assets, making the production version of your site as fast + as possible. There is also a developer mode in which individual components are + included directly for easy debugging and module development +
    • +
    +
  • + The HTML5 Page structure is semantic and simple, with attention paid to + accessibility best-practices +
    • +
    +
  • + Save the parameters of a search so that you can quickly access them later from + the menu without having to enter them again. This is particularly useful for parameters of + searches that are used frequently. Saved search parameters can also be deleted later. +
    • +
  • + Sieve filters can be created to automatically move, copy, or delete messages based on specific criteria such as sender, subject, keywords, or recipient. This allows for efficient organization and management of incoming emails, saving time and improving productivity. Sieve filters can be easily edited or deleted as needed. For more information on how to create and manage Sieve filters, see Email filters. +
    • +
    +
  • + JMAP (JSON Meta Application Protocol) support for faster, more efficient synchronization of emails across devices. +
    • +
    +
  • + Snooze feature to temporarily hide emails and bring them back at a more convenient time. +
    • +
    +
  • + Screen emails to help manage unwanted or irrelevant communications by filtering or prioritizing certain types of messages. +
    • +
    +
  • + IMAP capabilities for sharing folders to allow collaboration by sharing email folders between accounts. +
    • +
    +
  • + Delivery receipt to get confirmation when your emails are delivered to the recipient's inbox. +
    • +
    +
  • + Support for setting and managing environment variables to customize server-side configurations. +
    • +
    +
  • + IMAP folder subscriptions for managing which folders you want to subscribe to and view in your mail client. +
    • +
    +
  • + Collected Recipients and Trusted Senders feature to track commonly contacted people and trusted email addresses for enhanced security and efficiency. +
    • +
    +
  • + A simpler way to show the source of an email for better understanding of its origin and security analysis. +
    • +
    +
  • + Tags/Labels support to organize and categorize emails easily for better management and quick access to relevant content. +
    • +
    +
  • + Exchange Web Services (EWS) support is in development. For more details and updates, check out the progress here. +
    • +
+
diff --git a/pages/how-to-join.md b/pages/how-to-join.md new file mode 100644 index 0000000..d58348b --- /dev/null +++ b/pages/how-to-join.md @@ -0,0 +1,68 @@ +--- +title: How to join +nocontainer: true +exclude: true +--- +
+
+

Getting Started with Cypht Community

+

Introduction

+

+ Welcome to the Cypht community! We are excited to have you join us and become a part of our mission to + develop and improve Cypht. This documentation is designed to help you get started with our community, + understand the development process, and contribute effectively to the project. +

+

About the Cypht Community

+

What is Cypht?

+

+ Cypht is an open-source email client and news aggregator with a modular design. Unlike traditional + applications, Cypht is built entirely from plugins, or "module sets," with the core modules being + essential. Users can customize their experience by adding or replacing modules to suit specific site + requirements. This modular approach offers flexibility and easy customization, although it may introduce + complexity. +

+

Our Values

+

+ As a community, we prioritize collaboration, inclusivity, and transparency. We encourage respect for + others and open communication. Our goal is to create a welcoming environment for all developers, + regardless of experience levels. +

+

Joining the Community

+

Getting Involved

+

+ To start your journey with the Cypht community, + Connect with us on gitter. +

+

Setting up Your Development Environment

+

Tools and Software

+
+

+ Before you can contribute to Cypht, you need to set up your development environment. You will need + the + following tools and software: +

+
    +
  • A code editor of your choice (e.g., VSCode, Sublime Text)
    • +
  • Git for version control
    • +
  • PHP for developing Cypht
    • +
  • A web server (e.g., Apache, Nginx) for testing
    • +
+
+

Configuration and Setup

+

For installation, configuration, and setup, please check the installation + page

+

Contributing to Cypht

+

When contributing to Cypht, follow these practices

+

Community Resources

+

For more information and resources, explore the following:

+ +

+ Don't hesitate to ask for help or guidance. We have experienced community members who are willing to mentor + and support newcomers. Feel free to reach out on Gitter. +

+
+
diff --git a/index.html b/pages/index.md similarity index 55% rename from index.html rename to pages/index.md index fb7c618..52bf348 100644 --- a/index.html +++ b/pages/index.md @@ -1,71 +1,8 @@ - - - - - - - - Cypht - - - - - -
- -
+--- +title: Home +weight: 1 +nocontainer: true +---
-
+
@@ -113,7 +50,7 @@

An open source solution

-
+

Features

@@ -161,7 +98,6 @@

Features

-

Have a question about security?

@@ -175,7 +111,6 @@

Found a flaw in Cypht?

-

A modular design

@@ -188,46 +123,3 @@

A modular design

- - - - - - - - diff --git a/pages/install-1x.md b/pages/install-1x.md new file mode 100644 index 0000000..99a479f --- /dev/null +++ b/pages/install-1x.md @@ -0,0 +1,330 @@ +--- +title: Install v1 +exclude: true +--- +

Install Cypht v1.4.x

+

You can install specific versions of Cypht:

+

+ + + + + + + + Cypht v2.x + +

+

Cypht has four differents installation ways:

+
    +
  • Manual installation
    • +
  • Installation within Tiki
    • +
  • install using Docker (use cypht docker image)
    • +
  • Install cypht on a YunoHost server
    • +
+

Please read the bellow explanations about each way and pick one of your choice.

+
+

1. Manual installation

+

Requirements

+

Cypht 1.4.x requires PHP 5.6 or 7.0 or 7.1 or 7.2 or 7.3 or 7.4 (for PHP 8.1+, please use Cypht 2.1+), Composer 2, and at minimum the + OpenSSL, mbstring and cURL extensions. Cypht can also leverage several other + extensions as defined in composer.json. + Testing is done on Debian and Ubuntu + platforms with Nginx and Apache. +

+

Before proceeding please make sure your system meets minimal requirements

+

Steps

+

1. Check minimum requirements

+

+

+#!/bin/bash
+
+# You need to check php version which should be >=5.6 for version 1.4.x and 7.4 for upcoming Cypht version 2.0
+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
+

+

2. Download and prepare the code

+

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: + + +

+
+#!/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/cypht-org/cypht/archive/1.4.x.zip
+
+# unpack the archive
+unzip 1.4.x.zip
+
+# run composer
+cd cypht-1.4.x && composer install && cd ..
+
+# create a vanilla ini file
+cp cypht-1.4.x/hm3.sample.ini cypht-1.4.x/hm3.ini
+
+# fix permissions and ownership
+find cypht-1.4.x -type d -print | xargs chmod 755
+find cypht-1.4.x -type f -print | xargs chmod 644
+sudo chown -R root:root cypht-1.4.x
+
+# copy to destination folder
+sudo mv cypht-1.4.x/* $DESTINATION
+
+# remove working directory
+cd ..
+sudo rm -rf cypht-temp
+

3. Configure the program

+

To configure Cypht for your environment, you must first edit the hm3.ini file to your liking, + then + run the config_gen.php script to generate the optimized configuration file and assets used at run-time.

+ +

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.

+ +

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).

+ +
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/
+

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. +

+

4. Generate the run-time configuration

+

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:

+ +
cd /usr/local/share/cypht  (or wherever you put the code in section 1)
+sudo php ./scripts/config_gen.php
+ +

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.

+ + +

5. Enable the program in your web-server

+

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:

+ +
sudo ln -s /usr/local/share/cypht/site /var/www/html/mail
+ +

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.

+

6. Users

+

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: +

+            # 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
+
+

+

7. Debug mode

+

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:

+ +
sudo ln -s /usr/local/share/cypht /var/www/html/mail-debug
+ +

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.

+

8. Other INI files

+

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. +

+ +

2. Install cypht using Docker

+

+ 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.
+ Here is the cypht docker repository: https://hub.docker.com/r/sailfrog/cypht-docker
+ 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: +

+
    +
  • Create a new directory on your system named as you want.
    • +
  • In the directory created previously, create a file named "docker-compose.yaml" then copy and paste the content + of the example docker-compose section in the + created file .
    • +
  • Open your CLI/terminal and move to the directory containing the docker-compose file and run the command + to run containers + 
    docker-compose up -d
    +
    • +
  • 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.
    • +
+

+ NOTE: Please change usernames and passwords before using the given docker-compose code in your production + environment. +

+ +

3. Install Cypht on a YunoHost server

+

This is an other easy way of installing and use Cypht.
+ 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.
+ To learn more about YunoHost, visit https://yunohost.org/en/whatsyunohost +

+

To install Cypht on YunoHost, please follow these steps:

+
    +
  • If you don't have an installed YunoHost server, please consult the + guide to learn how to install it. If you have it, + please go directly to the next step.
    • +
  • If you just installed YunoHost or had it installed before, access your server and go to the admin + dashboard, then click on "Applications"
    • +
  • In the next page, click on the "install" button
    • +
  • In the search area, enter "cypht"
    • +
  • In the search result, click on cypht app
    • +
  • 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. +
    • +
  • Once clicked on the "install" button, wait for the installation to complete, it may take while.
    • +
  • Once the installation completed, you will be taking back to the dashboard.
    • +
  • 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.
    • +
  • 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.
    • +
+

4. Install Cypht within Tiki

+

If you have tiki installed, you can use Cypht within tiki. This is an easy way of installing Cypht.
+ Please follow the following link for a complete guide of how to install and use cypht within Tiki.
+ https://doc.tiki.org/Webmail +


+

Having problems?

+We are happy to help trouble-shoot any installation issues you run into. Chat with us at Gitter Cypht at Gitter and We'll get back to you as soon as we can. \ No newline at end of file diff --git a/pages/install-2x.md b/pages/install-2x.md new file mode 100644 index 0000000..4fad04e --- /dev/null +++ b/pages/install-2x.md @@ -0,0 +1,322 @@ +--- +title: Install v2 +exclude: true +--- +

Install Cypht v2.x

+

You can install specific versions of Cypht:

+

+ + + + + + + + Cypht v2.x + +

+

Cypht has four differents installation ways:

+
    +
  • Manual installation
    • +
  • Installation within Tiki
    • +
  • install using Docker (use cypht docker image)
    • +
  • Install cypht on a YunoHost server
    • +
+

Please read the bellow explanations about each way and pick one of your choice.

+
+

1. Manual installation

+ +

Requirements

+

Cypht 2.x requires at least PHP 8.1,Composer 2, and at minimum the OpenSSL, mbstring and cURL extensions. Cypht can also leverage several other + extensions as defined in composer.json. + Testing is done on Debian and Ubuntu + platforms with Nginx and Apache. +

+

Before proceeding please make sure your system meets minimal requirements

+

Steps

+

1. Check minimum requirements

+

+

+#!/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
+

+

2. Download and prepare the code

+

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: + + +

+
+#!/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
+
+
+

3. Configure the program

+

To configure Cypht for your environment, make adjustments to the .env file according to your preferences. + The .env file serves as the primary configuration file.

+ +

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.

+ +

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.

+ +

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).

+ +
+          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/
+
+

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. +

+

4. Generate Dynamic Run-Time Configuration

+

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:

+ +
cd /usr/local/share/cypht  (or wherever you put the code in section 1)
+sudo php ./scripts/config_gen.php
+ +

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.

+ +

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.

+ + +

5. Enable the program in your web-server

+

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:

+ +
sudo ln -s /usr/local/share/cypht/site /var/www/html/mail
+ +

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.

+

6. Users

+

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: +

+# 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
+
+

+

7. Debug mode

+

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:

+ +
sudo ln -s /usr/local/share/cypht /var/www/html/mail-debug
+ +

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.

+

8. Other Configs files

+

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. +

+ +

2. Install cypht using Docker

+

+ 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.
+ Here is the cypht docker repository: https://hub.docker.com/r/cypht/cypht
+ 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: +

+
    +
  • Create a new directory on your system named as you want.
    • +
  • In the directory created previously, create a file named "docker-compose.yaml" then copy and paste the content of + the example docker-compose file + in the created file or just download the example docker-compose file in the previously created directory. +
    • +
  • Open your CLI/terminal and move to the directory containing the docker-compose file and run the command to + run containers + 
    docker-compose up -d
    +
    • +
  • 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.
    • +
+

+ NOTE: Please change usernames and passwords before using the given docker-compose code in your production + environment. +

+ +

3. Install Cypht on a YunoHost server

+

This is an other easy way of installing and use Cypht.
+ 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.
+ To learn more about YunoHost, visit https://yunohost.org/en/overview/what_is_yunohost +

+

To install Cypht on YunoHost, please follow these steps:

+
    +
  • If you don't have an installed YunoHost server, please consult the + guide to learn how to install it. If you have it, please go directly to the next step.
    • +
  • If you just installed YunoHost or had it installed before, access your server and go to the admin dashboard, + then click on "Applications"
    • +
  • In the next page, click on the "install" button
    • +
  • In the search area, enter "cypht"
    • +
  • In the search result, click on cypht app
    • +
  • 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. +
    • +
  • Once clicked on the "install" button, wait for the installation to complete, it may take while.
    • +
  • Once the installation completed, you will be taking back to the dashboard.
    • +
  • 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.
    • +
  • 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.
    • +
+

4. Install Cypht within Tiki

+

If you have tiki installed, you can use Cypht within tiki. This is an easy way of installing Cypht.
+ Please follow the following link for a complete guide of how to install and use cypht within Tiki.
+ https://doc.tiki.org/Webmail +


+ +

Having problems?

+We are happy to help trouble-shoot any installation issues you run into. Chat with us at Gitter Cypht at Gitter and We'll get back to you as soon as we can. \ No newline at end of file diff --git a/pages/install.md b/pages/install.md new file mode 100644 index 0000000..03a0d61 --- /dev/null +++ b/pages/install.md @@ -0,0 +1,317 @@ +--- +title: Install +exclude: true +--- +

Install Cypht master

+

You can install specific versions of Cypht:

+

+ + + + + + + + Cypht v2.x + +

+

Cypht has four differents installation ways:

+
    +
  • Manual installation
    • +
  • Installation within Tiki
    • +
  • install using Docker (use cypht docker image)
    • +
  • Install cypht on a YunoHost server
    • +
+

Please read the bellow explanations about each way and pick one of your choice.

+
+

1. Manual installation

+

Requirements

+

Cypht master requires at least PHP 8.1, Composer 2, and at minimum the + OpenSSL, mbstring and cURL extensions. Cypht can also leverage several other + extensions as defined in composer.json. + Testing is done on Debian and Ubuntu + platforms with Nginx and Apache. +

+

Before proceeding please make sure your system meets minimal requirements

+

Steps

+

1. Check minimum requirements

+

+

+            #!/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
+
+

+

2. Download and prepare the code

+

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: + + +

+
+#!/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/cypht-org/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/.env.example.ini cypht-master/.env
+
+# 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
+

3. Configure the program

+

To configure Cypht for your environment, make adjustments to the .env file according to your + preferences. The .env file serves as the primary configuration file.

+ +

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.

+ +

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.

+ +

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).

+ +
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/
+

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. +

+

4. Generate the run-time configuration

+

Cypht uses a build process to create an optimized configuration, and to combine and minimize page assets. + Once + you have edited your .env file, generate the configuration with:

+ +
cd /usr/local/share/cypht  (or wherever you put the code in section 1)
+sudo php ./scripts/config_gen.php
+ +

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.

+ + +

5. Enable the program in your web-server

+

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:

+ +
sudo ln -s /usr/local/share/cypht/site /var/www/html/mail
+ +

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.

+

6. Users

+

Setting up users depends on what type of authentication you configure in the .env file. If you are using the + local database configuration for users, there are scripts in the scripts/ directory to help manage them: +

+# 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
+
+

+

7. Debug mode

+

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:

+ +
sudo ln -s /usr/local/share/cypht /var/www/html/mail-debug
+ +

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.

+

8. Other Configs files

+

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. +

+ + +

2. Install cypht using Docker

+

+ 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.
+ Here is the cypht docker repository: https://hub.docker.com/r/cypht/cypht
+ 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: +

+
    +
  • Create a new directory on your system named as you want.
    • +
  • In the directory created previously, create a file named "docker-compose.yaml" then copy and paste the content + of the example + docker-compose file in the created file or just download the example docker-compose file in the + previously created directory.
    • +
  • Open your CLI/terminal and move to the directory containing the docker-compose file and run the command + to run containers + 
    docker-compose up -d
    +
    • +
  • 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.
    • +
+

+ NOTE: Please change usernames and passwords before using the given docker-compose code in your production + environment. +

+ +

3. Install Cypht on a YunoHost server

+

This is an other easy way of installing and use Cypht.
+ 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.
+ To learn more about YunoHost, visit https://yunohost.org/en/whatsyunohost +

+

To install Cypht on YunoHost, please follow these steps:

+
    +
  • If you don't have an installed YunoHost server, please consult the + guide to learn how to install it. If you have it, + please go directly to the next step.
    • +
  • If you just installed YunoHost or had it installed before, access your server and go to the admin + dashboard, then click on "Applications"
    • +
  • In the next page, click on the "install" button
    • +
  • In the search area, enter "cypht"
    • +
  • In the search result, click on cypht app
    • +
  • 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. +
    • +
  • Once clicked on the "install" button, wait for the installation to complete, it may take while.
    • +
  • Once the installation completed, you will be taking back to the dashboard.
    • +
  • 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.
    • +
  • 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.
    • +
+

4. Install Cypht within Tiki

+

If you have tiki installed, you can use Cypht within tiki. This is an easy way of installing Cypht.
+ Please follow the following link for a complete guide of how to install and use cypht within Tiki.
+ https://doc.tiki.org/Webmail +


+

Having problems?

+We are happy to help trouble-shoot any installation issues you run into. Chat with us at Gitter Cypht at Gitter and We'll get back to you as soon as we can. \ No newline at end of file diff --git a/pages/license.md b/pages/license.md new file mode 100644 index 0000000..63b9e0a --- /dev/null +++ b/pages/license.md @@ -0,0 +1,66 @@ +--- +title: License +weight: 5 +--- +

Cypht source code is distributed under the LGPL V2.1 license:

+

Go to the license

+

Cypht will always be both free and Open Source. Cyphtuses a handful of third party libraries both indirectly + and directly. Compatible version of direct dependencies are always included in the Cypht source or installed via + PHP composer. +

+
+

Directly Used

+ +

Indirectly Used

+ diff --git a/pages/modules.md b/pages/modules.md new file mode 100644 index 0000000..1538d2e --- /dev/null +++ b/pages/modules.md @@ -0,0 +1,264 @@ +--- +title: Modules +weight: 4 +--- +

Overview

+

Cypht has a modular design. Instead of an application with a plugin API, Cypht is an application comprised + entirely of plugins, or as we call them, "module sets". There is only one required set, the "core" modules. The + components of any module set can be added to, or even replaced, by site specific modules. All the functionality + of Cypht is broken out into module sets, and each set is built from small pieces that are also easy to override. + The module system is powerful, but also a bit complex. First let's take a look at the module sets that come with + Cypht:

+
+
    +
  • 2faissues
    TOTP + based 2 factor authentication using the Google Authenticator mobile app +
    • +
  • accountissues
    UI + features for admins to create accounts, and for users to update passwords (when using the built-in DB + authentication). Functional, but could use more admin features +
    • +
  • + advanced_searchissues
    Support + for advanced search +
    • +
  • api_loginissues
    Login + using an API to provide single sign on ability +
    • +
  • calendarissues
    Basic + calendar. +
    • +
  • contactsissues
    Contact + management. Requires at least one contact backend module set to be enabled +
    • +
  • + carddav_contactsissues
    Support + for contacts stored in CardDav +
    • +
  • local_contactsissues
    Simple + locally stored contact support +
    • +
  • ldap_contactsissues
    Support + for contacts stored in LDAP +
    • +
  • gmail_contactsissues
    Read-only + support for Gmail contacts with an Oauth2 enabled Gmail account +
    • +
  • coreissues
    + Handles page layout, login/logout, and the default settings pages +
    • +
  • desktop_notificationsissues
    Desktop + notifications for new messages +
    • +
  • developerissues
    + For development, provides resources and installation details. Only available in "debug mode" +
    • +
  • dynamic_loginissues
    Allows + user to authenticate against a list of popular mail services, or to auto-discover the services for the + specified E-mail address +
    • +
  • feedsissues
    + RSS/ATOM feed support +
    • +
  • githubissues
    + Github repository tracking +
    • +
  • hello_worldissues
    + Example module set with lots of comments +
    • +
  • highlightsissues
    + Color highlighting for message lists +
    • +
  • historyissues
    + Simple list of messages read since login +
    • +
  • idle_timerissues
    + Controls idle time and automatic logout +
    • +
  • imapissues
    + IMAP E-mail account support +
    • +
  • imap_foldersissues
    + IMAP E-mail folder management support +
    • +
  • inline_messageissues
    + View messages inline in a reading pane instead of on a new page +
    • +
  • jmapissues
    + JMAP (JSON Meta Application Protocol) It uses a JSON-based structure to streamline communication and optimize + performance. By reducing the number of network round-trips compared to traditional protocols like IMAP and SMTP, + JMAP enhances responsiveness and reduces resource usage. With its real-time updates and simplified structure. It + is designed to improve the user experience by providing faster, more reliable access to data, making it ideal + for modern applications. +
    • +
  • + keyboard_shortcutsissues
    Adds + support for site navigation and actions using the keyboard +
    • +
  • nasaissues
    Access + the NASA APOD API content +
    • +
  • nuxissues
    + Friendly new user experience. Quickly add common E-mail services, and view development updates. Needs help + text added +
    • +
  • PGPissues
    + Encryption using Pretty Good Privacy +
    • +
  • profilesissues
    + Profiles to set reply-to, name, and signature to associated E-mail accounts +
    • +
  • recaptchaissues
    + Enable Recaptcha on the login form +
    • +
  • + recover_settingsissues
    + Ability to recover user settings after an external password change +
    • +
  • saved_searchesissues
    + Save and re-run searches easily +
    • +
  • sievefiltersissues
    + Message filtering +
    • +
  • siteissues
    + Site specific overrides. Used to control other module sets without hacking the code +
    • +
  • smtpissues
    + Send outbound E-mail using SMTP servers +
    • +
  • tagsissues
    + Allows users to organize content effectively by utilizing tags or labels. It is designed to enhance content + management by enabling users to assign relevant tags, facilitating easy categorization, filtering, and retrieval + of content. The tagging feature is fully implemented, allowing for seamless interaction where users can add, + edit, or remove tags as needed. +
    • +
  • themesissues
    + Change the UI using CSS +
    • +
  • wordpressissues
    + WordPress.com notifications and freshly pressed lists +
    • +
+
+

Module sets are setup in the hm3.ini file. With the exception of the core module, they can all be enabled or + disabled independently (though module sets can rely on each other, like the nux module). When the site build + process is run, module assignments are calculated and saved in the configuration file (so they don't need to be + re-calculated at run-time). There is also a debug mode in which modules are activated dynamically (for the most + part) to make development easier.

+

File Structure

+

Module set names in the ini file match the directory the module code is in under modules/. Files in a module + have pre-defined names. Any other required code should be included from one of these files. +

+

+
    +
  • setup.php
    This is where a module set defines it's own modules and assigns them to request + identifiers. This file must return an array of valid input and associated types in order for the module code + to have access to it. +
    • +
  • modules.php
    This is where the actual module code lives. If you have external libraries to include + this is a good place to do so. +
    • +
  • site.js
    Optional file to include JavaScript for the module set.
    • +
  • site.css
    Optional file to include CSS for the module set.
    • +
+
+

A module set can also include an assets sub-directory. Anything in that directory will be made availble in the + browser. An example of this is the HTML WSIWYG editor for the smtp module set. In debug mode the module site.css + and site.js files are included directly if they exist. In production mode combined and optionally minified + versions are used consisting of a single js file and a single CSS file generated by the build process. Minifying + programs can be specified in the hm3.ini file. +

+

Input and Output

+

There are two kinds of modules: Input processing modules called "handler modules", and output formatting modules + called "output modules". Modules can pass data to each other, and output modules have access to all the data + input modules create. By default, module output is immutable and can't be stepped on by other modules. Data can + be marked writable and an "appendable" data type is also supported. The typical job of a handler module is to + analyze user input and do some work based on it, which it then sends to the output modules. The typical job of + an output module is to take the results of an input module and format it for the browser. +

+

Hello World

+

For more information, check out the "hello world" module set. It illustrates how modules work and has loads of + comments that explain what is going on:

+

+https://github.com/cypht-org/cypht/tree/master/modules/hello_world +

\ No newline at end of file diff --git a/pages/security.md b/pages/security.md new file mode 100644 index 0000000..9f6e18c --- /dev/null +++ b/pages/security.md @@ -0,0 +1,117 @@ +--- +title: Security +weight: 3 +--- +

Have a question about security?

+

Found a flaw in Cypht? We want to hear from you!

+

Drop by the Cypht Gitter channel. + We take security seriously. Cypht is an entirely volunteer effort, so + we can't afford a bounty program. We can however promise that any security issue reported to us before release + will receive a quick response, a thorough review, a sincere thanks, and an honorable mention on this page

+
+

In the browser

+
    +
  • + By default all cookies are session level, HTTP only, and have the secure flag, path, and domain values set + (except one cookie used to pass user notices to the javascript) +
    • +
  • + HTTP request header fingerprinting, CSRF token protection, and target/source origin mismatch blocking +
    • +
  • + Security related HTTP headers like X-XSS-Protection, X-Content-Type-Options, X-Frame-Options, and + Content-Security-Policy +
    • +
  • + Subresource Integrity for the 2 primary includes (site.js and site.css) +
    • +
  • + Configurable idle timeout module set that ends a session after a predetermined amount of time +
    • +
  • + Support for 2 factor authentication with any TOTP compatible authentication application +
    • +
  • + Optional AES encrypted AJAX responses +
    • +
  • + Optional AES encrypted local session storage cache +
    • +
  • + reCAPTCHA support for the login form +
    • +
+
+

On the server

+
    +
  • + TLS/STARTTLS support for IMAP, LDAP, and SMTP connections +
    • +
  • + Oauth2 over IMAP/SMTP supported (currently only Gmail and Outlook support this feature) +
    • +
  • + Session level data is encrypted with a long random string generated on login. Data is stored server side, + and the key is stored in a session level secure cookie +
    • +
  • + Persistent data stored between logins is encrypted with a key derived from your clear text password, which + is obviously not stored anywhere +
    • +
  • + All encryption is done with libsodium if available, otherwise with AES-256-CBC, encrypt-then-MAC, and PBKDF2 + key derivation using OpenSSL (NOT Mcrypt) +
    • +
  • + PHP ini settings are tightened up at runtime for extra security, including open basedir and session best + practices (ones writable at runtime) +
    • +
  • + No writable files or directories are used inside the web-server document root, and only 3 files need to be + inside the document root to run the program. Module sets may include additional assets, such as the HTML + editor for outbound mail +
    • +
  • + Optional local DB based authentication using a salt and PBKDF2 (or libsodium using Argon2 if available) +
    • +
  • + HTML formatted E-Mail is filtered through HTMLPurifier with all external resources removed before being + rendered +
    • +
  • + Perfect score from the "Email Privacy Tester" at https://emailprivacytester.com/ +
+
+

During development

+
    +
  • + Easy output escaping inside modules for potentially dangerous content +
    • +
  • + Development is done with PHP's "E_ALL" and "E_STRICT" error reporting +
    • +
  • + Module design enforces a separation of input processing and output formatting, and encourages concise + methods, which makes the code easier to debug and audit +
    • +
  • + Only white-listed and typed/sanitized input is allowed. Modules must pre-define input in order to have + access +
    • +
  • + Modules can't reference PHP super-globals, and there are no globally scoped variables at all (there are a + few static class instances with private data structures that use getter/setter methods) +
    • +
  • + ~98% unit test coverage with PHPUnit for the + application framework and core module set +
    • +
  • + UI tests using Selenium with python bindings (currently at 64 tests) +
  • + Continuous Integration for UI tests, unit tests, and static code analysis done with Travis CI. You can read more info about our testing process at the testing page +
    • +
\ No newline at end of file diff --git a/pages/tests.md b/pages/tests.md new file mode 100644 index 0000000..60c4ef5 --- /dev/null +++ b/pages/tests.md @@ -0,0 +1,46 @@ +--- +title: Tests +exclude: true +--- +

Tests

+
+

+ Cypht uses PHPUnit to run our unit tests, and Selenium for integration testing. I periodically update the HTML + coverage report located here:

/docs/test_coverage/index.html

+ Currently our unit tests only cover the application framework (all the code under "lib/"), and the core + module set, and our Selenium tests are still pretty basic. We make use of the following services that generously + provide + access to Open Source projects:
+

+
+

Travis CI

+https://travis-ci.org/cypht-org/cypht/builds +

Travis CI is a really cool continuous integration service that we use to re-run our unit and UI tests every time + a change is pushed to Github. Our Travis build is 18 combinations, 6 versions of PHP (5.4, 5.5, 5.6, 5.7, 7.0, + 7.1, + 7.2) with 3 different databases (Mysql, Postgresql, Sqlite).

+
+

BrowserStack

+https://www.browserstack.com/

+

BrowserStack is a cloud based Selenium grid we use to run our UI tests. We connect to it directly from Travis CI. + Currently we test 4 browsers (Safari, IE, Edge, and Chrome). Firefox is disable for now due to a compatibility + issue + with the test environment.

+
+

Coveralls

+https://coveralls.io/github/cypht-org/cypht

+

Coveralls.io provides access to the PHPUnit test coverage report, and is updated every time code is pushed to + Github. + It has some cool metrics to track unit test coverage over time, and in general is a nicer UI than the PHPUnit + HTML + report.

+
+

Scrutinizer

+https://scrutinizer-ci.com/g/cypht-org/cypht/

+

Scrutinizer is a static code analyzer with a lot of great options. It understands our doc-string format and + provides + additinal information about potential type mismatches, in addition to a number of other static checks. Currently + I have it limited to the application framework (all the code under "lib/"). Like the Travis builds and Coveralls + reports, + a new analysis is run every time we push code to Github.

\ No newline at end of file diff --git a/security.html b/security.html deleted file mode 100644 index 76166e0..0000000 --- a/security.html +++ /dev/null @@ -1,226 +0,0 @@ - - - - - - Security - - - - - - -
- -
- -
-

Have a question about security?

-

Found a flaw in Cypht? We want to hear from you!

-

Drop by the Cypht Gitter channel. - We take security seriously. Cypht is an entirely volunteer effort, so - we can't afford a bounty program. We can however promise that any security issue reported to us before release - will receive a quick response, a thorough review, a sincere thanks, and an honorable mention on this page

-
-

In the browser

-
    -
  • - By default all cookies are session level, HTTP only, and have the secure flag, path, and domain values set - (except one cookie used to pass user notices to the javascript) -
    • -
  • - HTTP request header fingerprinting, CSRF token protection, and target/source origin mismatch blocking -
    • -
  • - Security related HTTP headers like X-XSS-Protection, X-Content-Type-Options, X-Frame-Options, and - Content-Security-Policy -
    • -
  • - Subresource Integrity for the 2 primary includes (site.js and site.css) -
    • -
  • - Configurable idle timeout module set that ends a session after a predetermined amount of time -
    • -
  • - Support for 2 factor authentication with any TOTP compatible authentication application -
    • -
  • - Optional AES encrypted AJAX responses -
    • -
  • - Optional AES encrypted local session storage cache -
    • -
  • - reCAPTCHA support for the login form -
    • -
-
-

On the server

-
    -
  • - TLS/STARTTLS support for IMAP, LDAP, and SMTP connections -
    • -
  • - Oauth2 over IMAP/SMTP supported (currently only Gmail and Outlook support this feature) -
    • -
  • - Session level data is encrypted with a long random string generated on login. Data is stored server side, - and the key is stored in a session level secure cookie -
    • -
  • - Persistent data stored between logins is encrypted with a key derived from your clear text password, which - is obviously not stored anywhere -
    • -
  • - All encryption is done with libsodium if available, otherwise with AES-256-CBC, encrypt-then-MAC, and PBKDF2 - key derivation using OpenSSL (NOT Mcrypt) -
    • -
  • - PHP ini settings are tightened up at runtime for extra security, including open basedir and session best - practices (ones writable at runtime) -
    • -
  • - No writable files or directories are used inside the web-server document root, and only 3 files need to be - inside the document root to run the program. Module sets may include additional assets, such as the HTML - editor for outbound mail -
    • -
  • - Optional local DB based authentication using a salt and PBKDF2 (or libsodium using Argon2 if available) -
    • -
  • - HTML formatted E-Mail is filtered through HTMLPurifier with all external resources removed before being - rendered -
    • -
  • - Perfect score from the "Email Privacy Tester" at https://emailprivacytester.com/ -
-
-

During development

-
    -
  • - Easy output escaping inside modules for potentially dangerous content -
    • -
  • - Development is done with PHP's "E_ALL" and "E_STRICT" error reporting -
    • -
  • - Module design enforces a separation of input processing and output formatting, and encourages concise - methods, which makes the code easier to debug and audit -
    • -
  • - Only white-listed and typed/sanitized input is allowed. Modules must pre-define input in order to have - access -
    • -
  • - Modules can't reference PHP super-globals, and there are no globally scoped variables at all (there are a - few static class instances with private data structures that use getter/setter methods) -
    • -
  • - ~98% unit test coverage with PHPUnit for the - application framework and core module set -
    • -
  • - UI tests using Selenium with python bindings (currently at 64 tests) -
  • - Continuous Integration for UI tests, unit tests, and static code analysis done with Travis CI. You can read more info about our testing process at the testing page -
    • -
- -
- - - - - - - diff --git a/bootstrap.bundle.min.js b/static/bootstrap.bundle.min.js similarity index 100% rename from bootstrap.bundle.min.js rename to static/bootstrap.bundle.min.js diff --git a/static/cecil-card.png b/static/cecil-card.png new file mode 100644 index 0000000..6e115db Binary files /dev/null and b/static/cecil-card.png differ diff --git a/static/config-generator.js b/static/config-generator.js new file mode 100644 index 0000000..fcf07b4 --- /dev/null +++ b/static/config-generator.js @@ -0,0 +1,172 @@ +// Helper functions +/** + * Gets input value, compatible with text/number inputs and checkboxes + * + * @param {JQueryElement} jqueryElem what jQuery element to get the value from + * @param {Boolean} checkbox whether the jQuery element is a checkbox + * @returns {string|Boolean} + */ +function getInputValue(jqueryElem, checkbox=false) { + if (!checkbox) { + return jqueryElem.val(); + } else { + return jqueryElem.is(":checked"); + } +} + +/** + * Adds a label under the passed jQuery element, + * notifying that changing it will change presented options + * + * @param {JQueryElem} jqueryElem jQuery element to add the label after + * @param {String|Boolean} prefix Prefix to add to "in the above input will change other presented options!". + * If set to explicitly to false, cancel adding label + * + * @default "Entering a value" + */ +function addExpandLabel(jqueryElem, prefix="Entering a value") { + if (prefix === false) return; + + jqueryElem.after(`${prefix} in the above input will change other presented options!`) +} + +// Thanks to https://stackoverflow.com/a/75419102 for the jsdoc notation +/** + * Runs provided func with input value as argument when... + * - Provided event trigger (default: input) + * - Setting the value + * Additionally, it uses addExpandLabel on the element + * + * @param {JQueryElem} jqueryElem what jQuery element to get the value from + * @param {(value:String|Boolean) => void} func the function to run on event & run. The input value will be passed as first/only argument + * @param {Boolean} checkbox whether the jQuery element is a checkbox + * @default false + * @param {String} event which event to attach to + * @default "input" + * @param {String|Boolean|undefined} prefix @see addExpandLabel + * + */ +function setInputAndRun(jqueryElem, func, checkbox=false, event="input", prefix=undefined) { + addExpandLabel(jqueryElem, prefix); + + jqueryElem.on(event, function(e) { + func(getInputValue(jqueryElem, checkbox)); + }); + func(getInputValue(jqueryElem, checkbox)); +} + +/** + * What it says on the tin: if passed boolean is true, + * show passed JQuery elements. Else, hide them. + * + * @param {Boolean} boolean whether to show or hide the passed jQuery elements + * @param {JQueryElem} jqueryElem which jQuery element(s) to show/hide depending on boolean + */ +function ifTrueShowElseHide(boolean, jqueryElem) { + if (boolean) { + jqueryElem.show(400); + } else { + jqueryElem.hide(400); + } +} + + +// This function needs a better name +/** + * From jquery selector string, get the first element. + * If the first element/input has value, show the other elements from the selector. + * Otherwise, hide them + * + * @param {String} jqueryString - jQuery selector string. `:first` & `:not(:first)` + * will be appended to select the right elements + * + * Note: this function should not be run for things that only + * appear in their own module file (e.g. RECAPTCHA, WORDPRESS) + */ +function onlyShowRestIfFirstHasValue(jqueryString) { + const first = $(jqueryString + ":first"); + const otherElements = $(jqueryString + ":not(:first)").parent("fieldset"); + + setInputAndRun(first, (value) => { + ifTrueShowElseHide(value.trim() != "", otherElements); + }) +} + +/** + * Resets jqueryEleemnt to default value. + * + * @param {JQueryElement} jqueryElement what jQuery element to reset the value of. It needs data-default to be set + * @param {Boolean} checkbox whether the jQuery element is a checkbox + * @default false + */ +function resetInput(jqueryElement, checkbox=false) { + if (!checkbox) { + jqueryElement.val(jqueryElement.data("default")).change().trigger("input"); + + } else { + jqueryElement.prop("checked", jqueryElement.data("default")).change().trigger("input"); + } +} + + +/* Specific events */ + +// Show related auth fields depending on whether they are selected +function onInputAuthType(value) { + ifTrueShowElseHide(value == "LDAP", $("[id^=LDAP_AUTH_]")); + ifTrueShowElseHide(value == "IMAP", $("[id^=IMAP_AUTH_]")); +} + +// Show LONG_SESSION_LIFETIME when ALLOW_LONG_SESSION is enabled +function onInputAllowLongSession(value) { + ifTrueShowElseHide(value == true, $("[id=LONG_SESSION_LIFETIME]")) +} + +// Generate .env file into #result when #generate is clicked +function onClickGenerate(value) { + let text = ""; + + const allInputs = $("input, select"); + allInputs.each(function(i) { + const input = $(this); + const value = input.attr("type") != "checkbox" ? input.val() : input.is(":checked"); + + text += `${input.attr("name")}=${value}\n`; + }); + + $("#result").val(text) +} + +// Reset button functionality (individual fields) +function onClickReset(e) { + const target = $(e.target); + target.siblings("input[type='checkbox']").each(function() { + resetInput($(this), true) + }); + target.siblings("input[type!='checkbox'], select").each(function() { + resetInput($(this)) + }); +} + +// Reset all functionality +function onClickResetAll() { + if (confirm("Reset all values?")) { + $(".reset").each(function() { + $(this).trigger("click"); + }) + } +} + +/* Main */ +onlyShowRestIfFirstHasValue("[name^=DEFAULT_SMTP_]"); +onlyShowRestIfFirstHasValue("[name^=GMAIL_]"); +onlyShowRestIfFirstHasValue("[name^=OUTLOOK_]"); + +setInputAndRun($("[name=AUTH_TYPE"), onInputAuthType, false, "input", "Selecting LDAP or IMAP"); +setInputAndRun($("[name=ALLOW_LONG_SESSION]"), onInputAllowLongSession, true); +setInputAndRun($("#generate"), onClickGenerate, false, "click", false) + +$(".reset").on("click", onClickReset); +$("#reset-all").on("click", onClickResetAll); + + diff --git a/img/.DS_Store b/static/img/.DS_Store similarity index 100% rename from img/.DS_Store rename to static/img/.DS_Store diff --git a/img/Add.PNG b/static/img/Add.PNG similarity index 100% rename from img/Add.PNG rename to static/img/Add.PNG diff --git a/img/Archive.png b/static/img/Archive.png similarity index 100% rename from img/Archive.png rename to static/img/Archive.png diff --git a/img/Calendar.PNG b/static/img/Calendar.PNG similarity index 100% rename from img/Calendar.PNG rename to static/img/Calendar.PNG diff --git a/img/Compose.PNG b/static/img/Compose.PNG similarity index 100% rename from img/Compose.PNG rename to static/img/Compose.PNG diff --git a/img/Contact.PNG b/static/img/Contact.PNG similarity index 100% rename from img/Contact.PNG rename to static/img/Contact.PNG diff --git a/img/Developer.PNG b/static/img/Developer.PNG similarity index 100% rename from img/Developer.PNG rename to static/img/Developer.PNG diff --git a/img/Inbox.PNG b/static/img/Inbox.PNG similarity index 100% rename from img/Inbox.PNG rename to static/img/Inbox.PNG diff --git a/img/Multi.PNG b/static/img/Multi.PNG similarity index 100% rename from img/Multi.PNG rename to static/img/Multi.PNG diff --git a/img/Oneperson.png b/static/img/Oneperson.png similarity index 100% rename from img/Oneperson.png rename to static/img/Oneperson.png diff --git a/img/block_list.png b/static/img/block_list.png similarity index 100% rename from img/block_list.png rename to static/img/block_list.png diff --git a/img/cloud.png b/static/img/cloud.png similarity index 100% rename from img/cloud.png rename to static/img/cloud.png diff --git a/img/cypht.png b/static/img/cypht.png similarity index 100% rename from img/cypht.png rename to static/img/cypht.png diff --git a/img/cypht_shot1.png b/static/img/cypht_shot1.png similarity index 100% rename from img/cypht_shot1.png rename to static/img/cypht_shot1.png diff --git a/img/edit_icon.png b/static/img/edit_icon.png similarity index 100% rename from img/edit_icon.png rename to static/img/edit_icon.png diff --git a/img/home.PNG b/static/img/home.PNG similarity index 100% rename from img/home.PNG rename to static/img/home.PNG diff --git a/img/icon.ico b/static/img/icon.ico similarity index 100% rename from img/icon.ico rename to static/img/icon.ico diff --git a/img/login.PNG b/static/img/login.PNG similarity index 100% rename from img/login.PNG rename to static/img/login.PNG diff --git a/img/logo.svg b/static/img/logo.svg similarity index 100% rename from img/logo.svg rename to static/img/logo.svg diff --git a/img/screenshots/1.png b/static/img/screenshots/1.png similarity index 100% rename from img/screenshots/1.png rename to static/img/screenshots/1.png diff --git a/img/screenshots/10.png b/static/img/screenshots/10.png similarity index 100% rename from img/screenshots/10.png rename to static/img/screenshots/10.png diff --git a/img/screenshots/11.png b/static/img/screenshots/11.png similarity index 100% rename from img/screenshots/11.png rename to static/img/screenshots/11.png diff --git a/img/screenshots/12.png b/static/img/screenshots/12.png similarity index 100% rename from img/screenshots/12.png rename to static/img/screenshots/12.png diff --git a/img/screenshots/13.jpg b/static/img/screenshots/13.jpg similarity index 100% rename from img/screenshots/13.jpg rename to static/img/screenshots/13.jpg diff --git a/img/screenshots/2.png b/static/img/screenshots/2.png similarity index 100% rename from img/screenshots/2.png rename to static/img/screenshots/2.png diff --git a/img/screenshots/3.png b/static/img/screenshots/3.png similarity index 100% rename from img/screenshots/3.png rename to static/img/screenshots/3.png diff --git a/img/screenshots/4.png b/static/img/screenshots/4.png similarity index 100% rename from img/screenshots/4.png rename to static/img/screenshots/4.png diff --git a/img/screenshots/5.png b/static/img/screenshots/5.png similarity index 100% rename from img/screenshots/5.png rename to static/img/screenshots/5.png diff --git a/img/screenshots/6.png b/static/img/screenshots/6.png similarity index 100% rename from img/screenshots/6.png rename to static/img/screenshots/6.png diff --git a/img/screenshots/7.png b/static/img/screenshots/7.png similarity index 100% rename from img/screenshots/7.png rename to static/img/screenshots/7.png diff --git a/img/screenshots/8.png b/static/img/screenshots/8.png similarity index 100% rename from img/screenshots/8.png rename to static/img/screenshots/8.png diff --git a/img/screenshots/9.png b/static/img/screenshots/9.png similarity index 100% rename from img/screenshots/9.png rename to static/img/screenshots/9.png diff --git a/img/sieveFilters.png b/static/img/sieveFilters.png similarity index 100% rename from img/sieveFilters.png rename to static/img/sieveFilters.png diff --git a/img/snooze.png b/static/img/snooze.png similarity index 100% rename from img/snooze.png rename to static/img/snooze.png diff --git a/img/userprofil.PNG b/static/img/userprofil.PNG similarity index 100% rename from img/userprofil.PNG rename to static/img/userprofil.PNG diff --git a/jquery.slim.min.js b/static/jquery.slim.min.js similarity index 100% rename from jquery.slim.min.js rename to static/jquery.slim.min.js diff --git a/site.css b/static/site.css similarity index 99% rename from site.css rename to static/site.css index 09075c6..faaf683 100644 --- a/site.css +++ b/static/site.css @@ -884,6 +884,10 @@ button.bg-dark:hover { text-align: center!important } +.text-left { + text-align: left; +} + @media print { *, ::after, @@ -1023,7 +1027,7 @@ header { .banner { position: relative; - background: url(img/cypht.png); + background: url(/img/cypht.png); min-height: 100vh; background-size: cover; background-position: center; @@ -1134,7 +1138,7 @@ section p { } .feature-section { - background: linear-gradient( rgba(4, 26, 0, 0.85), rgba(4, 26, 0, 0.85)), url(img/cloud.png); + background: linear-gradient( rgba(4, 26, 0, 0.85), rgba(4, 26, 0, 0.85)), url(/img/cloud.png); background-attachment: fixed; background-position: center; background-repeat: no-repeat; @@ -1173,7 +1177,7 @@ h3 { } .module-section { - background: linear-gradient( rgba(4, 26, 0, 0.85), rgba(4, 26, 0, 0.85)), url(img/cloud.png); + background: linear-gradient( rgba(4, 26, 0, 0.85), rgba(4, 26, 0, 0.85)), url(/img/cloud.png); background-attachment: fixed; background-position: center; background-repeat: no-repeat; @@ -1214,7 +1218,7 @@ h3 { } .social-section { - background: linear-gradient( rgba(4, 26, 0, 0.85), rgba(4, 26, 0, 0.85)), url(img/cloud.png); + background: linear-gradient( rgba(4, 26, 0, 0.85), rgba(4, 26, 0, 0.85)), url(/img/cloud.png); background-attachment: fixed; background-position: center; background-repeat: no-repeat; diff --git a/tests.html b/tests.html deleted file mode 100644 index f7dbeb3..0000000 --- a/tests.html +++ /dev/null @@ -1,150 +0,0 @@ - - - - - - License - - - - - - -
- -
- -
-

Tests

-
-

- Cypht uses PHPUnit to run our unit tests, and Selenium for integration testing. I periodically update the HTML - coverage report located here:

/docs/test_coverage/index.html

- Currently our unit tests only cover the application framework (all the code under "lib/"), and the core - module set, and our Selenium tests are still pretty basic. We make use of the following services that generously - provide - access to Open Source projects:
-

-
-

Travis CI

- https://travis-ci.org/cypht-org/cypht/builds -

Travis CI is a really cool continuous integration service that we use to re-run our unit and UI tests every time - a change is pushed to Github. Our Travis build is 18 combinations, 6 versions of PHP (5.4, 5.5, 5.6, 5.7, 7.0, - 7.1, - 7.2) with 3 different databases (Mysql, Postgresql, Sqlite).

-
-

BrowserStack

- https://www.browserstack.com/

-

BrowserStack is a cloud based Selenium grid we use to run our UI tests. We connect to it directly from Travis CI. - Currently we test 4 browsers (Safari, IE, Edge, and Chrome). Firefox is disable for now due to a compatibility - issue - with the test environment.

-
-

Coveralls

- https://coveralls.io/github/cypht-org/cypht

-

Coveralls.io provides access to the PHPUnit test coverage report, and is updated every time code is pushed to - Github. - It has some cool metrics to track unit test coverage over time, and in general is a nicer UI than the PHPUnit - HTML - report.

-
-

Scrutinizer

- https://scrutinizer-ci.com/g/cypht-org/cypht/

-

Scrutinizer is a static code analyzer with a lot of great options. It understands our doc-string format and - provides - additinal information about potential type mismatches, in addition to a number of other static checks. Currently - I have it limited to the application framework (all the code under "lib/"). Like the Travis builds and Coveralls - reports, - a new analysis is run every time we push code to Github.

-
- - - - - - -