aboutsummaryrefslogtreecommitdiffstats
path: root/docker/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'docker/README.md')
-rw-r--r--docker/README.md166
1 files changed, 85 insertions, 81 deletions
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 @@
1# Ferdium-server-docker 1# Ferdium-server-docker
2
2[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. 3[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.
3 4
4This is a dockerized version of [Ferdium-server](https://github.com/ferdium/ferdium-server) running on Alpine Linux and Node.js (v10.16.3). 5This is a dockerized version of [Ferdium-server](https://github.com/ferdium/ferdium-server) running on Alpine Linux and Node.js (v10.16.3).
5 6
6## Why use a custom Ferdium-server? 7## Why use a custom Ferdium-server?
8
7A 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. 9A 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.
8 10
9## Features 11## Features
12
10- [x] User registration and login 13- [x] User registration and login
11- [x] Service creation, download, listing and removing 14- [x] Service creation, download, listing and removing
12- [x] Workspace support 15- [x] Workspace support
@@ -32,34 +35,34 @@ Pull the docker image:
32 35
33To create the docker container with the proper parameters: 36To create the docker container with the proper parameters:
34 37
35 docker create \ 38 docker create \
36 --name=ferdium-server \ 39 --name=ferdium-server \
37 -e NODE_ENV=development \ 40 -e NODE_ENV=development \
38 -e APP_URL=<ferdium-server-url> \ 41 -e APP_URL=<ferdium-server-url> \
39 -e DB_CONNECTION=<database> \ 42 -e DB_CONNECTION=<database> \
40 -e DB_HOST=<yourdbhost> \ 43 -e DB_HOST=<yourdbhost> \
41 -e DB_PORT=<yourdbport> \ 44 -e DB_PORT=<yourdbport> \
42 -e DB_USER=<yourdbuser> \ 45 -e DB_USER=<yourdbuser> \
43 -e DB_PASSWORD=<yourdbpass> \ 46 -e DB_PASSWORD=<yourdbpass> \
44 -e DB_DATABASE=<yourdbdatabase> \ 47 -e DB_DATABASE=<yourdbdatabase> \
45 -e DB_SSL=false \ 48 -e DB_SSL=false \
46 -e MAIL_CONNECTION=smtp \ 49 -e MAIL_CONNECTION=smtp \
47 -e SMTP_HOST=<smtpmailserver> \ 50 -e SMTP_HOST=<smtpmailserver> \
48 -e SMTP_PORT=<smtpport> \ 51 -e SMTP_PORT=<smtpport> \
49 -e MAIL_SSL=true/false \ 52 -e MAIL_SSL=true/false \
50 -e MAIL_USERNAME=<yourmailusername> \ 53 -e MAIL_USERNAME=<yourmailusername> \
51 -e MAIL_PASSWORD=<yourmailpassword> \ 54 -e MAIL_PASSWORD=<yourmailpassword> \
52 -e MAIL_SENDER=<sendemailaddress> \ 55 -e MAIL_SENDER=<sendemailaddress> \
53 -e IS_CREATION_ENABLED=true \ 56 -e IS_CREATION_ENABLED=true \
54 -e IS_DASHBOARD_ENABLED=true \ 57 -e IS_DASHBOARD_ENABLED=true \
55 -e IS_REGISTRATION_ENABLED=true \ 58 -e IS_REGISTRATION_ENABLED=true \
56 -e CONNECT_WITH_FRANZ=true \ 59 -e CONNECT_WITH_FRANZ=true \
57 -e DATA_DIR=/data \ 60 -e DATA_DIR=/data \
58 -p <port>:3333 \ 61 -p <port>:3333 \
59 -v <path to data>:/data \ 62 -v <path to data>:/data \
60 -v <path to recipes>:/app/recipes \ 63 -v <path to recipes>:/app/recipes \
61 --restart unless-stopped \ 64 --restart unless-stopped \
62 ferdium/ferdium-server:latest 65 ferdium/ferdium-server:latest
63 66
64### docker-compose 67### docker-compose
65 68
@@ -75,56 +78,54 @@ Container images are configured using parameters passed at runtime (such as thos
75<strike>If any environment parameter is not passed to the container, its value will be taken from the `/config/config.txt` file.</strike> 78<strike>If any environment parameter is not passed to the container, its value will be taken from the `/config/config.txt` file.</strike>
76**Warning, the use of `config.txt` is now deprecated. Please make sure to pass the correct environment variables to your container at runtime. ** 79**Warning, the use of `config.txt` is now deprecated. Please make sure to pass the correct environment variables to your container at runtime. **
77 80
78| Parameter | Function | 81| Parameter | Function |
79| :----: | --- | 82| :-----------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80| `-p <port>: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 | 83| `-p <port>: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 |
81| `-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/) | 84| `-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/) |
82| `-e APP_URL=<ferdium-server-url>` | for specifying the URL of the Ferdium-server, including `http://` or `https://` as relevant. | 85| `-e APP_URL=<ferdium-server-url>` | for specifying the URL of the Ferdium-server, including `http://` or `https://` as relevant. |
83| `-e DB_CONNECTION=<databasedriver` | for specifying the database being used, default is `sqlite`, see [below](#supported-databases-and-drivers) for other options | 86| `-e DB_CONNECTION=<databasedriver` | for specifying the database being used, default is `sqlite`, see [below](#supported-databases-and-drivers) for other options |
84| `-e DB_HOST=<yourdbhost>` | for specifying the database host, default is `127.0.0.1` | 87| `-e DB_HOST=<yourdbhost>` | for specifying the database host, default is `127.0.0.1` |
85| `-e DB_PORT=<yourdbport>` | for specifying the database port, default is `3306` | 88| `-e DB_PORT=<yourdbport>` | for specifying the database port, default is `3306` |
86| `-e DB_USER=<yourdbuser>` | for specifying the database user, default is `root` | 89| `-e DB_USER=<yourdbuser>` | for specifying the database user, default is `root` |
87| `-e DB_PASSWORD=<yourdbpass>` | for specifying the database password, default is `password` | 90| `-e DB_PASSWORD=<yourdbpass>` | for specifying the database password, default is `password` |
88| `-e DB_DATABASE=<databasename>` | for specifying the database name to be used, default is `ferdium` | 91| `-e DB_DATABASE=<databasename>` | for specifying the database name to be used, default is `ferdium` |
89| `-e DB_SSL=false` | true only if your database is postgres and it is hosted online, on platforms like GCP, AWS, etc | 92| `-e DB_SSL=false` | true only if your database is postgres and it is hosted online, on platforms like GCP, AWS, etc |
90| `-e MAIL_CONNECTION=<mailsender>` | for specifying the mail sender to be used, default is `smtp` | 93| `-e MAIL_CONNECTION=<mailsender>` | for specifying the mail sender to be used, default is `smtp` |
91| `-e SMTP_HOST=<smtpmailserver>` | for specifying the mail host to be used, default is `127.0.0.1` | 94| `-e SMTP_HOST=<smtpmailserver>` | for specifying the mail host to be used, default is `127.0.0.1` |
92| `-e SMTP_PORT=<smtpport>` | for specifying the mail port to be used, default is `2525` | 95| `-e SMTP_PORT=<smtpport>` | for specifying the mail port to be used, default is `2525` |
93| `-e MAIL_SSL=true/false` | for specifying SMTP mail security, default is `false` | 96| `-e MAIL_SSL=true/false` | for specifying SMTP mail security, default is `false` |
94| `-e MAIL_USERNAME=<yourmailusername>` | for specifying your mail username to be used, default is `username` | 97| `-e MAIL_USERNAME=<yourmailusername>` | for specifying your mail username to be used, default is `username` |
95| `-e MAIL_PASSWORD=<yourmailpassword>` | for specifying your mail password to be used, default is `password` | 98| `-e MAIL_PASSWORD=<yourmailpassword>` | for specifying your mail password to be used, default is `password` |
96| `-e MAIL_SENDER=<sendemailaddress` | for specifying the mail sender address to be used, default is `noreply@ferdium.org` | 99| `-e MAIL_SENDER=<sendemailaddress` | for specifying the mail sender address to be used, default is `noreply@ferdium.org` |
97| `-e IS_CREATION_ENABLED=true` | for specifying whether to enable the [creation of custom recipes](#creating-and-using-custom-recipes), default is `true` | 100| `-e IS_CREATION_ENABLED=true` | for specifying whether to enable the [creation of custom recipes](#creating-and-using-custom-recipes), default is `true` |
98| `-e IS_DASHBOARD_ENABLED=true` | for specifying whether to enable the Ferdium-server dashboard, default is `true` | 101| `-e IS_DASHBOARD_ENABLED=true` | for specifying whether to enable the Ferdium-server dashboard, default is `true` |
99| `-e IS_REGISTRATION_ENABLED=true` | for specifying whether to allow user registration, default is `true` | 102| `-e IS_REGISTRATION_ENABLED=true` | for specifying whether to allow user registration, default is `true` |
100| `-e CONNECT_WITH_FRANZ=true` | for specifying whether to enable connections to the Franz server, default is `true` | 103| `-e CONNECT_WITH_FRANZ=true` | for specifying whether to enable connections to the Franz server, default is `true` |
101| `-e DATA_DIR=/data` | for specifying the SQLite database folder, default is `/data` | 104| `-e DATA_DIR=/data` | for specifying the SQLite database folder, default is `/data` |
102| `-v <path to data on host>:/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 | 105| `-v <path to data on host>:/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 |
103| `-v <path to recipes on host>:/app/recipes` | this will store Ferdium-server's recipes on the docker host for persistence | 106| `-v <path to recipes on host>:/app/recipes` | this will store Ferdium-server's recipes on the docker host for persistence |
104 107
105By enabling the `CONNECT_WITH_FRANZ` option, Ferdium-server can: 108By enabling the `CONNECT_WITH_FRANZ` option, Ferdium-server can: - Show the full Franz recipe library instead of only custom recipes - Import Franz accounts
106 - Show the full Franz recipe library instead of only custom recipes
107 - Import Franz accounts
108 109
109## Supported databases and drivers 110## Supported databases and drivers
110 111
111To use a different database than the default, SQLite3, enter the driver code below in your ENV configuration. 112To use a different database than the default, SQLite3, enter the driver code below in your ENV configuration.
112 113
113| Database | Driver | 114| Database | Driver |
114| :----: | --- | 115| :-----------: | ------ |
115| MariaDB/MySQL | mysql | 116| MariaDB/MySQL | mysql |
116| PostgreSQL | pg | 117| PostgreSQL | pg |
117| SQLite3 | sqlite | 118| SQLite3 | sqlite |
118 119
119## Supported mail connections (advanced) 120## Supported mail connections (advanced)
120 121
121To 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. 122To 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.
122 123
123| Mail Connection | ENV variables | 124| Mail Connection | ENV variables |
124| :----: | --- | 125| :-----------------------: | ------------------------------------------------------------------------ |
125| SMTP | SMTP_PORT, SMTP_HOST, MAIL_USERNAME, MAIL_PASSWORD, MAIL_SSL | 126| SMTP | SMTP_PORT, SMTP_HOST, MAIL_USERNAME, MAIL_PASSWORD, MAIL_SSL |
126| SparkPost | SPARKPOST_API_KEY | 127| SparkPost | SPARKPOST_API_KEY |
127| Mailgun | MAILGUN_DOMAIN, MAILGUN_API_REGION, MAILGUN_API_KEY | 128| Mailgun | MAILGUN_DOMAIN, MAILGUN_API_REGION, MAILGUN_API_KEY |
128| (**Deprecated**) Ethereal | A disposable account is created automatically if you choose this option. | 129| (**Deprecated**) Ethereal | A disposable account is created automatically if you choose this option. |
129 130
130## Migrating from an existing Ferdium-server 131## Migrating from an existing Ferdium-server
@@ -137,7 +138,7 @@ If you are an existing Ferdium-server user using the built-in `SQlite` database,
137| `-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 | 138| `-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 |
138| `-v <path to data on host>=/app/databases` | existing Ferdium-server users who use the built-in sqlite database should use the volume name `/app/database` | 139| `-v <path to data on host>=/app/databases` | existing Ferdium-server users who use the built-in sqlite database should use the volume name `/app/database` |
139 140
140If 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: 141If 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:
141| Parameter | Function | 142| Parameter | Function |
142| :----: | --- | 143| :----: | --- |
143| `-e DB_CONNECTION=mysql` | for specifying the database being used | 144| `-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
191For documentation on how to create a recipe, please visit [the official guide](https://github.com/ferdium/ferdium-recipes/blob/main/docs/integration.md). 192For documentation on how to create a recipe, please visit [the official guide](https://github.com/ferdium/ferdium-recipes/blob/main/docs/integration.md).
192 193
193To add your recipe to Ferdium-server, open `http://[YOUR FERDIUM-SERVER]/new` in your browser. You can now define the following settings: 194To add your recipe to Ferdium-server, open `http://[YOUR FERDIUM-SERVER]/new` in your browser. You can now define the following settings:
195
194- `Author`: Author who created the recipe 196- `Author`: Author who created the recipe
195- `Name`: Name for your new service. Can contain spaces and unicode characters 197- `Name`: Name for your new service. Can contain spaces and unicode characters
196- `Service ID`: Unique ID for this recipe. Does not contain spaces or special characters (e.g. `google-drive`) 198- `Service ID`: Unique ID for this recipe. Does not contain spaces or special characters (e.g. `google-drive`)
197- `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 199- `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
198- `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. 200- `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.
199 201
200### Listing custom recipes 202### Listing custom recipes
201 203
@@ -203,8 +205,8 @@ Inside Ferdium, searching for `ferdium:custom` will list all your custom recipes
203 205
204## Support Info 206## Support Info
205 207
206* Shell access while the container is running: `docker exec -it ferdium-server /bin/bash` 208- Shell access while the container is running: `docker exec -it ferdium-server /bin/bash`
207* To monitor the logs of the container in realtime: `docker logs -f ferdium-server` 209- To monitor the logs of the container in realtime: `docker logs -f ferdium-server`
208 210
209## Updating Info 211## Updating Info
210 212
@@ -212,22 +214,23 @@ Below are the instructions for updating the container to get the most recent ver
212 214
213### Via Docker Run/Create 215### Via Docker Run/Create
214 216
215* Update the image: `docker pull ferdium/ferdium-server:latest` 217- Update the image: `docker pull ferdium/ferdium-server:latest`
216* Stop the running container: `docker stop ferdium-server` 218- Stop the running container: `docker stop ferdium-server`
217* Delete the container: `docker rm ferdium-server` 219- Delete the container: `docker rm ferdium-server`
218* 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) 220- 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)
219* Start the new container: `docker start ferdium-server` 221- Start the new container: `docker start ferdium-server`
220 222
221### Via Docker Compose 223### Via Docker Compose
222 224
223* Update all images: `docker-compose -f docker/docker-compose.yml pull` 225- Update all images: `docker-compose -f docker/docker-compose.yml pull`
224 * or update a single image: `docker-compose -f docker/docker-compose.yml pull ferdium-server` 226 - or update a single image: `docker-compose -f docker/docker-compose.yml pull ferdium-server`
225* Let compose update all containers as necessary: `docker-compose -f docker/docker-compose.yml up -d` 227- Let compose update all containers as necessary: `docker-compose -f docker/docker-compose.yml up -d`
226 * or update a single container: `docker-compose -f docker/docker-compose.yml up -d ferdium-server` 228 - or update a single container: `docker-compose -f docker/docker-compose.yml up -d ferdium-server`
227 229
228## Building locally 230## Building locally
229 231
230If 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/): 232If 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/):
233
231``` 234```
232docker build \ 235docker build \
233 --no-cache \ 236 --no-cache \
@@ -236,4 +239,5 @@ docker build \
236``` 239```
237 240
238## License 241## License
242
239Ferdium-server-docker and Ferdium-server are licensed under the MIT License. 243Ferdium-server-docker and Ferdium-server are licensed under the MIT License.
generated by cgit v1.2.3-54-g00ecf (git 2.45.2) at 2024-07-17 15:55:52 +0000