Setting up DocMost with Amazon SES SMTP using Docker Compose

If you're setting up DocMost with Docker and need to configure email functionality, you'll probably want to use a reliable SMTP service. Amazon SES (Simple Email Service) is an excellent choice for this, as it's cost-effective, reliable, and integrates well with other AWS services.

In this guide, I'll walk you through the entire process of setting up Amazon SES as your SMTP provider for DocMost running in Docker containers.

What you'll need

Before we start, make sure you have:

• An AWS account with appropriate permissions
• Docker and Docker Compose installed
• A domain you own (for email sending verification)
• Basic familiarity with AWS console

Step 1: Setting up Amazon SES

Navigate to Amazon SES

First, log into your AWS console and navigate to Amazon SES. You can find it by searching for "SES" in the services search bar, or under the "Customer Engagement" section.

Verify your email domain

Before you can send emails through SES, you need to verify your domain or email address.

1. In the SES console, go to Configuration → Verified identities
2. Click Create identity
3. Choose Domain if you want to send from any email address on your domain, or Email address for a specific email
4. Enter your domain name (e.g., example.com)
5. Follow the verification process by adding the required DNS records to your domain

Note: If you're just testing, you can verify a single email address instead, but for production use, verifying the entire domain is recommended.

Request production access (if needed)

By default, SES starts in "sandbox mode," which means you can only send emails to verified email addresses. For production use, you'll need to request production access:

1. In the SES console, go to Account dashboard
2. If you see "Your account is in the Amazon SES sandbox," click Request production access
3. Fill out the form explaining your use case
4. Wait for approval (usually takes 24-48 hours)

Step 2: Create SMTP credentials

Now we need to create the actual SMTP credentials that DocMost will use.

Generate SMTP credentials

1. In the SES console, go to Configuration → SMTP settings
2. Click Create SMTP credentials
3. Enter a username for the credentials (e.g., docmost-smtp)
4. Click Create user
5. Important: Download the credentials immediately! You won't be able to see the password again

Your SMTP credentials will look something like this:

SMTP Username: AKIAIOSFODNN7EXAMPLE
SMTP Password: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Note the SMTP endpoint

On the same SMTP settings page, you'll see the SMTP endpoint for your AWS region. It will look like:

• email-smtp.us-east-1.amazonaws.com (for US East)
• email-smtp.eu-west-1.amazonaws.com (for EU West)
• And so on for other regions

The port will typically be 587 for STARTTLS or 465 for SSL/TLS.

Step 3: Configure your Docker Compose file

Now we need to configure DocMost to use these credentials. Here's how your docker-compose.yml should look:

version: '3.8'

services:
  docmost:
    image: docmost/docmost:latest
    depends_on:
      - db
      - redis
    environment:
      APP_URL: "http://localhost:3000"
      APP_SECRET: "your-secret-key-here"
      DATABASE_URL: "postgresql://docmost:STRONG_DB_PASSWORD@db:5432/docmost"
      REDIS_URL: "redis://redis:6379"

      # Email configuration
      MAIL_DRIVER: smtp
      SMTP_HOST: email-smtp.us-east-1.amazonaws.com
      SMTP_PORT: 587
      SMTP_USERNAME: AKIAIOSFODNN7EXAMPLE
      SMTP_PASSWORD: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
      SMTP_SECURE: "true"
      MAIL_FROM_ADDRESS: [e-mail]
      MAIL_FROM_NAME: Docmost
    ports:
      - "3000:3000"
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: docmost
      POSTGRES_USER: docmost
      POSTGRES_PASSWORD: STRONG_DB_PASSWORD
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    restart: unless-stopped

volumes:
  db_data:

Using environment variables (recommended)

Instead of hardcoding credentials in your docker-compose.yml, it's much better to use a .env file:

Create a .env file in the same directory as your docker-compose.yml:

# App configuration
APP_URL=http://localhost:3000
APP_SECRET=your-secret-key-here
DATABASE_URL=postgresql://docmost:STRONG_DB_PASSWORD@db:5432/docmost
REDIS_URL=redis://redis:6379

# Email configuration
MAIL_DRIVER=smtp
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=AKIAIOSFODNN7EXAMPLE
SMTP_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
SMTP_SECURE=true
MAIL_FROM_ADDRESS=[e-mail]
MAIL_FROM_NAME=Docmost

# Database
POSTGRES_DB=docmost
POSTGRES_USER=docmost
POSTGRES_PASSWORD=STRONG_DB_PASSWORD

Then update your docker-compose.yml to use these variables:

version: '3.8'

services:
  docmost:
    image: docmost/docmost:latest
    depends_on:
      - db
      - redis
    environment:
      APP_URL: ${APP_URL}
      APP_SECRET: ${APP_SECRET}
      DATABASE_URL: ${DATABASE_URL}
      REDIS_URL: ${REDIS_URL}
      MAIL_DRIVER: ${MAIL_DRIVER}
      SMTP_HOST: ${SMTP_HOST}
      SMTP_PORT: ${SMTP_PORT}
      SMTP_USERNAME: ${SMTP_USERNAME}
      SMTP_PASSWORD: ${SMTP_PASSWORD}
      SMTP_SECURE: ${SMTP_SECURE}
      MAIL_FROM_ADDRESS: ${MAIL_FROM_ADDRESS}
      MAIL_FROM_NAME: ${MAIL_FROM_NAME}
    ports:
      - "3000:3000"
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    restart: unless-stopped

volumes:
  db_data:

Step 4: Understanding the configuration

Let me explain what each environment variable does:

• MAIL_DRIVER: Set to smtp to use SMTP for sending emails
• SMTP_HOST: The Amazon SES SMTP endpoint for your region
• SMTP_PORT: Usually 587 for STARTTLS or 465 for SSL/TLS
• SMTP_USERNAME: The SMTP username you got from SES
• SMTP_PASSWORD: The SMTP password you got from SES
• SMTP_SECURE: Set to true to enable TLS encryption
• MAIL_FROM_ADDRESS: The email address emails will be sent from (must be verified in SES)
• MAIL_FROM_NAME: The display name for outgoing emails

Step 5: Start your containers

Now you can start your DocMost instance:

docker-compose up -d

Check the logs to make sure everything started correctly:

docker-compose logs docmost

Step 6: Test email functionality

Once DocMost is running, you can test the email functionality by:

1. Creating a new user account (this should send a welcome email)
2. Using the password reset feature
3. Inviting other users to your workspace

If emails aren't being sent, check the DocMost logs for any SMTP-related error messages.

Troubleshooting common issues

"Username/Password incorrect" errors

Double-check that you're using the SMTP credentials (not your AWS console credentials) and that you've copied them correctly from the SES console.

"Email address not verified" errors

Make sure the email address in MAIL_FROM_ADDRESS is either:

• An email address you've verified individually in SES, or
• An email address on a domain you've verified in SES

Connection timeout errors

Check that:

• Your SMTP_HOST matches your AWS region
• Your SMTP_PORT is correct (587 or 465)
• Your network allows outbound connections on the SMTP port

Still in sandbox mode

If you're trying to send emails to unverified addresses and getting bounces, you might still be in SES sandbox mode. Either verify the recipient email addresses or request production access.

Security considerations

A few important security notes:

1. Never commit credentials to version control: Always use .env files and add them to your .gitignore
2. Use IAM roles when possible: If you're running on EC2, consider using IAM roles instead of SMTP credentials
3. Rotate credentials regularly: SES SMTP passwords don't expire, but it's good practice to rotate them periodically
4. Monitor your usage: Keep an eye on your SES usage and set up billing alerts

Conclusion

Setting up DocMost with Amazon SES provides you with a reliable, scalable email solution. The SMTP configuration is straightforward once you have your SES credentials, and using Docker Compose with environment variables keeps your setup clean and secure.

The main thing to remember is that SES requires domain or email verification before you can send emails, and you'll need to request production access if you want to send to unverified email addresses.

Once everything is configured, DocMost will be able to send welcome emails, password reset emails, and notifications to keep your team informed and engaged with your documentation platform.

Disclaimer: AI was used to reformat this article and correct errors

Comments

[Nathan Tarbert]

pretty cool seeing all the smtp steps laid out so clearly, honestly makes me think about all the config mistakes i’ve made in the past lmao you think keeping stuff like credentials secure ever gets easier or is it always something people slip up on

[Parag Nandy Roy]

Super helpful guide.....SES setup can be a pain

[Dotallio]

Really appreciate how you broke down the whole process, especially the troubleshooting tips.
Have you run into any tricky SES sandbox issues and found workarounds?

[Alessio Michelini]

Well for testing is fine to use sandbox, the only annoying thing is that for every email you need to use, they have to be added to the sandbox as well.
At the end I just asked for production access, it's fairly straight forward process as long the usage is well defined and you explain to somebody in AWS what you need to do