{"id":13581394,"url":"https://github.com/ferdium/ferdium-server","last_synced_at":"2026-01-16T19:30:55.096Z","repository":{"id":38242656,"uuid":"481433419","full_name":"ferdium/ferdium-server","owner":"ferdium","description":"The server component that can either be self-hosted or hosted for general purpose - for use with the ferdium thick client.","archived":false,"fork":false,"pushed_at":"2025-08-13T10:42:35.000Z","size":2797,"stargazers_count":237,"open_issues_count":22,"forks_count":45,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-10T18:27:33.383Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ferdium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-14T01:58:16.000Z","updated_at":"2025-10-10T14:37:52.000Z","dependencies_parsed_at":"2023-09-26T11:16:26.640Z","dependency_job_id":"3cf46291-c50f-4a6b-81f2-32ae5a3a9ec7","html_url":"https://github.com/ferdium/ferdium-server","commit_stats":{"total_commits":450,"total_committers":35,"mean_commits":"12.857142857142858","dds":0.7377777777777778,"last_synced_commit":"0c65c9ae1e2ab1f1043bcc9452c082be2a087934"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/ferdium/ferdium-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferdium%2Fferdium-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferdium%2Fferdium-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferdium%2Fferdium-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferdium%2Fferdium-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ferdium","download_url":"https://codeload.github.com/ferdium/ferdium-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ferdium%2Fferdium-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28481771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-08-01T15:02:01.171Z","updated_at":"2026-01-16T19:30:54.851Z","avatar_url":"https://github.com/ferdium.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./logo.png\" alt=\"\" width=\"300\"/\u003e\n\u003c/p\u003e\n\n# Server\n  [![Docker Build and Publish](https://github.com/ferdium/ferdium-server/actions/workflows/docker.yml/badge.svg)](https://github.com/ferdium/ferdium-server/actions/workflows/docker.yml)\n\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n\u003ca href='#contributors-'\u003e\u003cimg src='https://img.shields.io/badge/contributors-19-default.svg?logo=github' alt='Contributors'/\u003e\u003c/a\u003e\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\n\u003e 👨🏾‍🍳 Server for [Ferdium](https://ferdium.org) that you can re-use to run your own\n\n## Why use a custom server?\n\n_Find answers to other frequently asked questions on [ferdium.org/faq](https://ferdium.org/faq)._\n\n\u003cdetails\u003e\n\u003csummary\u003eToggle answer\u003c/summary\u003e\n\nA 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](https://api.ferdium.org).\n\n\u003c/details\u003e\n\n## Features\n- [x] User registration and login\n- [x] Service creation, download, listing and removing\n- [x] Workspace support\n- [x] Functioning service store\n- [x] User dashboard\n- [x] Export/import data to other Ferdium-servers\n- [x] Password recovery\n- [x] Recipe update\n\n## Deploying the App\n\n\u003cdetails\u003e\n\u003csummary\u003eSetup with Docker\u003c/summary\u003e\nThe easiest way to set up Ferdium-server on your server is with Docker.\n\nThe 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).\nAfter 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.\n\n**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](./docker/README.md) for more information about migrating to the new image.\n\n1. Pull the Docker image\n\n    ```sh\n    docker pull ferdium/ferdium-server:latest\n    ```\n2. Create a *new* Docker container with your desired configuration **Existing users please seee the warning above.**\n\n    ```sh\n\t    docker create \\\n\t    --name=ferdium-server \\\n\t    -e NODE_ENV=development \\\n\t    -e APP_URL=\u003cferdium-server-url\u003e \\\n\t    -e DB_CONNECTION=\u003cdatabase\u003e \\\n\t    -e DB_HOST=\u003cyourdbhost\u003e \\\n\t    -e DB_PORT=\u003cyourdbport\u003e \\\n\t    -e DB_USER=\u003cyourdbuser\u003e \\\n\t    -e DB_PASSWORD=\u003cyourdbpass\u003e \\\n\t    -e DB_DATABASE=\u003cyourdbdatabase\u003e \\\n\t    -e DB_SSL=false \\\n\t    -e MAIL_CONNECTION=smtp \\\n\t    -e SMTP_HOST=\u003csmtpmailserver\u003e \\\n\t    -e SMTP_PORT=\u003csmtpport\u003e \\\n\t    -e MAIL_SSL=true/false \\\n\t    -e MAIL_USERNAME=\u003cyourmailusername\u003e \\\n\t    -e MAIL_PASSWORD=\u003cyourmailpassword\u003e \\\n\t    -e MAIL_SENDER=\u003csendemailaddress\u003e \\\n\t    -e IS_CREATION_ENABLED=true \\\n\t    -e IS_DASHBOARD_ENABLED=true \\\n\t    -e IS_REGISTRATION_ENABLED=true \\\n\t    -e CONNECT_WITH_FRANZ=true \\\n      -e DATA_DIR=data \\\n\t    -p \u003cport\u003e:3333 \\\n\t    -v \u003cpath to data\u003e:/data \\\n\t    -v \u003cpath to recipes\u003e:/app/recipes \\\n\t    --restart unless-stopped \\\n\t    ferdium/ferdium-server:latest\n    ```\n\n    Alternatively, you can also use docker-compose v2 schema. An example can be found [in the docker folder](./docker/docker-compose.yml).\n\n3. Optionally, you can [set up Nginx as a reverse proxy](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-node-js-application-for-production-on-ubuntu-16-04#set-up-nginx-as-a-reverse-proxy-server).\n\nFor more information on configuring the Docker image, please read [the Ferdium docker documentation](./docker/README.md).\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eManual setup\u003c/summary\u003e\n\n1. Clone repository with submodule\n2. Install the [AdonisJS CLI](https://adonisjs.com/)\n3. Copy `.env.example` to `.env` and edit the [configuration](#configuration) to your needs\n4. Have env DB_SSL=true only if your database is postgres and it is hosted online on platforms like GCP, AWS, etc\n5. Run `npm install` to install local dependencies\n6. Run the database migrations with\n\n    ```js\n    node ace migration:run\n    ```\n\n7. Start the server with\n\n    ```js\n    npm start\n    ```\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eConfiguration\u003c/summary\u003e\n\nFerdium-server's configuration is saved inside an `.env` file. Besides AdonisJS's settings, Ferdium-server has the following custom settings:\n- `IS_CREATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the [creation of custom recipes](#creating-and-using-custom-recipes)\n- `IS_REGISTRATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the creation of new user accounts\n- `IS_DASHBOARD_ENABLED` (`true` or `false`, default: `true`): Whether to enable the user dashboard\n- `CONNECT_WITH_FRANZ` (`true` or `false`, default: `true`): Whether to enable connections to the Franz server. By enabling this option, Ferdium-server can:\n  - Show the full Franz recipe library instead of only custom recipes\n  - Import Franz accounts\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eImporting your Franz/Ferdi account\u003c/summary\u003e\n\nFerdium-server allows you to import your full Franz/Ferdi account, including all its settings.\n\nTo 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.\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eTransferring user data\u003c/summary\u003e\n\nPlease refer to \u003chttps://github.com/getferdi/ferdi/wiki/Transferring-data-between-servers\u003e\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eCreating and using custom recipes\u003c/summary\u003e\nFerdium-server allows to extends the Franz/Ferdi recipe catalogue with custom Ferdium recipes.\n\nFor documentation on how to create a recipe, please visit [the official guide](https://github.com/ferdium/ferdium-recipes/blob/main/docs/integration.md).\n\nTo add your recipe to Ferdium-server, open `http://[YOUR FERDIUM-SERVER]/new` in your browser. You can now define the following settings:\n\n- `Author`: Author who created the recipe\n- `Name`: Name for your new service. Can contain spaces and unicode characters\n- `Service ID`: Unique ID for this recipe. Does not contain spaces or special characters (e.g. `google-drive`)\n- `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\n- `Recipe files`: Recipe files that you created using the [recipe creation guide](https://github.com/ferdium/ferdium-recipes/blob/main/docs/integration.md). 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.\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eListing custom recipes\u003c/summary\u003e\n\nInside Ferdium, searching for `ferdium:custom` will list all of your custom recipes.\n\u003c/details\u003e\n\n## Contributing\n\nPlease read the [contributing guidelines](CONTRIBUTING.md) to setup your development machine and proceed.\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://pogonip.pw/' title='nick: code'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/5242865?v=4' alt='HuggableSquare' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='http://code-addict.pl' title='Michał Kostewicz: code'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/6313392?v=4' alt='k0staa' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://gitlab.com/cromefire_' title='Cromefire_: code'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/26320625?v=4' alt='cromefire' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://omkaragrawal.dev' title='OMKAR AGRAWAL: code'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/10913160?v=4' alt='Omkaragrawal' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='http://www.nathanaelhoun.fr' title='Nathanaël Houn: review'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/45119518?v=4' alt='nathanaelhoun' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://github.com/ericreeves' title='Eric Reeves: infra'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/1744930?v=4' alt='ericreeves' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://github.com/SpecialAro' title='André Oliveira: infra, design'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/37463445?v=4' alt='SpecialAro' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://mydarkstar.net' title='mydarkstar: review'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/17343993?v=4' alt='mydarkstar' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://santhosh.cyou' title='Santhosh C: code'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/20743451?v=4' alt='santhosh-chinnasamy' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://github.com/vraravam' title='Vijay Aravamudhan: review, code'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/69629?v=4' alt='vraravam' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://github.com/dqos' title='Tamer: design'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/8611981?v=4' alt='dqos' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://github.com/Gibby' title='Gibby: infra, doc'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/503761?v=4' alt='Gibby' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://github.com/palepinkdot' title='MG: review'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/55257671?v=4' alt='palepinkdot' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://github.com/xthursdayx' title='thursday: infra'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/18044308?v=4' alt='xthursdayx' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://vantezzen.io/' title='Bennett: code'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/10333196?v=4' alt='vantezzen' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://gitlab.com/reggermont/' title='Romain Eggermont: infra'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/14902909?v=4' alt='reggermont' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='http://lnhrdt.com' title='Leonhardt Koepsell: infra'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/4040241?v=4' alt='lnhrdt' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://github.com/fabolhak' title='Fabian H.: doc'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/20029691?v=4' alt='fabolhak' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href='https://github.com/mazzz1y' title='Dmitry R.: code'\u003e\u003cimg src='https://avatars.githubusercontent.com/u/17034108?v=4' alt='mazzz1y' style='width:100px;'/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fferdium%2Fferdium-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fferdium%2Fferdium-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fferdium%2Fferdium-server/lists"}