From a63257f40e00fe23a2cb6ccffaf06e92c9268f55 Mon Sep 17 00:00:00 2001 From: Dorian Niemiec Date: Fri, 8 Nov 2024 14:40:18 +0100 Subject: [PATCH] feat: add the MERNMail documentation --- components/Hero.jsx | 4 +- constants/docLinks.js | 38 +++++++++++++- docs/configuration.md | 84 ++++++++++++++++++++++++++++++ docs/demo.md | 7 +++ docs/deployment/index.md | 5 ++ docs/deployment/svrjs.md | 3 ++ docs/features.md | 60 +++++++++++++++++++++ docs/getting-started.md | 57 ++++++++++++++++++++ docs/index.md | 5 +- docs/usage.md | 109 +++++++++++++++++++++++++++++++++++++++ 10 files changed, 366 insertions(+), 6 deletions(-) create mode 100644 docs/configuration.md create mode 100644 docs/demo.md create mode 100644 docs/deployment/index.md create mode 100644 docs/deployment/svrjs.md create mode 100644 docs/features.md create mode 100644 docs/getting-started.md create mode 100644 docs/usage.md diff --git a/components/Hero.jsx b/components/Hero.jsx index a81afce..4aa03c8 100644 --- a/components/Hero.jsx +++ b/components/Hero.jsx @@ -20,14 +20,14 @@ function Hero() {

Get started diff --git a/constants/docLinks.js b/constants/docLinks.js index 903839a..cf3fd03 100644 --- a/constants/docLinks.js +++ b/constants/docLinks.js @@ -2,6 +2,42 @@ export default [ { href: "/docs", target: "_self", - label: "Welcome to MERNMail documentation!" + label: "Welcome to the MERNMail documentation!" + }, + { + href: "/docs/getting-started", + target: "_self", + label: "Getting started" + }, + { + href: "/docs/demo", + target: "_self", + label: "Official demo" + }, + { + href: "/docs/features", + target: "_self", + label: "Features" + }, + { + href: "/docs/configuration", + target: "_self", + label: "Configuration" + }, + { + href: "/docs/usage", + target: "_self", + label: "Usage" + }, + { + href: "/docs/deployment", + target: "_self", + label: "Deployment" + }, + { + href: "/docs/deployment/svrjs", + target: "_self", + sub: true, + label: "Deploy with SVR.JS" } ]; diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..1aba3a8 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,84 @@ +# Configuration + +This guide will walk you through the process of configuring MERNMail. The configuration is managed through environment variables, which are defined in a `.env` file. An example `.env.example` file is provided in the repository to help you get started. + +## Creating the `.env` File + +1. **Copy the `.env.example` File**: + First, copy the `.env.example` file to create a new `.env` file in the root directory of your project: + + ```bash + cp .env.example .env + ``` + +2. **Edit the `.env` File**: + Open the `.env` file in your preferred text editor and update the values as needed. + +## Configuration Options + +### General Settings + +- **PORT**: The port on which the MERNMail server listens. +- **ATTACHMENTS_PATH**: The absolute path to the directory that contains attachments. If not set, the "attachments" directory in the script root will be used. + +### Database Configuration + +- **MONGODB_CONNSTRING**: The MongoDB connection string. + +### Encryption Settings + +- **ENCRYPTION_SECRETKEY**: A 256-bit secret key for password encryption. You can generate this key using the command `openssl rand -base64 32`. +- **ENCRYPTION_IV**: A 128-bit IV for password encryption. You can generate this IV using the command `openssl rand -base64 16`. + +### JWT Configuration + +- **JWT_SECRET**: The secret key for JWT (JSON Web Token) authentication. You can generate this key using the command `openssl rand -base64 32`. +- **JWT_SECURECOOKIE**: Set this to `1` if users access the webmail from HTTPS. + +### Email Receiving Configuration + +- **EMAIL_RECV_PROTOCOL**: The email receiving protocol. This can be `pop3` or `imap`. +- **EMAIL_RECV_HOST**: The host for receiving emails. +- **EMAIL_RECV_PORT**: The port for receiving emails. +- **EMAIL_RECV_TLS**: Set this to `1` to enable TLS for receiving emails. +- **EMAIL_RECV_ALLOWBADCERTIFICATES**: Set this to `1` to allow bad TLS certificates for receiving emails. +- **EMAIL_RECV_DISCARDDOMAIN**: Set this to `1` to log into email server without the email domain in the username. + +### Email Sending Configuration + +- **EMAIL_SEND_PROTOCOL**: The email sending protocol. This can be `smtp`. +- **EMAIL_SEND_HOST**: The host for sending emails. +- **EMAIL_SEND_PORT**: The port for sending emails. +- **EMAIL_SEND_TLS**: Set this to `1` to enable TLS for sending emails. If using STARTTLS, set this to `0`. +- **EMAIL_SEND_ALLOWBADCERTIFICATES**: Set this to `1` to allow bad TLS certificates for sending emails. +- **EMAIL_SEND_DISCARDDOMAIN**: Set this to `1` to log into email server without the email domain in the username. + +## Example Configuration + +Here is an example of what your `.env` file might look like: + +```shell +PORT=3000 +ATTACHMENTS_PATH=/path/to/attachments +MONGODB_CONNSTRING=mongodb://localhost:27017/mernmail +ENCRYPTION_SECRETKEY=your_256_bit_secret_key +ENCRYPTION_IV=your_128_bit_iv +JWT_SECRET=your_jwt_secret +JWT_SECURECOOKIE=1 +EMAIL_RECV_PROTOCOL=imap +EMAIL_RECV_HOST=imap.example.com +EMAIL_RECV_PORT=993 +EMAIL_RECV_TLS=1 +EMAIL_RECV_ALLOWBADCERTIFICATES=0 +EMAIL_RECV_DISCARDDOMAIN=0 +EMAIL_SEND_PROTOCOL=smtp +EMAIL_SEND_HOST=smtp.example.com +EMAIL_SEND_PORT=587 +EMAIL_SEND_TLS=0 +EMAIL_SEND_ALLOWBADCERTIFICATES=0 +EMAIL_SEND_DISCARDDOMAIN=0 +``` + +## Next Steps + +After configuring the `.env` file, you can start the MERNMail server by following the instructions in the [Getting started](/docs/getting-started) section. \ No newline at end of file diff --git a/docs/demo.md b/docs/demo.md new file mode 100644 index 0000000..5cc6257 --- /dev/null +++ b/docs/demo.md @@ -0,0 +1,7 @@ +# Official demo + +MERNMail hosts an official demo that connects to Ethereal Email. You can access the demo at [demo.mernmail.org](https://demo.mernmail.org). + +If you try to send an email message from this demo, the email message will not be sent, but instead delivered to the sender's inbox. + +You need to create an email account on [Ethereal Email](https://ethereal.email) before logging into the MERNMail demo. The credentials of the Ethereal Email account are visible after creating it. Use the username and the password to log into MERNMail demo. \ No newline at end of file diff --git a/docs/deployment/index.md b/docs/deployment/index.md new file mode 100644 index 0000000..ef91b72 --- /dev/null +++ b/docs/deployment/index.md @@ -0,0 +1,5 @@ +# Deployment + +MERNMail provides multiple options for deployment. Here is the list of the options: + +- [SVR.JS](/docs/deployment/svrjs) \ No newline at end of file diff --git a/docs/deployment/svrjs.md b/docs/deployment/svrjs.md new file mode 100644 index 0000000..558aad2 --- /dev/null +++ b/docs/deployment/svrjs.md @@ -0,0 +1,3 @@ +# Deploy with SVR.JS + +TODO \ No newline at end of file diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 0000000..c0ff544 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,60 @@ +# Features + +MERNMail is a webmail application designed to provide a seamless email experience. Below are the key features categorized for easy reference. + +## Email Management + +- **Inbox**: View and manage incoming emails. +- **Sent Items**: View and manage sent emails. +- **Drafts**: Save and manage email drafts. +- **Trash**: View and manage deleted emails. +- **Spam**: Automatically filter and manage spam emails. +- **Search**: Powerful search functionality to find specific emails. +- **Filters**: Create and manage email filters. +- **Labels**: Organize emails using custom labels. + +## Composer + +- **Rich Text Editor**: Compose emails with formatting options. +- **Attachments**: Attach files to emails. +- **Signature**: Automatically add a custom signature to outgoing emails. +- **CC/BCC**: Add carbon copy and blind carbon copy recipients. +- **Drafts**: Save email drafts for later editing and sending. + +## Address Book + +- **Contacts**: Add, edit, and delete contacts. +- **Groups**: Organize contacts into groups. +- **Import/Export**: Import and export contacts in various formats (e.g., CSV, vCard). +- **Search**: Quickly find contacts using the search bar. + +## Settings + +### General + +- **Language**: Select preferred language for the interface. +- **Notifications**: Enable or disable email and push notifications. +- **Theme**: Choose between light and dark themes. + +### Mailboxes + +- **Manage Mailboxes**: Add, edit, or delete mailboxes. +- **Folder Management**: Create and manage email folders. + +### Identities + +- **Manage Identities**: Add, edit, or delete email identities. +- **Default Identity**: Set a default identity for outgoing emails. + +### Signature + +- **Custom Signature**: Create and customize email signatures. +- **HTML Signature**: Support for HTML signatures. + +## Integration + +- **Email Protocols**: Support for IMAP, POP3, and SMTP protocols. + +## User Interface + +- **Responsive Design**: Optimized for use on various devices and screen sizes. \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..cfba401 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,57 @@ +# Getting started + +Welcome to MERNMail! This guide will help you set up and run MERNMail on your local machine. MERNMail is an open-source webmail application built using the MERN stack (MongoDB, Express, React, Node.JS). + +## Prerequisites + +Before you begin, ensure you have the following software and tools installed on your machine: + +- **Node.JS**: Make sure you have Node.JS installed. You can download it from [nodejs.org](https://nodejs.org/). +- **npm**: Node Package Manager (npm) comes with Node.JS. Ensure it is installed and up to date. +- **MongoDB**: Install MongoDB from [mongodb.com](https://www.mongodb.com/). +- **Git**: Install Git from [git-scm.com](https://git-scm.com/). + +## Installation + +Follow these steps to install and set up MERNMail: + +### 1. Clone the Repository + +First, clone the MERNMail repository: + +```bash +git clone https://git.svrjs.org/mernmail/mernmail.git +cd mernmail +``` + +### 2. Install Dependencies + +Navigate to the project directory and install the necessary dependencies: + +```bash +npm install +``` + +### 3. Configuration + +Copy the `.env.example` file to a `.env` file in the root directory of the project. The configuration options can be found in the "TODO" page. + +### 4. Running the Application + +Start the MERNMail server: + +```bash +npm start +``` + +### 5. Accessing the Application + +Open your web browser and navigate to `http://localhost:3000` to access the MERNMail application. + +## Next Steps + +Now that you have MERNMail up and running, you can explore the following sections of the documentation: + +- [**Configuration**](/docs/configuration): Learn how to configure MERNMail. +- [**Usage**](/docs/usage): Understand how to use MERNMail for sending and receiving emails. +- [**Deployment**](/docs/deployment): Learn how to deploy the MERNMail webmail application. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index c550ff3..c9d132f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,2 @@ -# Welcome to MERNMail documentation! - -The documentation is work in progress... \ No newline at end of file +# Welcome to the MERNMail documentation! +_This documentation is in the public domain._ \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..f4dfde8 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,109 @@ +# Usage + +This section provides a comprehensive guide on how to use MERNMail, including the webmail functionality, composer, address book, and settings page. + +## Webmail Functionality + +### Inbox + +The Inbox is where you receive all your emails. Here's how to navigate and manage your inbox: + +- **Viewing Emails**: Click on an email to view its contents. +- **Marking as Read/Unread**: Select an email and click the envelope icon next to the email to mark it as read or unread. +- **Deleting Emails**: Select an email and click the trash icon to delete the email. +- **Searching Emails**: Use the search bar to find specific emails. + +### Composer + +The Composer is used to create and send new emails. Here's how to use it: + +- **New Email**: Click the "Compose" button to open the Composer. +- **Recipients**: Enter the recipient's email address in the "To" field. You can also add CC and BCC recipients. +- **Subject**: Enter a subject for your email. +- **Body**: Type your message in the body of the email. +- **Attachments**: Click the "Attach" button to attach files. +- **Sending**: Click the "Send" button to send your email. + +### Address Book + +The Address Book helps you manage your contacts. Here's how to use it: + +- **Adding Contacts**: Click the "Add Contact" button and fill in the contact details. +- **Editing Contacts**: Click on a contact to edit their details. +- **Deleting Contacts**: Click the trash icon next to a contact to delete them. +- **Searching Contacts**: Click the search icon and use the search bar to find specific contacts. + +## Settings Page + +The Settings page allows you to customize your MERNMail experience. Here are the sections you can configure: + +### Language + +- **Changing Language**: Select your preferred language from the dropdown menu. + +### Notifications + +- **Push Notifications**: Enable or disable push notifications for new messages. + +### Theme + +- **Changing Theme**: Choose between light and dark themes to suit your preference. + +### Mailboxes + +- **Managing Mailboxes**: Add, edit, or delete mailboxes to organize your emails. + +### Identities + +- **Managing Identities**: Add, or delete email identities to manage multiple email accounts. + +### Signature + +- **Adding Signature**: Create and customize your email signature. +- **Editing Signature**: Update your email signature as needed. + +## Example Usage Scenarios + +### Sending an Email + +1. Click the "Compose" button to open the Composer. +2. Enter the recipient's email address in the "To" field. +3. Enter a subject for your email. +4. Type your message in the body of the email. +5. Click the paperclip icon to attach files if needed. +6. Click the "Send" button to send your email. + +### Adding a Contact + +1. Navigate to the Address Book. +2. Click the "New contact" button. +3. Fill in the contact details, including name, email, and phone number. +4. Click the "Save" button to add the contact. + +### Changing the Theme + +1. Navigate to the Settings page. +2. Go to the "Theme" section. +3. Select your preferred theme (system, light or dark). +4. The theme will be applied immediately. + +### Managing Mailboxes + +1. Navigate to the Settings page. +2. Go to the "Mailboxes" section. +4. Enter the mailbox name and click the "+" button. +5. To edit or delete a mailbox, click the respective icons next to the mailbox name. + +### Adding an Identity + +1. Navigate to the Settings page. +2. Go to the "Identities" section. +4. Enter the identity details, including name and email address. +5. Click the "Add identity" button to add the identity. + +### Customizing Your Signature + +1. Navigate to the Settings page. +2. Go to the "Signature" section. +3. Enter your desired signature text. +4. Click the "Save signature" button to apply the signature. \ No newline at end of file