-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #73 from conjoon/dev
Dev
- Loading branch information
Showing
4 changed files
with
247 additions
and
44 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,28 +1,27 @@ | ||
| # conjoon/lumen-app-email Documentation | ||
|
|
||
| # Installation | ||
| The recommended way to install **lumen-app-email** is by using `composer create-project`: | ||
|
|
||
| ## Via GIT & composer | ||
| ```shell | ||
| $ git clone https://github.com/conjoon/lumen-app-email | ||
| $ cd ./lumen-app-email | ||
| $ composer i | ||
| ``` | ||
|
|
||
| ## Via Docker (DDEV) | ||
| For a quick start, we suggest to use a pre-configured container for running the backend: [conjoon\/ddev-ms-email](https://github.com/conjoon/ddev-ms-email) provides a `.**Docker (DDEV)** configuration for a container running **lumen-app-email** out-of-the-box and is easy to install. | ||
|
|
||
| ## From Scratch | ||
| Since **lumen-app-webmail** is a Lumen/Laravel application, detailed information on how to set up a webserver for it can be found in the official [Lumen\-documentation](https://lumen.laravel.com/docs/). | ||
| `composer create-project {packageName} {targetDirectory} {version}` | ||
|
|
||
| The following command will install an instance of **lumen-app-email** along with its dependencies into the directory | ||
| `htdocs` relative to the current working directory: | ||
|
|
||
| #### .env - Environment Variables | ||
| The root directory of the project contains a [dotenv-configuration](https://github.com/vlucas/phpdotenv) file (`.env.example`). | ||
| Settings may be adjusted on your own to match your desired configuration for the environment the microservice runs in. Copy and rename this file to `.env` and configure away! | ||
| ```shell | ||
| $ composer create-project conjoon/lumen-app-email htdocs "1.*" | ||
| ``` | ||
|
|
||
| Once `composer` has finished downloading and installing the project, the `post-create-project-cmd` will automatically invoke | ||
| `php artisan install`, the installation script for **lumen-app-email**. Please refer to the subsequent documentation for | ||
| further details about the configuration options available: | ||
|
|
||
| ## Further Documentation | ||
| 1. Configuration | ||
| 1. [Available CLI commands](./commands.md) | ||
| 1. [Setting up CORS](./cors.md) | ||
| 2. [Configuring allowed IMAP servers](./serverconfig.md) | ||
| 2. [Troubleshooting & Known Issues](./troubleshooting.md) | ||
| 2. [Configuring IMAP servers](./imapserver.md) | ||
| 3. [Troubleshooting & Known Issues](./troubleshooting.md) | ||
|
|
||
| ## Related Resources | ||
| A pre-configured container for running an instance of **lumen-app-email** is also available and can be found at | ||
| [conjoon\/ddev-ms-email](https://github.com/conjoon/ddev-ms-email). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,194 @@ | ||
| # Available CLI commands | ||
|
|
||
| One **lumen-app-email** was installed with `composer`, you can use [Artisan](https://laravel.com/docs/artisan) to interact with this | ||
| instance using the CLI. | ||
|
|
||
| Change the directory to your installation of **lumen-app-email** and type | ||
|
|
||
| ```bash | ||
| $ php artisan list | ||
| ``` | ||
|
|
||
| to get a list of all commands available with this installation. | ||
|
|
||
| #### Commands | ||
| The following CLI commands are available for an instance of **lumen-app-email**: | ||
|
|
||
| | Command | Description | | ||
| |--------------------------------|----------------------------------------------------------------------------------------------------------------------| | ||
| | [install](#install) | Starts the installation process | | ||
| | [configure:url](#configureurl) | Configure URL where this instance is available | | ||
| | [configure:api](#configureapi) | Configure API paths | | ||
| | [configure:env](#configureenv) | Specify the environment this instance runs in | | ||
| | [configure:debug](#configuredebug) | Enable or disable debug mode | | ||
| | [copyconfig](#copyconfig) | Activate pre-defined configuration templates for this instance | | ||
|
|
||
|
|
||
| ## Configuration file | ||
| Configuration settings collected by the various scripts can be found in the dotenv-file `.env` in the root-directory of the installation. | ||
| The file can also be edited manually with the key/value pairs described in this document. | ||
|
|
||
| ## `install` | ||
| Starts the installation process and queues through the [commands](#commands) to collect all necessary information for configuring | ||
| this instance. The command can also be run for already installed instances of **lumen-app-email**. | ||
|
|
||
| ```bash | ||
| $ php artisan install | ||
| ``` | ||
|
|
||
|
|
||
| ## `configure:url` | ||
|
|
||
| Specify the URL of the server where this instance is located, along with the path to the installation directory of **lumen-app-email**. | ||
|
|
||
| ```bash | ||
| $ php artisan configure:url | ||
| ``` | ||
|
|
||
| #### dotenv key | ||
| `APP_URL` | ||
| - Type: `String` | ||
| - Default: `https://ddev-ms-email.ddev.site` | ||
|
|
||
| ### Example | ||
| The machine's URL serving this instance is | ||
| ``` | ||
| https://localhost:8080 | ||
| ``` | ||
|
|
||
| The URI of **lumen-app-email** on this machine is | ||
|
|
||
| ``` | ||
| /lumen-app-email/htdocs | ||
| ``` | ||
|
|
||
| the value of this setting must therefore be | ||
|
|
||
| ``` | ||
| https://localhost:8080/lumen-app-email/htdocs | ||
| ``` | ||
|
|
||
| ## `configure:api` | ||
|
|
||
| Specify the paths to the APIs exposed by this instance. | ||
|
|
||
| **lumen-app-email** provides an _auth_-Service and an _email_-Service. The _auth_-Service is required for | ||
| authenticating against the **IMAP**/**SMTP** servers the _email_-Service will connect to. | ||
|
|
||
| These settings provide the base-paths to the endpoints the services expose. | ||
|
|
||
| This instance will consider any path-segments representing the required API-Version | ||
| path appended to the path automatically. | ||
|
|
||
| ```bash | ||
| $ php artisan configure:api | ||
| ``` | ||
|
|
||
| #### dotenv key | ||
| `APP_EMAIL_PATH` | ||
| - Type: `String` | ||
| - Default: `rest-api-email` | ||
|
|
||
| The path to the _email_-Service. | ||
|
|
||
| `APP_AUTH_PATH` | ||
| - Type: `String` | ||
| - Default: `rest-imapuser` | ||
|
|
||
| The path to the _auth_-Service. | ||
|
|
||
| ### Example | ||
| **lumen-app-email** is available at | ||
| ``` | ||
| https://localhost:8080/lumen-app-email/htdocs | ||
| ``` | ||
|
|
||
| `APP_EMAIL_PATH` is configured with | ||
|
|
||
| ``` | ||
| api/rest-api-email | ||
| ``` | ||
|
|
||
| Endpoints for this service can then be found at | ||
|
|
||
| ``` | ||
| https://localhost:8080/lumen-app-email/htdocs/api/rest-api-email | ||
| ``` | ||
|
|
||
| Additionally, clients can require different versions for this API by appending a version tag to this | ||
| URL as a path segment: | ||
|
|
||
| ``` | ||
| https://localhost:8080/lumen-app-email/htdocs/api/rest-api-email/v2 | ||
| ``` | ||
|
|
||
| Omitting a version in the URL will default to the latest version of this API available. | ||
|
|
||
| The same applies to the `APP_AUTH_PATH` setting. | ||
|
|
||
| Refer to the [Backend API documentation](https://www.conjoon.org/docs/api/rest-api) for all available API endpoints. | ||
|
|
||
|
|
||
| ## `configure:env` | ||
| Specify the environment this instance is used in. | ||
|
|
||
| ```bash | ||
| $ php artisan configure:env | ||
| ``` | ||
|
|
||
| #### dotenv key | ||
| `APP_ENV` | ||
| - Type: `String` | ||
| - Default: `production` | ||
|
|
||
| When using **lumen-app-email** other than on a local machine, set this to `production`. For development | ||
| or staging, this value can be set to an arbitrary value for branching into different functionality | ||
| for these environments, if required. | ||
|
|
||
| Note: | ||
| This is a setting introduced by **Laravel**. Refer to its [documentation](https://laravel.com/docs/configuration#determining-the-current-environment) for further information. | ||
|
|
||
|
|
||
| ## `configure:debug` | ||
| Enable/disable debug mode for this instance. | ||
|
|
||
| ```bash | ||
| $ php artisan configure:debug | ||
| ``` | ||
|
|
||
| #### dotenv key | ||
| `APP_DEBUG` | ||
| - Type: `Boolean` | ||
| - Default: `false` | ||
|
|
||
| For local development, set this to `true`. In `production`, this should be set to `false`, otherwise your risking to expose | ||
| sensitive information to clients. | ||
|
|
||
| Note: | ||
| This is a setting introduced by **Laravel**. Refer to its [documentation](https://laravel.com/docs/configuration#debug-mode) for further information. | ||
|
|
||
|
|
||
| ## `copyconfig` | ||
| Copies default configuration and saves them under a name this instance requires. | ||
|
|
||
| This command processes configuration files located in `app/config`. | ||
|
|
||
| `copyconfig` will probe existing configuration files and require user interaction before it accidentally | ||
| overwrites them. | ||
|
|
||
| ```bash | ||
| $ php artisan copyconfig | ||
| ``` | ||
|
|
||
| The following configuration files are affected by this command: | ||
|
|
||
| | Template | Target | Description | | ||
| |----------------------------------------|-----------------|------------------------------------------------------------------| | ||
| | `cors.example.php` | `cors.php` | Cross-Origin Resource Sharing configuration | | ||
| | `imapserver.example.php` | `imapserver.php` | Configuration for Email servers this instance may connect to | | ||
|
|
||
| Once the files where copied, you should adjust the settings found therein to your needs. | ||
|
|
||
| Refer to their documentation for available configuration options: | ||
| 1. [Setting up CORS](./cors.md) | ||
| 2. [Configuring IMAP servers](./imapserver.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters