How to Set Up DocuSeal on Koyeb to Sign and Manage Digital Documents
Tags: opensource, tutorial, webdev, programming
Published: 2023-09-07 13:14:47

## Introduction

[DocuSeal](https://www.docuseal.co/) is an open-source document signing and management platform.  It allows you to upload PDFs and other digital documents and mark them up to define the fields and signatures needed.  Afterwards, you can send out signing requests to all relevant parties and managed the lifecycle of the signature process from within a centralized hub.  DocuSeal can be deployed to your own infrastructure and configured to use custom email messaging to make sure it fits your organization's needs.

This guide will cover how to deploy and configure a DocuSeal instance on [Koyeb](https://www.koyeb.com/) to create, sign, and organize documents for your organization.  We will use a PostgreSQL database hosted on Neon to store user information and other data.  The documents themselves will be stored in a Backblaze B2 object storage bucket.  We will configure DocuSeal to use Mailgun for mail delivery.

You can deploy and configure DocuSeal as configured in this guide using the [Deploy to Koyeb](/docs/build-and-deploy/deploy-to-koyeb-button) button below:

[![Deploy to Koyeb](https://www.koyeb.com/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=docuseal&type=docker&image=docker.io/docuseal/docuseal&env[PORT]=8000&env[DATABASE_URL]=CHANGE_ME&env[SECRET_KEY_BASE]=CHANGE_ME&ports=8000;http;/)

**Note:** Remember to replace the value of the `DATABASE_URL` environment variable with the connection URL for your own PostgreSQL database and the value of the `SECRET_KEY_BASE` variable with a long randomized string.  You can find out more about this requirement in the [deployment section](#deploy-docu-seal-to-koyeb).

## Requirements

To follow along with this guide, you will need to create accounts with the following services. Each of these services offers a free tier that you can use to get started:

- **[Koyeb](https://app.koyeb.com/):** We will use Koyeb to deploy, run, and scale the DocuSeal instance.
- **[Neon](https://www.koyeb.com/docs/integrations/databases/neon):** We will provision a PostgreSQL database with Neon to store user and configuration data.
- **[Backblaze B2](https://www.backblaze.com/cloud-storage):** We will use Backblaze's B2 object storage service to store the actual documents that DocuSeal manages.
- **[Mailgun](https://www.mailgun.com/):** We will use Mailgun to send transactional emails to users for account-related activity and document notifications.

## Steps

This guide will cover how to deploy DocuSeal to Koyeb with the following steps:

1. [Create a PostgreSQL database with Neon](#create-a-postgresql-database-with-neon)
2. [Create an object storage bucket with Backblaze B2](#create-an-object-storage-bucket-with-backblaze-b2)
3. [Set up the Mailgun SMTP service](#set-up-the-mailgun-smtp-service)
4. [Deploy DocuSeal to Koyeb](#deploy-docuseal-to-koyeb)
5. [Configure DocuSeal](#configure-docuseal)
    * [Set up the admin account](#set-up-the-admin-account)
    * [Configure object storage](#configure-object-storage)
    * [Configure SMTP for email](#configure-smtp-for-email)
    * [Test the document management workflow](#test-the-document-management-workflow)

## Create a PostgreSQL database with Neon

DocuSeal uses a relational database to store user data and configuration information.  In its default configuration, DocuSeal will use a local SQLite database to manage this information.  To ensure that our data survives across redeploys and to make it easier to scale out the execution layer, we will configure it to use an external PostgreSQL database instead.  We will use Neon for this to take advantage of their free tier.

To create a new PostgreSQL database, log into your [Neon account](https://console.neon.tech/sign_in). In the Neon console, follow these steps:

1. In the **Projects** section, click the **Create a project** link on the bottom of the page.
2. Choose a name for your PostgreSQL database. We will use `docuseal` for this guide.
3. Leave the version to the default selection (15 at the time of writing).
4. Select the region to deploy your database. In this guide, we will select "Europe (Frankfurt)" to demonstrate deploying resources in Europe, but you should choose the region closest to your users.
7. Click the **Create project** button to begin provisioning your new database.

The following screen will show the connection details for your new database.  Click on the copy icon associated with the `psql` connection string to copy it and save it to a safe place for later reference.  We will use this value when we configure DocuSeal so that it can connect to and authenticate with the database.

## Create an object storage bucket with Backblaze B2

Like the information stored in the database, by default, DocuSeal will attempt to store uploaded documents locally.  Since the local disk space attached to our DocuSeal instance will be ephemeral, we need to keep our documents somewhere more persistent.  For this, we'll use an object storage bucket provided by Backblaze B2.

To create an object storage bucket for DocuSeal, log into your [Backblaze account](https://secure.backblaze.com/user_signin.htm) and follow these steps:

1. In the **B2 Cloud Storage** section on the left side of the dashboard, click **Buckets**.
2. Click **Create a Bucket** to begin configuring a new bucket.
3. Choose a name for the bucket.  This must be globally unique, so choose a name not likely to be used by another user.
4. Set the bucket privacy to **Private**.
5. **Enable** the default encryption.  This will help protect sensitive documents in storage.
5. Choose to **Disable** the object lock.  This feature, while useful, would prevent some of the document management capabilities we want DocuSeal to have.
6. Click **Create a Bucket** to create the new bucket.

Copy and save the following information about your new bucket.  You'll need it later to configure DocuSeal:

| Backblaze B2 item | DocuSeal field | Example value                       |
|-------------------|----------------|-------------------------------------|
| Bucket name       | Bucket         | `some-bucket-name`                  |
| Endpoint          | Endpoint       | `s3.eu-central-003.backblazeb2.com` |

Now that you have a bucket, you need to create API credentials so that DocuSeal can authenticate to Backblaze as well as upload and manage documents:

1. In the **Account** section on the left side of the dashboard, click **Application Keys**.
2. Under **Your Application Keys**, click **Add a New Application Key** to begin configuring a new key.
3. Select a name for your key to help you identify it more easily.
4. Select the bucket you just created in the **Allow access to Bucket(s)** drop-down menu.
5. Select **Read and Write** as the access type.
6. Leave the remaining fields blank to accept the default policies.
7. Click **Create New Key** to generate the new key to manage your bucket.

Copy and save the following information related to your new API key.  You'll need it to properly authenticate to your Backblaze account and perform object operations:

| Backblaze B2 item | DocuSeal field    | Example value                     |
|-------------------|-------------------|-----------------------------------|
| `keyID`           | Access key ID     | `008c587cb98cb3d0000000003`       |
| `applicationKey`  | Secret access key | `K002cbYLV/CkW/x+28zsqmpbIAtdzMM` |


## Set up the Mailgun SMTP service

Next, you need to copy the SMTP information for your Mailgun account. DocuSeal uses email to perform account-related messages and for notifications about document changes.

To begin, log into your [Mailgun account](https://login.mailgun.com/login/). In the side navigation pane, open the **Sending** menu. Next, click the **Overview** sub-menu item.

Mailgun offers sandbox domains to test its functionality.  These are useful, but restricted to sending emails only to previously authorised email addresses.  We can use this to test the mail delivery with DocuSeal for free.  On the right sidebar of the Overview page, enter the email address you want to send test emails to in **email address** input field of the **Authorized Recipients** section and click the **Save Recipient** button.

Mailgun will send a verification email to the provided address. In the verification email, click the **I Agree** button to complete the authorisation process.  If you refresh the page in Mailgun, you see that the target email address is now marked as verified.

From this same page, click the **Select** box associated with "SMTP" to see the information you need to send email using your Mailgun account.  The information related to using SMTP with your Mailgun account will be displayed.  Copy and save the following information:

| Mailgun SMTP info | DocuSeal Email field             | Example                                                          |
|-------------------|----------------------------------|------------------------------------------------------------------|
| SMTP hostname     | Host                             | `smtp.mailgun.org`                                               |
| Username          | "Username" and "Send from Email" | `postmaster@sandboxbac59f0e6dac45cdab38e53aee4e1363.mailgun.org` |
| Password          | Password                         | `e627704d99111f00c7aedf3805961383-262b123e-66b6979f`             |

**Note:** Mailgun displays port 587 as the recommended port.  However, because of the authentication DocuSeal uses, we'll use the alternative port 465 when configuring the service instead.

## Deploy DocuSeal to Koyeb

With the database connection string in hand, you can now deploy DocuSeal to Koyeb.

Start by logging into your [Koyeb account](https://app.koyeb.com/auth/signin). Follow these steps to deploy the default [DocuSeal container image](https://hub.docker.com/r/docuseal/docuseal) to the platform:

1. Click the **Create App** button on the [Koyeb console](https://app.koyeb.com/).
2. Select **Docker** as your deployment method.
3. Set the **Image** to `docker.io/docuseal/docuseal`. Leave the **Tag** blank to pull the latest image or select the [image tag](https://hub.docker.com/r/docuseal/docuseal/tags) you'd like to deploy.
4. Click the **Advanced** button to view additional settings.
5. In the **Environment variables** section, click the **Add Variable** button to add the following variables:
    * `DATABASE_URL`: set to the connection URI you copied from Neon.
    * `SECRET_KEY_BASE`: set to a unique random string.  You can generate a string locally with OpenSSL by running `openssl rand -hex 64` locally.  This same string needs to be set for redeployments or replicas to work correctly.
6. Set the **App name** to your choice.
7. Click the **Deploy** button.

Koyeb will pull the DocuSeal container image from Docker Hub and use it to provision a new container. The DocuSeal application will start up, connect to and initialize the database, and begin listening on the port specified in the configuration.

## Configure DocuSeal

Once DocuSeal is up and running, you can visit your Koyeb Service's subdomain (you can find this on your Service's page) to connect. It will have the following format:

```
https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app
```

### Set up the admin account

When you visit DocuSeal's URL, you will be redirected to an account creation page.

Fill out the form with your own information.  For the "App URL" field, enter your Koyeb Service's subdomain that you are using to access DocuSeal.  It will have the same format listed above:

![DocuSeal sign up page](https://www.koyeb.com/static/images/tutorials/docuseal/account_creation_page.png)

Click **Submit** when you are finished.

Next, you'll have the option to sign up for email updates about the DocuSeal project:

![DocuSeal email updates](https://www.koyeb.com/static/images/tutorials/docuseal/sign_up_for_updates.png)

Either enter your email and click **Submit** or click **Skip** to continue.

You'll be dropped into the initial DocuSeal welcome page:

![DocuSeal welcome page](https://www.koyeb.com/static/images/tutorials/docuseal/welcome_page.png)

Now that we have an account, we can begin configuring DocuSeal.

### Configure object storage

First, we need to configure DocuSeal to store all of its documents and other files in our object storage bucket.

In the upper-right corner, click **Settings** to access the configuration pages.  In the left-hand menu, click **Storage** to continue:

![DocuSeal initial storage page](https://www.koyeb.com/static/images/tutorials/docuseal/initial_storage_page.png)

Since Backblaze B2 is an AWS S3-compatible object storage implementation, click on the **AWS** option.

Configure the object storage by filling out the following information taken from your Backblaze account.  See the notes that follow for specific information you'll need to know:

| DocuSeal field    | Backblaze B2 item | Example value                               |
|-------------------|-------------------|---------------------------------------------|
| Access key ID     | `keyID`           | `008c587cb98cb3d0000000003`                 |
| Secret access key | `applicationKey`  | `K002cbYLV/CkW/x+28zsqmpbIAtdzMM`           |
| Region            | (not used)        | `any-string`                                |
| Bucket            | Bucket name       | `some-bucket-name`                          |
| Endpoint          | Endpoint          | `https://s3.eu-central-003.backblazeb2.com` |

**Note 1:** For the "Endpoint" value, you need to prepend `https://` to the value copied from the Backblaze dashboard.

**Note 2:** While Backblaze B2 can be used in different regions (you must select this during original account creation), it doesn't use those designations for bucket addressing (it is built directly into the endpoint name instead).  This field is marked as required, so enter any dummy string to continue.

![DocuSeal configured storage page](https://www.koyeb.com/static/images/tutorials/docuseal/configured_storage_page.png)

When you are finished entering the information about your Backblaze B2 bucket, click **Save** to continue.

### Configure SMTP for email

Next, configure email by clicking the **Email** item in the left-hand menu.

Fill in the following information using the information from your Mailgun account:

| DocuSeal Email field | Mailgun SMTP info       | Example                                                          |
|----------------------|-------------------------|------------------------------------------------------------------|
| Host                 | SMTP hostname           | `smtp.mailgun.org`                                               |
| Port                 | 465 (587 does not work) | 465                                                              |
| Username             | Username                | `postmaster@sandboxbac59f0e6dac45cdab38e53aee4e1363.mailgun.org` |
| Send from Email      | Username                | `postmaster@sandboxbac59f0e6dac45cdab38e53aee4e1363.mailgun.org` |
| Password             | Password                | `e627704d99111f00c7aedf3805961383-262b123e-66b6979f`             |

**Note 1:** As mentioned earlier, Mailgun displays port 587 as the recommended port, but because of the authentication DocuSeal uses, we'll use the alternative port 465 when configuring the service instead.

**Note 2:** We are using a Mailgun sandbox domain for testing which can only send to authorized email addresses.  At the time of writing, when the SMTP information is saved, DocuSeal will show the following message:

```
could not get 3xx (421: 421 Domain sandbox<SANDBOX_ID>.mailgun.org is not allowed to send:
Free accounts are for test purposes only. Please upgrade or add the address to authorized
recipients in Account Settings. )
```

While this indicates that something went wrong, test emails to the authorized account will still be sent successfully.  You can safely ignore this message.

![DocuSeal configured email page](https://www.koyeb.com/static/images/tutorials/docuseal/configured_email_page.png)

Click **Save** when you are finished.

## Test the document management workflow

Now that DocuSeal is configured, we can begin to test the features and demonstrate the document workflow.

Click the main **DocuSeal** logo in the upper left corner to go to the main welcome page.

Click **Create Template** to begin configuring your first document template:

![DocuSeal choose template name](https://www.koyeb.com/static/images/tutorials/docuseal/choose_template_name.png)

Choose a name for your template and click **Create**.

On the following page, you can begin to configure your first PDF template:

![DocuSeal template configuration](https://www.koyeb.com/static/images/tutorials/docuseal/template_configuration.png)

Click **Add PDF documents or images** to upload your first form.  As an example, we'll use the [US tax withholding certificate (form W-4)](https://www.irs.gov/pub/irs-pdf/fw4.pdf) published by the IRS.  Select the file with your browser's file selector and upload it to begin.

The form will be uploaded and rendered in the template configuration window:

![DocuSeal template uploaded](https://www.koyeb.com/static/images/tutorials/docuseal/template_uploaded.png)

You can begin to define the fields that should be filled out by selecting the **Text** field type in the right-hand menu.  A new field label will appear above the field types with the default label "Text Field 1".

Click the associated pencil icon to update the field label and then click the box icon to draw a box on the PDF that corresponds with the field content:

![DocuSeal text field example](https://www.koyeb.com/static/images/tutorials/docuseal/text_field_example.png)

Try out another few form field types like the signature and date field:

![DocuSeal signature and date example](https://www.koyeb.com/static/images/tutorials/docuseal/signature_and_date_example.png)

Click **Save** when you are finished.  You will be taken to the template management page for the PDF form you just configured.  It will indicate that no one has filled out the form yet:

![DocuSeal no submissions](https://www.koyeb.com/static/images/tutorials/docuseal/no_submissions.png)

Click **Submit it yourself** to test your new form.  On the next page, fill in the email address you authorized through Mailgun and click **Start**:

![DocuSeal fill in authorized email](https://www.koyeb.com/static/images/tutorials/docuseal/fill_in_authorized_email.png)

You will then be tasked with filling out the form that you just configured:

![DocuSeal fill out the form](https://www.koyeb.com/static/images/tutorials/docuseal/fill_out_the_form.png)

Fill in the fields using the helper window.  If you selected the appropriate field types during creation, the fields will have helpful widgets like date selectors and signature upload forms when they are active.

When you are finished with the last field, click **Submit** to save your filled out form to DocuSeal.

You will have the option to download a copy of your form or send it to yourself in an email:

![DocuSeal download or email form](https://www.koyeb.com/static/images/tutorials/docuseal/download_or_email_form.png)

Click **Send copy via email** to test out DocuSeal's email functionality.

Check the account of the email address you sent to (including the spam folder since we're using a sandbox domain) to verify that the email was delivered successfully.  You might also see an email from DocuSeal notifying you that someone filled out the form:

![DocuSeal successful email](https://www.koyeb.com/static/images/tutorials/docuseal/successful_email.png)

This tells us that the SMTP configuration is correct and that delivery is working as expected.

## Conclusion

In this guide, we deployed a DocuSeal instance backed by a Neon PostgreSQL database to Koyeb. We configured DocuSeal to upload all documents and other files to a Backblaze B2 object storage bucket and configured SMTP email with a Mailgun account.  Once the configuration was complete, we tested the file upload functionality, template creation mechanics, and mail delivery.

As you continue to test out your new DocuSeal environment, take some time to verify that the documents you're uploading are being uploaded into your bucket and that they are available if you redeploy your DocuSeal instance.  By decoupling the data from the processing components, you're able to easily recover from failures and scale out your deployment without additional effort.  Furthermore, since Koyeb fetches the container image directly from Docker Hub, upgrading your DocuSeal instance is only a redeploy away.