Installation

General

While the general functionalities are stable, there may be breaking changes nonetheless. If you need to archive your emails for a critical purpose, it is not recommended to solely rely on this application.

The docker image comes with a SSL certificate issued and signed by the Eonvelope project. It ensures safe communication between your server and your reverse proxy as well as within your local network.

Note

The SSL certificate is a different one for every version of Eonvelope.

It is not safe or intended for use on the open web.

Therefore, do not expose this application to the web without a reverse proxy like nginx. Further details on this can be found in the reverse-proxy section below.

Recommended

The project is intended to be run with the container image provided at dockerhub.

The Eonvelope service mounts 2 volumes, one for the logfiles of Eonvelope and one for the files that Eonvelope archives.

Note

You can also mount all logfiles of the container by changing the path in the docker-compose.yml to /var/log. In that case you will have to give the directory 777 permissions, otherwise services will fail to start and log properly.

It is recommended to use the minimal version of the docker-compose for the first time you deploy Eonvelope and to skim the docker settings section of the configuration reference beforehand.

In all container management systems you need to change at least the following variables:

• Change the passwords on both the db and web container and make sure they match each other

• Set a random sequence of characters for the SECRET_KEY

• Add your servers address to the ALLOWED_HOSTS list.

Then you can spin Eonvelope up.

Important

Also keep in mind that Eonvelope is only accessible via https, you will get a cryptic browser error if you try to access via bare http.

Docker

There are example compose-files in the docker directory of the repository, to install for the first time we recommend the minimal version.

If your system is low-spec and quite limited in its resources, use the slim version. This has slim mode enabled, which reduces the resources Eonvelope consumes at runtime.

Take the docker-compose of your choice, adapt it to your needs and start the stack with docker compose up -d or via your container manager. Done!

Podman

Just do the same thing as above, just with podman instead of docker.

Kubernetes

There are two example kubernetes setup in the docker/kubernetes directory of the repository. One is a minimal version with only the basic setup and configuration. The other is a full setup with all environment level configurations. Take one of them, adapt and launch it, for example via minikube.

Agentic installation

If you want to outsource installation to a LLM, point it to the install.md file which holds a prompt outlining the installation process for docker.

curl -fsSL https://github.com/dacid99/eonvelope/blob/master/install.md | claude

For more details, see [the page introducing the concept of a install.md file](https://www.mintlify.com/blog/install-md-standard-for-llm-executable-installation).

Advanced

Alternatively, you can run the application bare metal.

1. Clone the repository.

2. Install the dependencies for python and the system as described in development.

3. Spin up a mysql db server matching the configurations in the django application settings config.settings.py on your machine.

4. Finally the Eonvelope server is started via the docker entrypoint script docker/docker-compose.yml.

Other Database Type

Depending on your setup, you may want to use a database that is not a mariadb.

In that case you can set the type of database you want to use in the docker-compose.yml file using the DATABASE_TYPE environment variable. See Configuration for more details on this.

Important

It is crucial that the name of the database service in the stack is matches the DATABASE_HOST env setting! The default is db. Otherwise the connection from the Eonvelope container to the database will fail.

External Database

If you use docker, you can set Eonvelope up to use an external database by adding

extra_hosts:
  - "db: <database_ip>"

to the eonvelope-web service and omitting the db portion of the stack.

Note

Using a database other than the default mysql can lead to issues. If possible try to stick with the default, which is tested and guaranteed to work flawlessly.

In case your centralized database and eonvelope-web share a docker-network, you can simply set the DATABASE_HOST environment variable to match that database containers hostname. You can find more details on this in the configuration page

Known quirks

If you use an external database for Eonvelope, that may cause some sideeffects as some tables may not be properly set up. This is a list of known issues that have been reported and their solution.

Timezone table of mariadb not installed, causing issues with datetime values in Eonvelope.

Open a shell to the container and run

mariadb-tzinfo-to-sql /usr/share/zoneinfo | mariadb -u root mysql

For more details see the django docs on this subject.

Reverse-Proxy

If you reverse-proxy or expose your Eonvelope instance another way, you must make sure that the prometheus endpoint /metrics is not exposed for the entire world to see!

Just add

location /metrics {
   return 403;   # or 404
}

to your nginx config.

Note

Make sure to add the address to the ALLOWED_HOSTS environment variable in the docker-compose file.

Updating

You can update your Eonvelope server by getting and deploying the latest version from dockerhub.

Database Migrations

If there are structural changes to the database of Eonvelope, these changes will be implemented and mitigated by migrations applied before the Eonvelope container starts. This ensures continuity of the data. Sometimes there are changes that may not be easy to mitigate with a migration alone. In that case a script for this purpose to be applied manually in the Eonvelope will be supplied.

It can be run from the terminal of your server with

docker exec -it eonvelope-web python3 manage.py runscript scriptname

Swap in the name of the specific script for the migration fix. Just the name is required, drop the .py suffix. If your containers have different names, you may have to exchange the eonvelope-web part.

For more details see the django docs on this topic.

Note

If you are migrating from version 0.2.0 or lower to a version above 0.2.0, you will have to add an adminer container (see the docker-compose.debug.yml for reference) to the stack and change the app column of all rows in the migrations table that have emailkasten as value to eonvelope.

Migration

To New Server

If you already have a running Eonvelope instance and want to move it to a new server there are 4 steps you can go through to do so in a save manner.

1. Locate and docker volumes of all containers in the docker stack in the old servers storage.

2. Copy these complete folders to the new server to the locations of the volumes on the new server.

3. Copy the docker compose from the old server setup to the new server and adjust the volume paths if necessary. Do not change the passwords and secret key!

4. Start the stack. Done.

From Other Service

In principle it is possible to migrate to Eonvelope from another service fetching emails. The main part is required for this is a migration that rewrites that services database into one compatible with Eonvelope.

If you are interested in providing such a program for the application you are using right now, please get in touch!

Alternatively, you can also export all emails from the other application and import them into Eonvelope. The import supports various formats for collections of emails, including the popular mbox format. For details please refer to the instructions.