Skip to content

Commit

Permalink
update containers docs
Browse files Browse the repository at this point in the history
  • Loading branch information
adamcooke committed Mar 5, 2024
1 parent 22cdd49 commit 597158c
Showing 1 changed file with 5 additions and 21 deletions.
26 changes: 5 additions & 21 deletions content/5.other/2.containers.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,18 @@ Postal is packaged and hosted at `ghcr.io/postalserver/postal`.

The `latest` tag will always track the `main` branch within the repository and therefore will have the latest copy of the application. It is not recommended to use this tag in production because you may start using it at any time without noticing.

Each version of Postal will also be tagged, for example, `2.0.0`. We always recommend using a version tag in production. To upgrade, you simply need to start using the newer version of the container and be sure to run the `upgrade` command. You can view all the tags which exist [on GitHub](https://github.com/postalserver/postal/pkgs/container/postal) and in [our CHANGELOG](https://github.com/postalserver/postal/blob/main/CHANGELOG.md).
Each version of Postal will also be tagged, for example, `3.0.0`. We always recommend using a version tag in production. To upgrade, you simply need to start using the newer version of the container and be sure to run the `upgrade` command. You can view all the tags which exist [on GitHub](https://github.com/postalserver/postal/pkgs/container/postal) and in [our CHANGELOG](https://github.com/postalserver/postal/blob/main/CHANGELOG.md).

## What processes need to run?

There are 5 processes that need to be running for a successful Postal installation. All processes are run within the same image (`ghcr.io/postalserver/postal`). The table below identifies the processes.
There are 3 processes that need to be running for a successful Postal installation. All processes are run within the same image (`ghcr.io/postalserver/postal`). The table below identifies the processes.

### The web server

- **Command:** `postal web-server`
- **Ports:** 5000

This is the main web server that handles all web traffic for Postal's admin interface and open/click tracking requests. By default, it listens on port 5000 but this can be configured in the `postal.yml` file by changing the `web_server.port` option.
This is the main web server that handles all web traffic for Postal's admin interface and open/click tracking requests. By default, it listens on port 5000 but this can be configured in the `postal.yml` file by changing the `web_server.default_port` option or setting the `PORT` environment variable.

You can run multiple web servers and load balance between them to add additional capacity for web requests.

Expand All @@ -32,7 +32,7 @@ You can run multiple web servers and load balance between them to add additional
- **Ports:** 25
- **Capabilities required:** `NET_BIND_SERVICE`

This is the main SMTP server for receiving messages from clients and other MTAs. As with the web server, you can configure this to run on any port by changing the `smtp_server.port` option in the `postal.yml` config file.
This is the main SMTP server for receiving messages from clients and other MTAs. As with the web server, you can configure this to run on any port by changing the `smtp_server.default_port` option in the `postal.yml` config file or setting the `PORT` environment variable.

You can run multiple SMTP servers and load balance between them to add additional capacity for SMTP connections.

Expand All @@ -42,25 +42,9 @@ You can run multiple SMTP servers and load balance between them to add additiona

This runs a worker which will receive jobs from the message queue. Essentially, this handles processing all incoming and outgoing e-mail. If you're needing to process lots of e-mails, you may wish to run more than one of these. You can run as many of these as you wish.

### The cron

- **Command:** `postal cron`

**There must only be one of these running.** It will automatically create jobs at appropriate times in order to handle scheduled actions. Running more of these will not increase the capacity of your system. Running none of them will cause many problems.

### The message re-queuer

- **Command:** `postal requeuer`

**There must only be one of these running.** This process monitors the queues and ensures that messages that need to be retried are re-added to the message queue at the appropriate times. Like the cron, do not run more than one of these processes.

::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
Be sure to configure your system to only allow a single <code>cron</code> and <code>requeuer</code> process to be running at the same time.
::

## Configuration

The image expects all configuration to be mounted at `/config`. At a minimum, this directory must contain a `postal.yml` and a `signing.key`. You can see an example `postal.yml` in the [installation tool repository](https://github.com/postalserver/install/blob/main/examples/postal.yml).
The image expects all configuration to be mounted at `/config`. At a minimum, this directory must contain a `postal.yml` and a `signing.key`. You can see a minimal example `postal.yml` in the [installation tool repository](https://github.com/postalserver/install/blob/main/examples/postal.v3.yml). For a full example, [see here](https://github.com/postalserver/postal/blob/main/doc/config/yaml.yml).

The `signing.key` can be generated using the following command:

Expand Down

0 comments on commit 597158c

Please sign in to comment.