diff options
Diffstat (limited to 'docker/README.md')
-rw-r--r-- | docker/README.md | 166 |
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 | ||
4 | This is a dockerized version of [Ferdium-server](https://github.com/ferdium/ferdium-server) running on Alpine Linux and Node.js (v10.16.3). | 5 | This 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 | |||
7 | 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. | 9 | 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. |
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 | ||
33 | To create the docker container with the proper parameters: | 36 | To 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 | ||
105 | By enabling the `CONNECT_WITH_FRANZ` option, Ferdium-server can: | 108 | By 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 | ||
111 | To use a different database than the default, SQLite3, enter the driver code below in your ENV configuration. | 112 | To 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 | ||
121 | 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. | 122 | 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. |
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 | ||
140 | 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: | 141 | 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: |
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 | |||
191 | For documentation on how to create a recipe, please visit [the official guide](https://github.com/ferdium/ferdium-recipes/blob/main/docs/integration.md). | 192 | For 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 | ||
193 | To add your recipe to Ferdium-server, open `http://[YOUR FERDIUM-SERVER]/new` in your browser. You can now define the following settings: | 194 | To 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 | ||
230 | 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/): | 232 | 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/): |
233 | |||
231 | ``` | 234 | ``` |
232 | docker build \ | 235 | docker build \ |
233 | --no-cache \ | 236 | --no-cache \ |
@@ -236,4 +239,5 @@ docker build \ | |||
236 | ``` | 239 | ``` |
237 | 240 | ||
238 | ## License | 241 | ## License |
242 | |||
239 | Ferdium-server-docker and Ferdium-server are licensed under the MIT License. | 243 | Ferdium-server-docker and Ferdium-server are licensed under the MIT License. |