![Ferdium (stack)]()
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=passwordMAIL_SENDER=noreply@getferdi.comIS_CREATION_ENABLED=trueIS_DASHBOARD_ENABLED=trueIS_REGISTRATION_ENABLED=trueCONNECT_WITH_FRANZ=trueDATA_DIR=/dataPUID=1000PGID=1000alwaysStandalone Install
Select an install method, to see config/commands for deploying Ferdium (stack)
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 Ferdium (stack), 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: 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
- MAIL_SENDER=noreply@getferdi.com
- 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 deploy it directly from the source:
git clone https://github.com/xneo1/portainer_templates
cd portainer_templates
docker compose -f Template/Stack/ferdium.yml up -dMore install options in our documentation, or see ferdium/ferdium-server for app-specific guidance.
<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
A Compose stack
Ferdium (stack) 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 Ferdium (stack) needs bundled into one download. This template pulls ferdium/ferdium-server:latest, which Docker fetches once (about 312 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. Ferdium (stack)'s comes from Docker Hub, published by ferdium.
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 2.0.13. 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 3334:3333 means it's reachable on port 3334 of your server, where the left number is yours to change and the right one belongs to the app. It opens:
3334:3333
Volumes
A volume is where Ferdium (stack) 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:
/datafrom/portainer/Files/AppData/Config/ferdiumon the host/app/recipesfrom/portainer/Files/AppData/Config/ferdium/recipeson the host
Environment variables
Environment variables are the settings you hand over when you deploy, things like a password or a timezone. Ferdium (stack) takes 23 of them, all with defaults you can leave alone or tweak:
NODE_ENV, defaults todevelopmentEXTERNAL_DOMAIN, defaults tolocalhostDB_CONNECTION, defaults tosqliteDB_HOST, defaults to127.0.0.1DB_PORT, defaults to3306DB_USER, defaults torootDB_PASSWORD, defaults topasswordDB_DATABASE, defaults toferdiDB_SSL, defaults tofalseMAIL_CONNECTION, defaults tosmtpSMPT_HOST, defaults to127.0.0.1SMTP_PORT, defaults to2525MAIL_SSL, defaults tofalseMAIL_USERNAME, defaults tousernameMAIL_PASSWORD, defaults topasswordMAIL_SENDER, defaults tonoreply@getferdi.comIS_CREATION_ENABLED, defaults totrueIS_DASHBOARD_ENABLED, defaults totrueIS_REGISTRATION_ENABLED, defaults totrueCONNECT_WITH_FRANZ, defaults totrueDATA_DIR, defaults to/dataPUID, defaults to1000PGID, defaults to1000
Restart policy
The restart policy here is always, so Docker brings Ferdium (stack) back up after a crash and again when the server reboots. Good for anything you want running around the clock. 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 Ferdium (stack) 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.
Open source license
Ferdium (stack) is open source, released under the MIT license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.
Portainer app templates
Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set Ferdium (stack) up. Add the template list to Portainer once, then deploying Ferdium (stack) is a click rather than a wall of config.