docs: update documentation with available cli commands

refs #67
conjoon · Nov 13, 2022 · 2ec50e1 · 2ec50e1
1 parent d34b005
commit 2ec50e1
Show file tree

Hide file tree

Showing 4 changed files with 246 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -1,13 +1,37 @@
 # conjoon/lumen-app-email ![MIT](https://img.shields.io/github/license/conjoon/lumen-app-email) ![Tests](https://github.com/conjoon/lumen-app-email/actions/workflows/run.tests.yml/badge.svg)
-A backend service for IMAP/SMTP email messaging, based on Lumen.
+Backend service for IMAP/SMTP email messaging.
 
 ## What is lumen-app-email?
-**conjoon/lumen-app-email** is a **PHP🐘** application built with [Lumen](https://lumen.laravel.com).
-It provides a stateless backend for Email messaging according to [https://github.com/conjoon/rest-api-description](conjoon/rest-api-description)
+**conjoon/lumen-app-email** is a standalone **PHP🐘** application built with [Lumen](https://lumen.laravel.com).
+It provides a backend for Email messaging according to [https://github.com/conjoon/rest-api-description](conjoon/rest-api-description)
 and serves endpoints for reading, writing and sending email messages with **IMAP**/**SMTP**.
 
 **lumen-app-email** has minimal footprint and is easy to install. 
 
+## Installation
+
+```shell
+$ composer create-project conjoon/lumen-app-email htdocs "1.*" 
+```
+Please refer to the official [documentation](./docs) of **lumen-app-email** for further information on installation and configuration.
+
+
+
+## Features
+
+**lumen-app-email** follows a service oriented approach. 
+Services are easily replacable with the help of upfront DI configurations and related bindings. 
+
+**Use lumen-app-email, if you...**
+- need a fully functional middleware for communicating with IMAP / SMTP servers
+- want to provide webmail solutions with domain-specific sign-in to IMAP accounts
+- are looking for a distribution with minimal footprint and easy setup
+- require a headless, service oriented standalone application with your infrastructure 
+
+**do not use lumen-app-email, if you...**
+ - are looking for a stateful, session based webmail backend
+ - need baked-in caching
+
 ## API Examples
 
 ````http request
@@ -32,31 +56,14 @@ Host: hostname
 ````
 
 
-## Features
-
-**lumen-app-email** follows a service oriented approach. 
-Services are easily replacable with the help of upfront DI configurations and related bindings. 
-
-**Use lumen-app-email, if you...**
-- need a fully functional middleware for communicating with IMAP / SMTP servers
-- want to provide webmail solutions with domain-specific sign-in to IMAP accounts
-- are looking for a distribution with minimal footprint and easy setup
-- require a headless, service oriented standalone application with your infrastructure 
-
-**do not use lumen-app-email, if you...**
- - are looking for a stateful, session based webmail backend
- - need baked-in caching
-
-
-## Supported Backend API
-* **rest-api-email**
-  <br>For the list of endpoints this microservice provides, please refer to the 
+## Backend API documentation
+  <br>For the list of endpoints this service provides, please refer to the 
   [OpenApi-documentation of `rest-api-email`](https://github.com/conjoon/rest-api-description), available as OpenAPI documentation at [conjoon.stoplight.io](https://conjoon.stoplight.io/docs/rest-api-description/)
 
-## Installation & Configuration
-Please refer to the official [documentation](./docs) of **lumen-app-email** for further information on installation and configuration.
-
 ## Additional Notes
+### Official Documentation
+The official documentation can be found at the project page for [conjoon](https://www.conjoon.org/docs/api/backends/@conjoon/lumen-app-email).
+This documentation is in line with the offical project page.
 
 ### WIP
 **lumen-app-email** is a work in progress. We are constantly improving the API and strive for a RESTful implementation.

diff --git a/docs/README.md b/docs/README.md
@@ -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).
diff --git a/docs/commands.md b/docs/commands.md
@@ -0,0 +1,193 @@
+# Available CLI commands
+
+One  **lumen-app-email** was installed, 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](#configure:url) | Configure URL where this instance is available                                                                       |
+| [configure:api](#configure:api) | Configure API paths                                                                                                  | 
+| [configure:env](#configure:env)           | Specify the environment this instance runs in                                                                        | 
+| [configure:debug](#configure:debug)       | 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)
diff --git a/docs/serverconfig.md → docs/imapserver.md b/docs/serverconfig.md → docs/imapserver.md
@@ -2,7 +2,10 @@
 In order for users to authenticate against IMAP servers, `lumen-app-email` provides a template-configuration file in `app/config/imapserver.php.example`.
 In this file, you can specify an array of mail server configurations. Each entry represents a mail server to which connection may be established, for both sending and receiving messages.
 
-Rename this file to `imapserver.php` once all configurations are defined.
+Note:
+[`php artisan copyconfig`](./commands.md#copyconfig) can be used for automatically copying the configuration template
+`imapserver.example.php` to its target destination. If you choose to manually work with the template, copy and rename it 
+to `imapserver.php`, then adjust its entries.
 
 ## Entry Details