From e1c47572a6235fd8fd20af888ac3a11c7ae1369d Mon Sep 17 00:00:00 2001 From: MCMXC <16797721+mcmxcdev@users.noreply.github.com> Date: Sat, 10 Feb 2024 18:37:40 -0700 Subject: updates --- docker/README.md | 166 ++++++++++++++++++++++++---------------------- docker/docker-compose.yml | 2 +- 2 files changed, 86 insertions(+), 82 deletions(-) (limited to 'docker') diff --git a/docker/README.md b/docker/README.md index 0051ac5..d80a545 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,12 +1,15 @@ # Ferdium-server-docker + [Ferdium](https://github.com/ferdium/ferdium-app) is a hard-fork of [Ferdi](https://github.com/getferdi/ferdi), adding awesome features and removing unwanted ones. Ferdium-server is an unofficial replacement of the Franz/Ferdi server for use with the Ferdium Client. This is a dockerized version of [Ferdium-server](https://github.com/ferdium/ferdium-server) running on Alpine Linux and Node.js (v10.16.3). ## Why use a custom Ferdium-server? + A custom Ferdium-server allows you to experience the full potential of the Ferdium Client. It allows you to use all Premium features (e.g. Workspaces and custom URL recipes) for free and [add your own recipes](#creating-and-using-custom-recipes) that are monetized in Franz. ## Features + - [x] User registration and login - [x] Service creation, download, listing and removing - [x] Workspace support @@ -32,34 +35,34 @@ Pull the docker image: To create the docker container with the proper parameters: - docker create \ - --name=ferdium-server \ - -e NODE_ENV=development \ - -e APP_URL= \ - -e DB_CONNECTION= \ - -e DB_HOST= \ - -e DB_PORT= \ - -e DB_USER= \ - -e DB_PASSWORD= \ - -e DB_DATABASE= \ - -e DB_SSL=false \ - -e MAIL_CONNECTION=smtp \ - -e SMTP_HOST= \ - -e SMTP_PORT= \ - -e MAIL_SSL=true/false \ - -e MAIL_USERNAME= \ - -e MAIL_PASSWORD= \ - -e MAIL_SENDER= \ - -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 :3333 \ - -v :/data \ - -v :/app/recipes \ - --restart unless-stopped \ - ferdium/ferdium-server:latest + docker create \ + --name=ferdium-server \ + -e NODE_ENV=development \ + -e APP_URL= \ + -e DB_CONNECTION= \ + -e DB_HOST= \ + -e DB_PORT= \ + -e DB_USER= \ + -e DB_PASSWORD= \ + -e DB_DATABASE= \ + -e DB_SSL=false \ + -e MAIL_CONNECTION=smtp \ + -e SMTP_HOST= \ + -e SMTP_PORT= \ + -e MAIL_SSL=true/false \ + -e MAIL_USERNAME= \ + -e MAIL_PASSWORD= \ + -e MAIL_SENDER= \ + -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 :3333 \ + -v :/data \ + -v :/app/recipes \ + --restart unless-stopped \ + ferdium/ferdium-server:latest ### docker-compose @@ -75,56 +78,54 @@ Container images are configured using parameters passed at runtime (such as thos If any environment 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 environment variables to your container at runtime. ** -| Parameter | Function | -| :----: | --- | -| `-p :3333` | Will map the container's port 3333 to a port on the host, default is 3333. See the [Docker docs](https://docs.docker.com/config/containers/container-networking/) for more information about port mapping | -| `-e NODE_ENV=development` | for specifying Node environment, production or development, default is development **currently this should not be changed**. See the [Docker docs](https://docs.docker.com/) for more information on the use of environment variables in [Command-line](https://docs.docker.com/engine/reference/commandline/run/#mount-volume--v---read-only) and [Docker Compose](https://docs.docker.com/compose/environment-variables/) | -| `-e APP_URL=` | for specifying the URL of the Ferdium-server, including `http://` or `https://` as relevant. | -| `-e DB_CONNECTION=` | for specifying the database host, default is `127.0.0.1` | -| `-e DB_PORT=` | for specifying the database port, default is `3306` | -| `-e DB_USER=` | for specifying the database user, default is `root` | -| `-e DB_PASSWORD=` | for specifying the database password, default is `password` | -| `-e DB_DATABASE=` | for specifying the database name to be used, default is `ferdium` | -| `-e DB_SSL=false` | true only if your database is postgres and it is hosted online, on platforms like GCP, AWS, etc | -| `-e MAIL_CONNECTION=` | for specifying the mail sender to be used, default is `smtp` | -| `-e SMTP_HOST=` | for specifying the mail host to be used, default is `127.0.0.1` | -| `-e SMTP_PORT=` | for specifying the mail port to be used, default is `2525` | -| `-e MAIL_SSL=true/false` | for specifying SMTP mail security, default is `false` | -| `-e MAIL_USERNAME=` | for specifying your mail username to be used, default is `username` | -| `-e MAIL_PASSWORD=` | for specifying your mail password to be used, default is `password` | -| `-e MAIL_SENDER=:/data` | this will store Ferdium-server's data (its database, among other things) on the docker host for persistence. See the [Docker docs](https://docs.docker.com/storage/volumes/) for more information on the use of container volumes | -| `-v :/app/recipes` | this will store Ferdium-server's recipes on the docker host for persistence | - -By enabling the `CONNECT_WITH_FRANZ` option, Ferdium-server can: - - Show the full Franz recipe library instead of only custom recipes - - Import Franz accounts +| Parameter | Function | +| :-----------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-p :3333` | Will map the container's port 3333 to a port on the host, default is 3333. See the [Docker docs](https://docs.docker.com/config/containers/container-networking/) for more information about port mapping | +| `-e NODE_ENV=development` | for specifying Node environment, production or development, default is development **currently this should not be changed**. See the [Docker docs](https://docs.docker.com/) for more information on the use of environment variables in [Command-line](https://docs.docker.com/engine/reference/commandline/run/#mount-volume--v---read-only) and [Docker Compose](https://docs.docker.com/compose/environment-variables/) | +| `-e APP_URL=` | for specifying the URL of the Ferdium-server, including `http://` or `https://` as relevant. | +| `-e DB_CONNECTION=` | for specifying the database host, default is `127.0.0.1` | +| `-e DB_PORT=` | for specifying the database port, default is `3306` | +| `-e DB_USER=` | for specifying the database user, default is `root` | +| `-e DB_PASSWORD=` | for specifying the database password, default is `password` | +| `-e DB_DATABASE=` | for specifying the database name to be used, default is `ferdium` | +| `-e DB_SSL=false` | true only if your database is postgres and it is hosted online, on platforms like GCP, AWS, etc | +| `-e MAIL_CONNECTION=` | for specifying the mail sender to be used, default is `smtp` | +| `-e SMTP_HOST=` | for specifying the mail host to be used, default is `127.0.0.1` | +| `-e SMTP_PORT=` | for specifying the mail port to be used, default is `2525` | +| `-e MAIL_SSL=true/false` | for specifying SMTP mail security, default is `false` | +| `-e MAIL_USERNAME=` | for specifying your mail username to be used, default is `username` | +| `-e MAIL_PASSWORD=` | for specifying your mail password to be used, default is `password` | +| `-e MAIL_SENDER=:/data` | this will store Ferdium-server's data (its database, among other things) on the docker host for persistence. See the [Docker docs](https://docs.docker.com/storage/volumes/) for more information on the use of container volumes | +| `-v :/app/recipes` | this will store Ferdium-server's recipes on the docker host for persistence | + +By enabling the `CONNECT_WITH_FRANZ` option, Ferdium-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 | +| 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 | SMTP_PORT, SMTP_HOST, MAIL_USERNAME, MAIL_PASSWORD, MAIL_SSL | -| SparkPost | SPARKPOST_API_KEY | -| Mailgun | MAILGUN_DOMAIN, MAILGUN_API_REGION, MAILGUN_API_KEY | +| Mail Connection | ENV variables | +| :-----------------------: | ------------------------------------------------------------------------ | +| SMTP | SMTP_PORT, SMTP_HOST, MAIL_USERNAME, MAIL_PASSWORD, MAIL_SSL | +| SparkPost | SPARKPOST_API_KEY | +| Mailgun | MAILGUN_DOMAIN, MAILGUN_API_REGION, MAILGUN_API_KEY | | (**Deprecated**) Ethereal | A disposable account is created automatically if you choose this option. | ## Migrating from an existing Ferdium-server @@ -137,7 +138,7 @@ If you are an existing Ferdium-server user using the built-in `SQlite` database, | `-e DATA_DIR=/app/database` | existing Ferdium-server users who use the built-in sqlite database should add this environment variable to ensure data persistence | | `-v =/app/databases` | existing Ferdium-server users who use the built-in sqlite database should use the volume name `/app/database` | -If you are an existing Ferdium-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: +If you are an existing Ferdium-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 DB_CONNECTION=mysql` | for specifying the database being used | @@ -191,11 +192,12 @@ Ferdium-server allows to extends the Franz recipe catalogue with custom Ferdi re For documentation on how to create a recipe, please visit [the official guide](https://github.com/ferdium/ferdium-recipes/blob/main/docs/integration.md). 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 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 [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. +- `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. ### Listing custom recipes @@ -203,8 +205,8 @@ Inside Ferdium, searching for `ferdium:custom` will list all your custom recipes ## Support Info -* Shell access while the container is running: `docker exec -it ferdium-server /bin/bash` -* To monitor the logs of the container in realtime: `docker logs -f ferdium-server` +- Shell access while the container is running: `docker exec -it ferdium-server /bin/bash` +- To monitor the logs of the container in realtime: `docker logs -f ferdium-server` ## Updating Info @@ -212,22 +214,23 @@ Below are the instructions for updating the container to get the most recent ver ### Via Docker Run/Create -* Update the image: `docker pull ferdium/ferdium-server:latest` -* Stop the running container: `docker stop ferdium-server` -* Delete the container: `docker rm ferdium-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 ferdium-server` +- Update the image: `docker pull ferdium/ferdium-server:latest` +- Stop the running container: `docker stop ferdium-server` +- Delete the container: `docker rm ferdium-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 ferdium-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 ferdium-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 ferdium-server` +- Update all images: `docker-compose -f docker/docker-compose.yml pull` + - or update a single image: `docker-compose -f docker/docker-compose.yml pull ferdium-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 ferdium-server` ## Building locally If you want to build this image locally, please run this command from root of [Ferdium-server repository](https://github.com/ferdium/ferdium-server/tree/main/): + ``` docker build \ --no-cache \ @@ -236,4 +239,5 @@ docker build \ ``` ## License + Ferdium-server-docker and Ferdium-server are licensed under the MIT License. diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index cdf8f88..79b1a03 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -1,4 +1,4 @@ -version: "2" +version: '2' services: ferdium-server: image: ferdium-server -- cgit v1.2.3-70-g09d2