diff --git a/.env.selfhost.example b/.env.selfhost.example index 3ca00ba..0cc2e98 100644 --- a/.env.selfhost.example +++ b/.env.selfhost.example @@ -1,21 +1,22 @@ -# Redis container name +# Redis container name - required REDIS_URL="redis://redis:6379" -# Postgres +# Postgres - required for docker-compose, not needed for just docker POSTGRES_USER="postgres" POSTGRES_PASSWORD="postgres" POSTGRES_DB="unsend" +# Postgres - required DATABASE_URL="postgresql://postgres:postgres@postgres:5432/unsend" -# NextAuth +# NextAuth - required NEXTAUTH_URL="http://localhost:3000" NEXTAUTH_SECRET= -# Github login +# Github login - required GITHUB_ID="" GITHUB_SECRET="" -# AWS details +# AWS details - required AWS_DEFAULT_REGION="us-east-1" AWS_SECRET_KEY="" AWS_ACCESS_KEY="" @@ -23,8 +24,7 @@ AWS_ACCESS_KEY="" DOCKER_OUTPUT=1 -NEXT_PUBLIC_IS_CLOUD=false API_RATE_LIMIT=1 -# used to send important error notification +# used to send important error notification - optional DISCORD_WEBHOOK_URL="" diff --git a/README.md b/README.md index d708690..cd59785 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ We're currently working on opening unsend for public beta. - [NextAuth.js](https://next-auth.js.org/) - Authentication - [tRPC](https://trpc.io/) - API - [hono](https://hono.dev/) - Public API +- [Redis](https://redis.io/) - Queue ## Local Development @@ -77,6 +78,22 @@ To run Unsend locally, you will need - Postgres SQL Database - Docker (optional) +## Docker + +We provide a Docker container for Unsend, which is published on both DockerHub and GitHub Container Registry. + +DockerHub: [https://hub.docker.com/r/unsend/unsend](https://hub.docker.com/r/unsend/unsend) +GitHub Container Registry: [https://ghcr.io/unsend-dev/unsend](https://ghcr.io/unsend-dev/unsend) +You can pull the Docker image from either of these registries and run it with your preferred container hosting provider. + +Please note that you will need to provide environment variables for connecting to the database, redis, aws and so forth. + +For detailed instructions on how to configure and run the Docker container, please refer to the Docker [Docker README](./docker/README.md) in the docker directory. + ## Self Hosting -Docs coming soon. +Checkout the [Self hosting](https://docs.unsend.dev/get-started/self-hosting) guide to learn how to self-host Unsend. + +Also + +[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/QbMnwX?referralCode=oaAwvp) diff --git a/apps/docs/get-started/create-aws-credentials.mdx b/apps/docs/get-started/create-aws-credentials.mdx new file mode 100644 index 0000000..3cffcb1 --- /dev/null +++ b/apps/docs/get-started/create-aws-credentials.mdx @@ -0,0 +1,38 @@ +--- +title: Create AWS credentials +description: Step by step guide to create AWS credentials to self-host Unsend. +--- + + + + Login to your AWS console and go to IAM > Users > Create user. Type in user name, in this case `unsend` + + ![create user](/images/aws/key-1.png) + + + + Search for `AmazonSNSFullAccess` and `AmazonSESFullAccess` and check the checkboxes. Then proceed to create the user. + + ![set permission](/images/aws/key-2.png) + + + + Click on the created user and click on the `Create access key` button. + + ![create access key](/images/aws/key-3.png) + ![option and create](/images/aws/key-4.png) + ![description](/images/aws/key-5.png) + + + + Copy the access key ID and secret access key to your `.env` file. + + ```env + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + ``` + + ![create access key](/images/aws/key-6.png) + + + diff --git a/apps/docs/get-started/nodejs.mdx b/apps/docs/get-started/nodejs.mdx index f41fc86..377130b 100644 --- a/apps/docs/get-started/nodejs.mdx +++ b/apps/docs/get-started/nodejs.mdx @@ -1,6 +1,7 @@ --- title: NodeJS description: "Send your mail using unsend in NodeJS" +icon: node-js --- ## Prerequisites diff --git a/apps/docs/get-started/self-hosting.mdx b/apps/docs/get-started/self-hosting.mdx new file mode 100644 index 0000000..a5f9ea1 --- /dev/null +++ b/apps/docs/get-started/self-hosting.mdx @@ -0,0 +1,127 @@ +--- +title: Self hosting Unsend +description: "An end-to-end guide on how to self-host Unsend. An opensource sending infrastructure for developers." +icon: server +--- + +## Prerequisites + +- A [Github](https://github.com) account +- An [AWS](https://aws.amazon.com) account + +If you have any questions join [#self-host](https://discord.gg/gbsvjb9MqV) on discord. + +## Step 1: Environment variables + +Unsend depends on AWS ses to send emails and SNS to receive email status. Along with that it also depends on Postgres as a database and Redis for queue. Copy the `.env.selfhost.example` file to `.env` and fill in the values. + + + + tl;dr: Login to your AWS console and create a new user with programmatic access. Attach the `AmazonSNSFullAccess` and `AmazonSESFullAccess` policies to the user. Then create a new access key for the user. + +Add the following environment variables. + + ```env + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + ``` + + + Follow this for detailed steps: [Create AWS + credentials](/get-started/create-aws-credentials) + + + + + Usend uses github authentication for login. + +Use this link to [create an github app](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) + +Callback URL : `https:///api/auth/callback/github` + +![github app](/images/github-callback.png) + +Add the following environment variables. + +```env +GITHUB_ID="" +GITHUB_SECRET="" +``` + + If you want email/password login, please help us out with the [code](https://github.com/unsend-dev/unsend) + + + Unsend uses Postgres as a database and Redis as a queue. You need to create a new database and add the following environment variables. + +If you're using docker-compose or our railway template, it's all automatically done for you. + +```env +DATABASE_URL="postgres://:@:/" +REDIS_URL="redis://:@:" +``` + + + + Url is the app url you're going to use and secret is random string. You can generate a random secret using this command. + +```sh +openssl rand -base64 32 +``` + +Add the following environment variables. + +```env + NEXTAUTH_URL="https://" + NEXTAUTH_SECRET="" +``` + + + + +## Step 2: Setting up the app + +You can use any platforms that supports docker. You can also use the railway template. In this example I'll be using railway. If you have any questions drop in the [discord channel](https://discord.gg/gbsvjb9MqV) and i'll try to help you out + +### Docker + +Follow this guide to setup your docker instance: [Set up docker](/get-started/set-up-docker) + +[![Docker image](https://img.shields.io/badge/dockerhub-images-important.svg?logo=Docker)](https://hub.docker.com/r/unsend/unsend) + +### Railway + +This option is very easy. Click on the below button and click "Deploy now". Add a custom domain etc. + +Updating image is easy, click on the 3 dots and redeploy. This will pull the latest image. + +[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/QbMnwX?referralCode=oaAwvp) + +Your unsend instance is now live now. + +## Step 3: Setting up a region + +In order to send emails, you need to select an region in aws. Use a region where your users are located / where unsend is hosted. If you're confused just use `us-east-1`. + +You can check available regions [here](https://docs.aws.amazon.com/general/latest/gr/ses.html) + +Once you logged in to unsend, it will prompt you add ses configuration. + +- Add the region +- Add the callback url, which is basically the app url. Note this should be accesible from internet. This is how you get the delivery status of the emails. +- You don't need to update the send rate, it's automatically based on your account. + +![github app](/images/ses-settings/add-ses-settings.png) + +Don't forget to get the SES account out of sandbox mode. + +![github app](/images/ses-settings/sandbox.png) + +## Next steps + +You're all set up now. + +- Setup a domain. +- Create an API key. +- Start sending emails. + +If you have any questions, please join [#self-host](https://discord.gg/gbsvjb9MqV) on discord. diff --git a/apps/docs/get-started/set-up-docker.mdx b/apps/docs/get-started/set-up-docker.mdx new file mode 100644 index 0000000..e27e67c --- /dev/null +++ b/apps/docs/get-started/set-up-docker.mdx @@ -0,0 +1,69 @@ +--- +title: Docker setup for unsend +description: The following guide will walk you through setting up Unsend using Docker. You can choose between a production setup using Docker Compose or a standalone container. +--- + +## Prerequisites + +Before you begin, ensure that you have the following installed: + +- Docker +- Docker Compose (if using the Docker Compose setup) + +## Option 1: Production Docker Compose Setup + +This setup includes PostgreSQL, Redis and the Unsend application. + +1. Download the Docker Compose file from the Unsend repository: [compose.yml](https://github.com/unsend-dev/unsend/blob/main/docker/prod/compose.yml) +2. Navigate to the directory containing the `compose.yml` file. +3. Create a `.env` file in the same directory. Copy the contents of `.env.selfhost.example` +4. Run the following command to start the containers: + +``` +docker-compose --env-file ./.env up -d +``` + +This will start the PostgreSQL database, Redis and the Unsend application containers. + +5. Access the Unsend application by visiting `http://localhost:3000` in your web browser. + +## Option 2: Standalone Docker Container + +If you prefer to host the Unsend application on your container provider of choice, you can use the pre-built Docker image from DockerHub or GitHub's Package Registry. Note that you will need to provide your own database and SMTP host. + +1. Pull the Unsend Docker image: + +``` +docker pull unsend/unsend +``` + +Or, if using GitHub's Package Registry: + +``` +docker pull ghcr.io/unsend-dev/unsend +``` + +2. Run the Docker container, providing the necessary environment variables for your database and SMTP host: + +``` +docker run -d \ + -p 3000:3000 \ + -e NEXTAUTH_URL="" + -e NEXTAUTH_SECRET="" + -e DATABASE_URL="" + -e REDIS_URL="" + -e AWS_ACCESS_KEY="" + -e AWS_SECRET_KEY="" + -e AWS_DEFAULT_REGION="" + -e GITHUB_ID="" + -e GITHUB_SECRET="" + unsend/unsend +``` + +Replace the placeholders with your actual database and aws details. + +1. Access the Unsend application by visiting the URL you provided in the `NEXTAUTH_URL` environment variable in your web browser. + +## Success + +You have now successfully set up Unsend using Docker. You can start sending emails efficiently. If you encounter any issues or have further questions, please refer to the official Unsend documentation or seek assistance from the community. diff --git a/apps/docs/images/aws/key-1.png b/apps/docs/images/aws/key-1.png new file mode 100644 index 0000000..269fde8 Binary files /dev/null and b/apps/docs/images/aws/key-1.png differ diff --git a/apps/docs/images/aws/key-2.png b/apps/docs/images/aws/key-2.png new file mode 100644 index 0000000..b11d831 Binary files /dev/null and b/apps/docs/images/aws/key-2.png differ diff --git a/apps/docs/images/aws/key-3.png b/apps/docs/images/aws/key-3.png new file mode 100644 index 0000000..08915e8 Binary files /dev/null and b/apps/docs/images/aws/key-3.png differ diff --git a/apps/docs/images/aws/key-4.png b/apps/docs/images/aws/key-4.png new file mode 100644 index 0000000..f573c13 Binary files /dev/null and b/apps/docs/images/aws/key-4.png differ diff --git a/apps/docs/images/aws/key-5.png b/apps/docs/images/aws/key-5.png new file mode 100644 index 0000000..5c9b04b Binary files /dev/null and b/apps/docs/images/aws/key-5.png differ diff --git a/apps/docs/images/aws/key-6.png b/apps/docs/images/aws/key-6.png new file mode 100644 index 0000000..99d6471 Binary files /dev/null and b/apps/docs/images/aws/key-6.png differ diff --git a/apps/docs/images/github-callback.png b/apps/docs/images/github-callback.png new file mode 100644 index 0000000..0a32281 Binary files /dev/null and b/apps/docs/images/github-callback.png differ diff --git a/apps/docs/images/ses-settings/add-ses-settings.png b/apps/docs/images/ses-settings/add-ses-settings.png new file mode 100644 index 0000000..7d766cc Binary files /dev/null and b/apps/docs/images/ses-settings/add-ses-settings.png differ diff --git a/apps/docs/images/ses-settings/sandbox.png b/apps/docs/images/ses-settings/sandbox.png new file mode 100644 index 0000000..1c105d0 Binary files /dev/null and b/apps/docs/images/ses-settings/sandbox.png differ diff --git a/apps/docs/introduction.mdx b/apps/docs/introduction.mdx index a71e725..3bc3b7a 100644 --- a/apps/docs/introduction.mdx +++ b/apps/docs/introduction.mdx @@ -1,6 +1,7 @@ --- title: Introduction description: "Unsend is Open source alternative to Resend, Sendgrid, Mailgun and Postmark etc." +icon: rocket --- ## Setting up diff --git a/apps/docs/mint.json b/apps/docs/mint.json index 432233f..a047c1c 100644 --- a/apps/docs/mint.json +++ b/apps/docs/mint.json @@ -45,10 +45,11 @@ ], "navigation": [ { - "group": "Get Started", + "group": "Getting Started", "pages": [ "introduction", - "get-started/nodejs" + "get-started/nodejs", + "get-started/self-hosting" ] }, { diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000..43a8aa0 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,68 @@ +# Docker Setup for Unsend + +The following guide will walk you through setting up Unsend using Docker. You can choose between a production setup using Docker Compose or a standalone container. + +## Prerequisites + +Before you begin, ensure that you have the following installed: + +- Docker +- Docker Compose (if using the Docker Compose setup) + +## Option 1: Production Docker Compose Setup + +This setup includes PostgreSQL, Redis and the Unsend application. + +1. Download the Docker Compose file from the Unsend repository: [compose.yml](https://github.com/unsend-dev/unsend/blob/main/docker/prod/compose.yml) +2. Navigate to the directory containing the `compose.yml` file. +3. Create a `.env` file in the same directory. Copy the contents of `.env.selfhost.example` +4. Run the following command to start the containers: + +``` +docker-compose --env-file ./.env up -d +``` + +This will start the PostgreSQL database, Redis and the Unsend application containers. + +5. Access the Unsend application by visiting `http://localhost:3000` in your web browser. + +## Option 2: Standalone Docker Container + +If you prefer to host the Unsend application on your container provider of choice, you can use the pre-built Docker image from DockerHub or GitHub's Package Registry. Note that you will need to provide your own database and SMTP host. + +1. Pull the Unsend Docker image: + +``` +docker pull unsend/unsend +``` + +Or, if using GitHub's Package Registry: + +``` +docker pull ghcr.io/unsend-dev/unsend +``` + +2. Run the Docker container, providing the necessary environment variables for your database and SMTP host: + +``` +docker run -d \ + -p 3000:3000 \ + -e NEXTAUTH_URL="" + -e NEXTAUTH_SECRET="" + -e DATABASE_URL="" + -e REDIS_URL="" + -e AWS_ACCESS_KEY="" + -e AWS_SECRET_KEY="" + -e AWS_DEFAULT_REGION="" + -e GITHUB_ID="" + -e GITHUB_SECRET="" + unsend/unsend +``` + +Replace the placeholders with your actual database and aws details. + +1. Access the Unsend application by visiting the URL you provided in the `NEXTAUTH_URL` environment variable in your web browser. + +## Success + +You have now successfully set up Unsend using Docker. You can start sending emails efficiently. If you encounter any issues or have further questions, please refer to the official Unsend documentation or seek assistance from the community.