Ferdium (stack)
Ferdium is a messaging browser that allows you to combine your favourite messaging services into one application
Image details
Source details
Configuration
TypeComposelinuxferdium/ferdium-server:latest3334:3333/data : /portainer/Files/AppData/Config/ferdium/app/recipes : /portainer/Files/AppData/Config/ferdium/recipesNODE_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=password[email protected]IS_CREATION_ENABLED=trueIS_DASHBOARD_ENABLED=trueIS_REGISTRATION_ENABLED=trueCONNECT_WITH_FRANZ=trueDATA_DIR=/dataPUID=1000PGID=1000alwaysInstallation
- 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 the app you wish to deploy, fill in any config options, and hit Deploy
Template Import URL
https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me
docker run -d --name ferdi-server \
-p 3334:3333 \
-e 'NODE_ENV=development' \
-e 'EXTERNAL_DOMAIN=localhost' \
-e 'DB_CONNECTION=sqlite' \
-e 'DB_HOST=127.0.0.1' \
-e 'DB_PORT=3306' \
-e 'DB_USER=root' \
-e 'DB_PASSWORD=password' \
-e 'DB_DATABASE=ferdi' \
-e 'DB_SSL=false' \
-e 'MAIL_CONNECTION=smtp' \
-e 'SMPT_HOST=127.0.0.1' \
-e 'SMTP_PORT=2525' \
-e 'MAIL_SSL=false' \
-e 'MAIL_USERNAME=username' \
-e 'MAIL_PASSWORD=password' \
-e '[email protected]' \
-e 'IS_CREATION_ENABLED=true' \
-e 'IS_DASHBOARD_ENABLED=true' \
-e 'IS_REGISTRATION_ENABLED=true' \
-e 'CONNECT_WITH_FRANZ=true' \
-e 'DATA_DIR=/data' \
-e 'PUID=1000' \
-e 'PGID=1000' \
-v /portainer/Files/AppData/Config/ferdium:/data \
-v /portainer/Files/AppData/Config/ferdium/recipes:/app/recipes \
--restart=always \
ferdium/ferdium-server:latestIf the stack expects env vars, set them or add them to a .env file first.
services:
ferdi-server:
image: ferdium/ferdium-server:latest
container_name: ferdium-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
- [email protected]
- IS_CREATION_ENABLED=true
- IS_DASHBOARD_ENABLED=true
- IS_REGISTRATION_ENABLED=true
- CONNECT_WITH_FRANZ=true
- DATA_DIR=/data
- PUID=1000
- PGID=1000
volumes:
- /portainer/Files/AppData/Config/ferdium:/data
- /portainer/Files/AppData/Config/ferdium/recipes:/app/recipes
ports:
- 3334:3333
restart: always
Or, use the original compose file, straight from the template repo. Deploy with:
git clone https://github.com/xneo1/portainer_templates
cd portainer_templates
docker compose -f Template/Stack/ferdium.yml up -dSave this file as ferdium-stack-stack.yml, then from a manager node, run docker stack deploy -c ferdium-stack-stack.yml ferdium-stack
version: '3.8'
services:
ferdium-stack:
image: ferdium/ferdium-server:latest
ports:
- '3334:3333'
volumes:
- /portainer/Files/AppData/Config/ferdium:/data
- /portainer/Files/AppData/Config/ferdium/recipes:/app/recipes
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: [email protected]
IS_CREATION_ENABLED: 'true'
IS_DASHBOARD_ENABLED: 'true'
IS_REGISTRATION_ENABLED: 'true'
CONNECT_WITH_FRANZ: 'true'
DATA_DIR: /data
PUID: '1000'
PGID: '1000'
deploy:
restart_policy:
condition: any
Save each file below into a folder, then run kubectl apply -f .
Written for k3s, but works on any cluster: bind mounts use hostPath, named volumes get a
persistent volume claim, and ports are exposed via a LoadBalancer service.
ferdium-stack-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: ferdium-stack
labels:
app: ferdium-stack
spec:
replicas: 1
selector:
matchLabels:
app: ferdium-stack
template:
metadata:
labels:
app: ferdium-stack
spec:
containers:
- name: ferdium-stack
image: ferdium/ferdium-server:latest
env:
- name: NODE_ENV
value: development
- name: EXTERNAL_DOMAIN
value: localhost
- name: DB_CONNECTION
value: sqlite
- name: DB_HOST
value: 127.0.0.1
- name: DB_PORT
value: '3306'
- name: DB_USER
value: root
- name: DB_PASSWORD
value: password
- name: DB_DATABASE
value: ferdi
- name: DB_SSL
value: 'false'
- name: MAIL_CONNECTION
value: smtp
- name: SMPT_HOST
value: 127.0.0.1
- name: SMTP_PORT
value: '2525'
- name: MAIL_SSL
value: 'false'
- name: MAIL_USERNAME
value: username
- name: MAIL_PASSWORD
value: password
- name: MAIL_SENDER
value: [email protected]
- name: IS_CREATION_ENABLED
value: 'true'
- name: IS_DASHBOARD_ENABLED
value: 'true'
- name: IS_REGISTRATION_ENABLED
value: 'true'
- name: CONNECT_WITH_FRANZ
value: 'true'
- name: DATA_DIR
value: /data
- name: PUID
value: '1000'
- name: PGID
value: '1000'
ports:
- containerPort: 3333
protocol: TCP
volumeMounts:
- name: ferdium-stack-data-0
mountPath: /data
- name: ferdium-stack-data-1
mountPath: /app/recipes
volumes:
- name: ferdium-stack-data-0
hostPath:
path: /portainer/Files/AppData/Config/ferdium
- name: ferdium-stack-data-1
hostPath:
path: /portainer/Files/AppData/Config/ferdium/recipes
ferdium-stack-service.yaml
apiVersion: v1
kind: Service
metadata:
name: ferdium-stack
spec:
type: LoadBalancer
selector:
app: ferdium-stack
ports:
- name: 3334-tcp
port: 3334
targetPort: 3333
protocol: TCP
Save this file as ~/.config/containers/systemd/ferdium-stack.container
[Unit]
Description=Ferdium (stack)
[Container]
Image=ferdium/ferdium-server:latest
ContainerName=ferdium-stack
PublishPort=3334:3333
Environment=NODE_ENV=development
Environment=EXTERNAL_DOMAIN=localhost
Environment=DB_CONNECTION=sqlite
Environment=DB_HOST=127.0.0.1
Environment=DB_PORT=3306
Environment=DB_USER=root
Environment=DB_PASSWORD=password
Environment=DB_DATABASE=ferdi
Environment=DB_SSL=false
Environment=MAIL_CONNECTION=smtp
Environment=SMPT_HOST=127.0.0.1
Environment=SMTP_PORT=2525
Environment=MAIL_SSL=false
Environment=MAIL_USERNAME=username
Environment=MAIL_PASSWORD=password
Environment[email protected]
Environment=IS_CREATION_ENABLED=true
Environment=IS_DASHBOARD_ENABLED=true
Environment=IS_REGISTRATION_ENABLED=true
Environment=CONNECT_WITH_FRANZ=true
Environment=DATA_DIR=/data
Environment=PUID=1000
Environment=PGID=1000
Volume=/portainer/Files/AppData/Config/ferdium:/data
Volume=/portainer/Files/AppData/Config/ferdium/recipes:/app/recipes
[Service]
Restart=always
[Install]
WantedBy=default.targetThen reload systemd and start the service:
systemctl --user daemon-reload
systemctl --user start ferdium-stackFor a system-wide service, use /etc/containers/systemd/ and drop --user.
For more installation options, see the Documentation in our GitHub repo
For app-specific guidance, check Ferdium (stack)'s own repo at ferdium/ferdium-server
<img src="https://raw.githubusercontent.com/ferdium/ferdium-server/HEAD/logo.png" alt="" width="300"/>Server
👨🏾🍳 Server for Ferdium that you can re-use to run your own
Why use a custom server?
Find answers to other frequently asked questions on ferdium.org/faq.Toggle answer
A custom server allows you to manage the data of all registered users yourself and add your own recipes to the repository. If you are not interested in doing this you can use our official instance of the server at api.ferdium.org
Features
- x User registration and login
- x Service creation, download, listing and removing
- x Workspace support
- x Functioning service store
- x User dashboard
- x Export/import data to other Ferdium-servers
- x Password recovery
- x Recipe update
Deploying the App
Setup with Docker
The easiest way to set up Ferdium-server on your server is with Docker.The Docker image can be run as is, with the default SQLite database or you can modify your ENV variables to use an external database (e.g. MySQL, MariaDB, Postgres, etc). After setting up the docker container we recommend you set up an NGINX reverse proxy to access Ferdium-server outside of your home network and protect it with an SSL certificate.
Warning, please note that the use of the previous
config.txt is now deprecated and a number of environment variables have changed, specifically the default database name and location, the internal container port, and an additional DATA_DIR variable has been added. Make sure to pass the correct environment variables to your container at runtime. If you are an existing Ferdium-server user, please see the Ferdium docker documentation for more information about migrating to the new image.- Pull the Docker image
```sh
docker pull ferdium/ferdium-server:latest
```- Create a new Docker container with your desired configuration Existing users please seee the warning above.
```sh
docker create \
--name=ferdium-server \
-e NODE_ENV=development \
-e APP_URL=<ferdium-server-url> \
-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 SMTP_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 \
ferdium/ferdium-server:latest
```
Alternatively, you can also use docker-compose v2 schema. An example can be found [in the docker folder](https://github.com/ferdium/ferdium-server/blob/HEAD/docker/docker-compose.yml).- Optionally, you can set up Nginx as a reverse proxy.
For more information on configuring the Docker image, please read the Ferdium docker documentation.
Manual setup
- Clone repository with submodule
- Install the AdonisJS CLI
- Copy
.env.exampleto.envand edit the configuration to your needs - Have env DBSSL=true only if your database is postgres and it is hosted online on platforms like GCP, AWS, etc
- Run
npm installto install local dependencies - Run the database migrations with
```js
node ace migration:run
```- Start the server with
```js
npm start
```Configuration
Ferdium-server's configuration is saved inside an
.env file. Besides AdonisJS's settings, Ferdium-server has the following custom settings:IS_CREATION_ENABLED(trueorfalse, default:true): Whether to enable the creation of custom recipesIS_REGISTRATION_ENABLED(trueorfalse, default:true): Whether to enable the creation of new user accountsIS_DASHBOARD_ENABLED(trueorfalse, default:true): Whether to enable the user dashboardCONNECT_WITH_FRANZ(trueorfalse, default:true): Whether to enable connections to the Franz server. By enabling this option, Ferdium-server can:
DB_SQLITE_JOURNAL_MODE(DELETE,TRUNCATE,PERSIST,MEMORY,WAL, orOFF, default:WAL): SQLite journal mode.WALimproves concurrency for the default single-file deployment.DB_SQLITE_SYNCHRONOUS(OFF,NORMAL,FULL, orEXTRA, default:FULL): SQLite synchronous mode.FULLis the safer default for production durability.NORMALreduces write latency but can lose the last committed transactions on sudden power loss.DB_BUSY_TIMEOUT(milliseconds, default:5000): How long SQLite should wait for a locked database before failing a query.
Importing your Franz/Ferdi account
Ferdium-server allows you to import your full Franz/Ferdi account, including all its settings.
To import your Franz/Ferdi account, open
http://[YOUR FERDIUM-SERVER]/import in your browser and login using your Franz/Ferdi account details. Ferdium-server will create a new user with the same credentials and copy your Franz/Ferdi settings, services and workspaces.
Transferring user data
Please refer to
Creating and using custom recipes
Ferdium-server allows to extends the Franz/Ferdi recipe catalogue with custom Ferdium recipes.For documentation on how to create a recipe, please visit the official guide.
To add your recipe to Ferdium-server, open
http://[YOUR FERDIUM-SERVER]/new in your browser. You can now define the following settings:Author: Author who created the recipeName: Name for your new service. Can contain spaces and unicode charactersService ID: Unique ID for this recipe. Does not contain spaces or special characters (e.g.google-drive)Link to SVG image: Direct link to a 1024x1024 SVG image 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 loadRecipe files: Recipe files that you created using the recipe creation guide. Please do not package your files beforehand - upload the raw files (you can drag and drop multiple files). Ferdium-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 Ferdium, searching for
ferdium:custom will list all of your custom recipes.
Contributing
Please read the contributing guidelines to setup your development machine and proceed.Contributors ✨
Thanks goes to these wonderful people (emoji key):This project follows the all-contributors specification. Contributions of any kind welcome!
Serve Ferdium (stack) 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.
Proxying ferdium-stack.example.com to http://ferdi-server:3333
Add this to your Caddyfile
ferdium-stack.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:
137means killed, usually out of memory.126or127means the command inside the image is broken.
Port already in use
If deployment fails with "Bind for 0.0.0.0:3334 failed: port is already allocated", something else on your server is using that port.
- Find what's using it:
sudo ss -tlnp | grep :3334 - Stop the other service, or pick a different host port. In
3334:3333only 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:3334. 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 3334
Permission denied on volumes
If the logs show "permission denied", the app can't write to its data folder on the host.
- Fix the ownership:
sudo chown -R 1000:1000 /portainer/Files/AppData/Config/ferdium(and the same for the other mapped folders) - Or set the
PUIDandPGIDvariables (defaults 1000:1000) to match your own user, found withid $USER
Image won't pull
Test the pull directly on the host: docker pull ferdium/ferdium-server:latest
- "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 loginto 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 always 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
noso 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 on ferdium/ferdium-server
- Template not working: Open an issue on xneo1/portainer_templates
- This website not working: Open an issue on lissy93/portainer-templates