👨🏾🍳 Server for Ferdi that you can re-use to run your own
Why use a custom server?
Find answers to other frequently asked questions on getferdi.com/faq.
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.getferdi.com.
- User registration and login
- Service creation, download, listing and removing
- Workspace support
- Functioning service store
- User dashboard
- Export/import data to other Ferdi-servers
- Password recovery
- Recipe update
Deploying the App
Click the button below to deploy your server to the DigitalOcean App Platform:
Setup with DockerThe easiest way to set up Ferdi-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 Ferdi-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 environmental 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 environmental variables to your container at runtime. If you are an existing Ferdi-server user, please see the Ferdi docker documentation for more information about migrating to the new image.
Pull the Docker image
docker pull getferdi/ferdi-server
Create a new Docker container with your desired configuration Existing users please seee the warning above.
docker create \ --name=ferdi-server \ -e NODE_ENV=development \ -e APP_URL=<ferdi-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 \ getferdi/ferdi-server
Alternatively, you can also use docker-compose v2 schema. An example can be found in the docker folder.
Optionally, you can set up Nginx as a reverse proxy.
For more information on configuring the Docker image, please read the Ferdi docker documentation.
Clone repository with submodule
Install the AdonisJS CLI
.envand edit the configuration to your needs
Have env DB_SSL=true only if your database is postgres and it is hosted online on platforms like GCP, AWS, etc
npm installto install local dependencies
Run the database migrations with
node ace migration:run
Start the server with
franz-server's configuration is saved inside an
.env file. Besides AdonisJS's settings, Ferdi-server has the following custom settings:
true): Whether to enable the creation of custom recipes
true): Whether to enable the creation of new user accounts
true): Whether to enable the user dashboard
true): Whether to enable connections to the Franz server. By enabling this option, Ferdi-server can:
- Show the full Franz recipe library instead of only custom recipes
- Import Franz accounts
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
Creating and using custom recipesFerdi-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.
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 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 of your custom recipes.
Please read the contributing guidelines to setup your development machine and proceed.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!