Ferdi Server

Stack

Messenger

Ferdi is a messaging browser that allows you to combine your favourite messaging services into one application

Image details

Pulls: 1.1M

Architecture: amd64, arm64

Image size: 79 MB

Latest: 1.3

User: getferdi

Created: Oct 01, 2019

Updated: 4 years ago

Status: active

Configuration

Type

Compose

Platform

linux

Image

getferdi/ferdi-server

Ports

3333:3333

Volumes

/data : ferdi-database-vol/app/recipes : ferdi-recipes-vol

Env vars

NODE_ENV=developmentEXTERNAL_DOMAIN=localhostDB_CONNECTION=sqliteDB_HOST=127.0.0.1DB_PORT=3306DB_USER=rootDB_PASSWORD=passwordDB_DATABASE=ferdiDB_SSL=falseMAIL_CONNECTION=smtpSMPT_HOST=127.0.0.1SMTP_PORT=2525MAIL_SSL=falseMAIL_USERNAME=usernameMAIL_PASSWORD=passwordMAIL_SENDER=noreply@getferdi.comIS_CREATION_ENABLED=trueIS_DASHBOARD_ENABLED=trueIS_REGISTRATION_ENABLED=trueCONNECT_WITH_FRANZ=falseDATA_DIR=/dataPUID=1000PGID=1000

Restart

unless-stopped

Source

Repo

Template by xneo1·Source

Standalone Install

Select an install method, to see config/commands for deploying Ferdi Server

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

Ensure both Docker and Portainer are installed, and up-to-date
Log into your Portainer web UI
Under Settings → App Templates, paste the below URL
Head to Home → App Templates, and the list of apps will show up
Select Ferdi Server, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json

Show Me

Original stackfile

The compose file this template deploys, straight from its repo:

services:
  ferdi-server:
    image: getferdi/ferdi-server
    container_name: ferdi-server
    environment:
      - NODE_ENV=development
      - EXTERNAL_DOMAIN=localhost
      - DB_CONNECTION=sqlite
      - DB_HOST=127.0.0.1
      - DB_PORT=3306
      - DB_USER=root
      - DB_PASSWORD=password
      - DB_DATABASE=ferdi
      - DB_SSL=false
      - MAIL_CONNECTION=smtp
      - SMPT_HOST=127.0.0.1
      - SMTP_PORT=2525
      - MAIL_SSL=false
      - MAIL_USERNAME=username
      - MAIL_PASSWORD=password
      - MAIL_SENDER=noreply@getferdi.com
      - IS_CREATION_ENABLED=true
      - IS_DASHBOARD_ENABLED=true
      - IS_REGISTRATION_ENABLED=true
      - CONNECT_WITH_FRANZ=false
      - DATA_DIR=/data
      - PUID=1000
      - PGID=1000
    volumes:
      - ferdi-database-vol:/data
      - ferdi-recipes-vol:/app/recipes
    ports:
      - 3333:3333
    restart: unless-stopped
volumes:
  ferdi-database-vol:
  ferdi-recipes-vol:

Or deploy it directly from the source:

git clone https://github.com/xneo1/portainer_templates
cd portainer_templates
docker compose -f Template/Stack/ferdiserver.yml up -d

More install options in our documentation.

Ferdi-server-docker

Ferdi is a hard-fork of Franz, adding awesome features and removing unwanted ones. Ferdi-server is an unofficial replacement of the Franz server for use with the Ferdi Client.
This is a dockerized version of Ferdi-server running on Alpine Linux and Node.js (v10.16.3).

Why use a custom Ferdi-server?

A custom Ferdi-server allows you to experience the full potential of the Ferdi Client. It allows you to use all Premium features (e.g. Workspaces and custom URL recipes) and add your own recipes.

Features

x User registration and login
x Service creation, download, listing and removing
x Workspace support
x Functioning service store
x User dashboard
x Password recovery
x Export/import data to other Ferdi-servers
Recipe update

Installation & Setup

Here are some example snippets to help you get started creating a container.
The docker can be run as is, with the default sqlite database, or you can modify your environment variables to use an external database (e.g. MySQL, MariaDB, Postgres, etc). After setting up the docker container you will need to create a reverse proxy to access Ferdi-server outside of your home network, using a webserver such as NGINX.
Existing users, please note: The latest updates to Ferdi-server and the Ferdi-server Docker image introduce changes to the default SQLite database name and location, as well as the internal container port. The new container port is 3333. If you would like to keep your existing SQLite database, you will need to add the DATA_DIR variable and change it to /app/database, to match your existing data volume. You will also need to change the DB_DATABASE variable to development to match your existing database. Please see the parameters in the Migration section below.

docker

Pull the docker image:

docker pull getferdi/ferdi-server

To create the docker container with the proper parameters:

docker create \
  --name=ferdi-server \
  -e NODE_ENV=development \
  -e EXTERNAL_DOMAIN=<ferdi-serverdomain> \
  -e DB_CONNECTION=<database> \
  -e DB_HOST=<yourdbhost> \
  -e DB_PORT=<yourdbport> \
  -e DB_USER=<yourdbuser> \
  -e DB_PASSWORD=<yourdbpass> \
  -e DB_DATABASE=<yourdbdatabase> \
  -e DB_SSL=false \
  -e MAIL_CONNECTION=smtp \
  -e SMPT_HOST=<smtpmailserver> \
  -e SMTP_PORT=<smtpport> \
  -e MAIL_SSL=true/false \
  -e MAIL_USERNAME=<yourmailusername> \
  -e MAIL_PASSWORD=<yourmailpassword> \
  -e MAIL_SENDER=<sendemailaddress> \
  -e IS_CREATION_ENABLED=true \
  -e IS_DASHBOARD_ENABLED=true \
  -e IS_REGISTRATION_ENABLED=true \
  -e CONNECT_WITH_FRANZ=true \
  -e DATA_DIR=/data \
  -p <port>:3333 \
  -v <path to data>:/data \
  -v <path to recipes>:/app/recipes \
  --restart unless-stopped \
  getferdi/ferdi-server

docker-compose

You can use the provided sample docker-compose.yml if you are happy with the default environmental variables. This will pull the latest image from Docker Hub or use a local copy of the image which you can build using the instructions provided in the Building locally section.
To start the application, use docker-compose -f docker/docker-compose.yml up -d. The server will be launched at http://localhost:3333/ address.

Configuration

Container images are configured using parameters passed at runtime (such as those above). An explanaition of the default parameters is included below, but please see the Docker documentation for additional information.
~~If any environmental parameter is not passed to the container, its value will be taken from the /config/config.txt file.~~ Warning, the use of config.txt is now deprecated. Please make sure to pass the correct environmental variables to your container at runtime.

Parameter	Function
`-p <port>:3333`	Will map the container's port 3333 to a port on the host, default is 3333. See the Docker docs for more information about port mapping
`-e NODEENV=development`	for specifying Node environment, production or development, default is development currently this should not be changed. See the Docker docs for more information on the use of environmental variables in Command-line and Docker Compose
`-e EXTERNALDOMAIN=<ferdi-serverdomain>`	for specifying the external domain address of the Ferdi-server
`-e DBCONNECTION=<databasedriver`	for specifying the database being used, default is sqlite, see below for other options
`-e DBHOST=<yourdbhost>`	for specifying the database host, default is 127.0.0.1
`-e DBPORT=<yourdbport>`	for specifying the database port, default is 3306
`-e DBUSER=<yourdbuser>`	for specifying the database user, default is root
`-e DBPASSWORD=<yourdbpass>`	for specifying the database password, default is password
`-e DBDATABASE=<databasename>`	for specifying the database name to be used, default is ferdi
`-e DBSSL=false`	true only if your database is postgres and it is hosted online, on platforms like GCP, AWS, etc
`-e MAILCONNECTION=<mailsender>`	for specifying the mail sender to be used, default is smtp
`-e SMPTHOST=<smtpmailserver>`	for specifying the mail host to be used, default is 127.0.0.1
`-e SMTPPORT=<smtpport>`	for specifying the mail port to be used, default is 2525
`-e MAILSSL=true/false`	for specifying SMTP mail security, default is false
`-e MAILUSERNAME=<yourmailusername>`	for specifying your mail username to be used, default is username
`-e MAILPASSWORD=<yourmailpassword>`	for specifying your mail password to be used, default is password
`-e MAILSENDER=<sendemailaddress`	for specifying the mail sender address to be used, default is noreply@getferdi.com
`-e ISCREATIONENABLED=true`	for specifying whether to enable the creation of custom recipes, default is true
`-e ISDASHBOARDENABLED=true`	for specifying whether to enable the Ferdi-server dashboard, default is true
`-e ISREGISTRATIONENABLED=true`	for specifying whether to allow user registration, default is true
`-e CONNECTWITHFRANZ=true`	for specifying whether to enable connections to the Franz server, default is true
`-e DATADIR=data`	for specifying the SQLite database folder, default is data
`-v <path to data on host>:/data`	this will store Ferdi-server's data (its database, among other things) on the docker host for persistence. See the Docker docs for more information on the use of container volumes
`-v <path to recipes on host>:/app/recipes`	this will store Ferdi-server's recipes on the docker host for persistence

By enabling the CONNECT_WITH_FRANZ option, Ferdi-server can:

- Show the full Franz recipe library instead of only custom recipes
- Import Franz accounts

Supported databases and drivers

To use a different database than the default, SQLite3, enter the driver code below in your ENV configuration.

Database	Driver
MariaDB/MySQL	mysql
PostgreSQL	pg
SQLite3	sqlite

Supported mail connections (advanced)

To use a different email sender than the default, SMTP, enter the correct information in your ENV configuration and adapt your docker run, create, or compose commands accordingly.

Mail Connection	ENV variables
SMTP	SMTPPORT, SMTPHOST, MAILUSERNAME, MAILPASSWORD, MAILSSL
SparkPost	SPARKPOSTAPIKEY
Mailgun	MAILGUNDOMAIN, MAILGUNAPIREGION, MAILGUNAPIKEY
(Deprecated) Ethereal	A disposable account is created automatically if you choose this option.

Migrating from an existing Ferdi-server

If you are an existing Ferdi-server user using the built-in SQlite database, you should include the following variables:

Parameter	Function
`-p 3333:3333`	existing Ferdi-server users will need to update their container port mappings from `80:3333` to `3333:3333`
`-e DBPASSWORD=development`	existing Ferdi-server users who use the built-in sqlite database should use the database name `development`
`-e DATADIR=/app/database`	existing Ferdi-server users who use the built-in sqlite database should add this environmental variable to ensure data persistence
`-v <path to data on host>=/app/databases`	existing Ferdi-server users who use the built-in sqlite database should use the volume name `/app/database`

If you are an existing Ferdi-server user who uses an external database or different variables for the built-in SQlite database, you should updatae your parameterse acordingly. For example, if you aree using an exterenal MariaDB or MySql database your unique parameters might look like this:

Parameter	Function
`-e DBCONNECTION=mysql`	for specifying the database being used
`-e DBHOST=192.168.10.1`	for specifying the database host machine IP
`-e DBPORT=3306`	for specifying the database port
`-e DBUSER=ferdi`	for specifying the database user
`-e DBPASSWORD=ferdipw`	for specifying the database password
`-e DBDATABASE=adonis`	for specifying the database to be used
`-v <path to database>:/app/database`	this will strore Ferdi-server's database on the docker host for persistence
`-v <path to recipes>:/app/recipes`	this will strore Ferdi-server's recipes on the docker host for persistence

In either case, please be sure to pass the correct variables to the new Ferdi-server container in order maintain access to your existing database.

NGINX config block

To access Ferdi-server from outside of your home network on a subdomain use this server block:

# Ferdi-server
server {
  listen 443 ssl http2;
  server_name ferdi.my.website;

  # all ssl related config moved to ssl.conf
  include /config/nginx/ssl.conf;

  location / {
    proxy_pass http://<Ferdi-IP>:3333;
    proxy_set_header  X-Real-IP  $remote_addr;
    proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
    proxy_set_header  Host  $host;
    proxy_set_header  X-Forwarded-Proto  $scheme;
  }
}

Importing your Franz account

Ferdi-server allows you to import your full Franz account, including all its settings.
To import your Franz account, open http://[YOUR FERDI-SERVER]/import in your browser and login using your Franz account details. Ferdi-server will create a new user with the same credentials and copy your Franz settings, services and workspaces.

Transferring user data

Please refer to

Creating and using custom recipes

Ferdi-server allows to extends the Franz recipe catalogue with custom Ferdi recipes.
For documentation on how to create a recipe, please visit the official guide by Franz.
To add your recipe to Ferdi-server, open http://[YOUR FERDI-SERVER]/new in your browser. You can now define the following settings:

Author: Author who created the recipe
Name: Name for your new service. Can contain spaces and unicode characters
Service ID: Unique ID for this recipe. Does not contain spaces or special characters (e.g. google-drive)
Link to PNG/SVG image: Direct link to a 1024x1024 PNG image and SVG that is used as a logo inside the store. Please use jsDelivr when using a file uploaded to GitHub as raw.githubusercontent files won't load
Recipe files: Recipe files that you created using the Franz recipe creation guide. Please do not package your files beforehand - upload the raw files (you can drag and drop multiple files). Ferdi-server will automatically package and store the recipe in the right format. Please also do not drag and drop or select the whole folder, select the individual files.

Listing custom recipes

Inside Ferdi, searching for ferdi:custom will list all your custom recipes.

Support Info

Shell access while the container is running: docker exec -it ferdi-server /bin/bash
To monitor the logs of the container in realtime: docker logs -f ferdi-server

Updating Info

Below are the instructions for updating the container to get the most recent version of Ferdi-server:

Via Docker Run/Create

Update the image: docker pull getferdi/ferdi-server
Stop the running container: docker stop ferdi-server
Delete the container: docker rm ferdi-server
Recreate a new container with the same docker create parameters as instructed above (if mapped correctly to a host folder, your /config folder and ENV settings will be preserved)
Start the new container: docker start ferdi-server

Via Docker Compose

Update all images: docker-compose -f docker/docker-compose.yml pull

or update a single image: docker-compose -f docker/docker-compose.yml pull ferdi-server
Let compose update all containers as necessary: docker-compose -f docker/docker-compose.yml up -d
or update a single container: docker-compose -f docker/docker-compose.yml up -d ferdi-server

Building locally

If you want to build this image locally, please run this command from root of Ferdi-server repository:

docker build \
  --no-cache \
  --pull \
  -t getferdi/ferdi-server:latest .

License

Ferdi-server-docker and Ferdi-server are licensed under the MIT License.

Serve Ferdi Server on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxy Domain App port Upstream

Proxying ferdi-server.example.com to http://ferdi-server:3333

Add this to your Caddyfile

ferdi-server.example.com {
	reverse_proxy http://ferdi-server:3333
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

In Portainer, go to Containers, click the container, then Logs. Or run docker logs <container>
Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:3333 failed: port is already allocated", something else on your server is using that port.

Find what's using it: sudo ss -tlnp | grep :3333
Stop the other service, or pick a different host port. In 3333:3333 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

Use your server's real IP: http://your-server-ip:3333. The 0.0.0.0 link Portainer shows isn't a real address.
Give it a minute after first deploy, ferdi-server can take a while to initialise.
Make sure your firewall allows the port, e.g. sudo ufw allow 3333

Image won't pull

Test the pull directly on the host: docker pull getferdi/ferdi-server

"manifest unknown" means the tag no longer exists. This template uses latest, so try pinning a specific version instead.
"toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
"no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

This image supports: amd64, arm64
Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

Check the logs right after a restart, the last few lines before it died are the useful ones.
Get the exit code with docker inspect <container> --format '{{.State.ExitCode}}'
Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Stack won't deploy

Compose stacks fail fast on small mistakes, and Portainer shows the reason just above the editor.

YAML only accepts spaces for indentation, a single tab breaks the whole file.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

Bug within the app: Open an issue within ferdi-server's repo
Template not working: Open an issue on xneo1/portainer_templates
This website not working: Open an issue on lissy93/portainer-templates

A Compose stack

Ferdi Server is a Compose stack, a set of containers defined in one file and brought up together by Portainer, then started and stopped as a single app.

The app image

An image is the app packed up ready to go, everything Ferdi Server needs bundled into one download. This template pulls getferdi/ferdi-server, which Docker fetches once (about 79 MB) and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. Ferdi Server's comes from Docker Hub, published by getferdi.

Version tags

The bit after the colon in the image name is the version tag. Here it's latest, which always points at the newest build, so a redeploy can bump you to a newer release without you asking. Newest right now is 1.3. Pin a specific tag if you would rather stay on one version.

Which machines it runs on

Every image is built for particular CPU types. This one ships for amd64, arm64, so it runs on both regular x86 servers and ARM boards like a Raspberry Pi.

Ports

A port is the door the app answers on. A mapping like 3333:3333 means it's reachable on port 3333 of your server, where the left number is yours to change and the right one belongs to the app. It opens:

3333:3333

Volumes

A volume is where Ferdi Server keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

/data kept in the ferdi-database-vol volume Docker manages
/app/recipes kept in the ferdi-recipes-vol volume Docker manages

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. Ferdi Server takes 23 of them, all with defaults you can leave alone or tweak:

NODE_ENV, defaults to development
EXTERNAL_DOMAIN, defaults to localhost
DB_CONNECTION, defaults to sqlite
DB_HOST, defaults to 127.0.0.1
DB_PORT, defaults to 3306
DB_USER, defaults to root
DB_PASSWORD, defaults to password
DB_DATABASE, defaults to ferdi
DB_SSL, defaults to false
MAIL_CONNECTION, defaults to smtp
SMPT_HOST, defaults to 127.0.0.1
SMTP_PORT, defaults to 2525
MAIL_SSL, defaults to false
MAIL_USERNAME, defaults to username
MAIL_PASSWORD, defaults to password
MAIL_SENDER, defaults to noreply@getferdi.com
IS_CREATION_ENABLED, defaults to true
IS_DASHBOARD_ENABLED, defaults to true
IS_REGISTRATION_ENABLED, defaults to true
CONNECT_WITH_FRANZ, defaults to false
DATA_DIR, defaults to /data
PUID, defaults to 1000
PGID, defaults to 1000

Restart policy

The restart policy here is unless-stopped, so Docker restarts Ferdi Server after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Users and permissions

The PUID and PGID settings tell it which user and group to act as on your host. Point them at your own account (find yours with id $USER) so the files it writes into your mounted folders come out owned by you rather than root.

Networking

Nothing custom is set, so Ferdi Server sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container ferdi-server. That's what you'll spot in the containers list and use in commands like docker logs ferdi-server.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set Ferdi Server up. Add the template list to Portainer once, then deploying Ferdi Server is a click rather than a wall of config.

Ferdi Server

Image details

Configuration

Standalone Install

Install on Portainer

Template Import URL

Container Documentation

Ferdi-server-docker

Why use a custom Ferdi-server?

Features

Installation & Setup

docker

docker-compose

Configuration

Supported databases and drivers

Supported mail connections (advanced)

Migrating from an existing Ferdi-server

NGINX config block

Importing your Franz account

Transferring user data

Creating and using custom recipes

Listing custom recipes

Support Info

Updating Info

Via Docker Run/Create

Via Docker Compose

Building locally

License

Recent versions

Proxy configurator

Troubleshooting

Check the logs first

Port already in use

Running but the page won't load

Image won't pull

"exec format error"

Container keeps restarting

Stack won't deploy

Raise an issue

Config glossary

A Compose stack

The app image

Where the image comes from

Version tags

Which machines it runs on

Ports

Volumes

Environment variables

Restart policy

Users and permissions

Networking

Container name

Platform

Portainer app templates

Similar apps