diff options
author | 2021-08-17 20:25:54 +0000 | |
---|---|---|
committer | 2021-08-17 20:25:54 +0000 | |
commit | ca11636dfe0b087b65c6e768140d46fceee1e1b5 (patch) | |
tree | 2162986c5db18da27b15edada2dbc1debed73cc3 /docker | |
parent | Bump path-parse from 1.0.6 to 1.0.7 (diff) | |
parent | Update Dockerfile (diff) | |
download | ferdium-server-ca11636dfe0b087b65c6e768140d46fceee1e1b5.tar.gz ferdium-server-ca11636dfe0b087b65c6e768140d46fceee1e1b5.tar.zst ferdium-server-ca11636dfe0b087b65c6e768140d46fceee1e1b5.zip |
Merge pull request #1 from k0staa/master
Test merge
Diffstat (limited to 'docker')
-rw-r--r-- | docker/.env | 1 | ||||
-rw-r--r-- | docker/README.md | 241 | ||||
-rw-r--r-- | docker/docker-compose.yml | 38 | ||||
-rwxr-xr-x | docker/entrypoint.sh | 37 | ||||
-rw-r--r-- | docker/logo.png | bin | 0 -> 340668 bytes |
5 files changed, 317 insertions, 0 deletions
diff --git a/docker/.env b/docker/.env new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/docker/.env | |||
@@ -0,0 +1 @@ | |||
diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000..3d8bd5f --- /dev/null +++ b/docker/README.md | |||
@@ -0,0 +1,241 @@ | |||
1 | # Ferdi-server-docker | ||
2 | [Ferdi](https://github.com/getferdi/ferdi) is a hard-fork of [Franz](https://github.com/meetfranz/franz), adding awesome features and removing unwanted ones. Ferdi-server is an unofficial replacement of the Franz server for use with the Ferdi Client. | ||
3 | |||
4 | This is a dockerized version of [Ferdi-server](https://github.com/getferdi/server) running on Alpine Linux and Node.js (v10.16.3). | ||
5 | |||
6 | ## Why use a custom Ferdi-server? | ||
7 | A custom Ferdi-server allows you to experience the full potential of the Ferdi Client. It allows you to use all Premium features (e.g. Workspaces and custom URL recipes) and [add your own recipes](#creating-and-using-custom-recipes). | ||
8 | |||
9 | ## Features | ||
10 | - [x] User registration and login | ||
11 | - [x] Service creation, download, listing and removing | ||
12 | - [x] Workspace support | ||
13 | - [x] Functioning service store | ||
14 | - [x] User dashboard | ||
15 | - [x] Password recovery | ||
16 | - [x] Export/import data to other Ferdi-servers | ||
17 | - [ ] Recipe update | ||
18 | |||
19 | ## Installation & Setup | ||
20 | |||
21 | Here are some example snippets to help you get started creating a container. | ||
22 | |||
23 | The docker can be run as is, with the default sqlite database, or you can modify your environment variables to use an external database (e.g. MySQL, MariaDB, Postgres, etc). After setting up the docker container you will need to create a reverse proxy to access Ferdi-server outside of your home network, using a webserver such as NGINX. | ||
24 | |||
25 | **Existing users, please note:** The latest updates to Ferdi-server and the Ferdi-server Docker image introduce changes to the default SQLite database name and location, as well as the internal container port. The new container port is `3333`. If you would like to keep your existing SQLite database, you will need to add the `DATA_DIR` variable and change it to `/app/database`, to match your existing data volume. You will also need to change the `DB_DATABASE` variable to `development` to match your existing database. Please see the parameters in the [Migration section](#migrating-from-an-existing-ferdi-server) below. | ||
26 | |||
27 | ### docker | ||
28 | |||
29 | Pull the docker image: | ||
30 | |||
31 | docker pull getferdi/ferdi-server | ||
32 | |||
33 | To create the docker container with the proper parameters: | ||
34 | |||
35 | docker create \ | ||
36 | --name=ferdi-server \ | ||
37 | -e NODE_ENV=development \ | ||
38 | -e EXTERNAL_DOMAIN=<ferdi-serverdomain> \ | ||
39 | -e DB_CONNECTION=<database> \ | ||
40 | -e DB_HOST=<yourdbhost> \ | ||
41 | -e DB_PORT=<yourdbport> \ | ||
42 | -e DB_USER=<yourdbuser> \ | ||
43 | -e DB_PASSWORD=<yourdbpass> \ | ||
44 | -e DB_DATABASE=<yourdbdatabase> \ | ||
45 | -e DB_SSL=false \ | ||
46 | -e MAIL_CONNECTION=smtp \ | ||
47 | -e SMPT_HOST=<smtpmailserver> \ | ||
48 | -e SMTP_PORT=<smtpport> \ | ||
49 | -e MAIL_SSL=true/false \ | ||
50 | -e MAIL_USERNAME=<yourmailusername> \ | ||
51 | -e MAIL_PASSWORD=<yourmailpassword> \ | ||
52 | -e MAIL_SENDER=<sendemailaddress> \ | ||
53 | -e IS_CREATION_ENABLED=true \ | ||
54 | -e IS_DASHBOARD_ENABLED=true \ | ||
55 | -e IS_REGISTRATION_ENABLED=true \ | ||
56 | -e CONNECT_WITH_FRANZ=true \ | ||
57 | -e DATA_DIR=/data \ | ||
58 | -p <port>:3333 \ | ||
59 | -v <path to data>:/data \ | ||
60 | -v <path to recipes>:/app/recipes \ | ||
61 | --restart unless-stopped \ | ||
62 | getferdi/ferdi-server | ||
63 | |||
64 | ### docker-compose | ||
65 | |||
66 | You can use the provided sample [docker-compose.yml](https://github.com/getferdi/server/tree/master/docker/docker-compose.yml) if you are happy with the default environmental variables. This will pull the latest image from Docker Hub or use a local copy of the image which you can build using the instructions provided in the [Building locally section](#building-locally). | ||
67 | |||
68 | To start the application, use `docker-compose up -d`. | ||
69 | The server will be launched at [http://localhost:3333/](http://localhost:3333/) address. | ||
70 | |||
71 | ## Configuration | ||
72 | |||
73 | Container images are configured using parameters passed at runtime (such as those above). An explanaition of the default parameters is included below, but please see [the Docker documentation](https://docs.docker.com/get-started/overview/) for additional information. | ||
74 | |||
75 | <strike>If any environmental 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 environmental variables to your container at runtime. ** | ||
77 | |||
78 | | Parameter | Function | | ||
79 | | :----: | --- | | ||
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 | | ||
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 environmental 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 EXTERNAL_DOMAIN=<ferdi-serverdomain>` | for specifying the external domain address of the Ferdi-server | | ||
83 | | `-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 | | ||
85 | | `-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 | | ||
87 | | `-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 ferdi | | ||
89 | | `-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 | | ||
91 | | `-e SMPT_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 | | ||
93 | | `-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 | | ||
95 | | `-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@getferdi.com | | ||
97 | | `-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 Ferdi-server dashboard, default is true | | ||
99 | | `-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 | | ||
101 | | `-e DATA_DIR=data` | for specifying the SQLite database folder, default is data | | ||
102 | | `-v <path to data on host>:/data` | this will store Ferdi-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 Ferdi-server's recipes on the docker host for persistence | | ||
104 | |||
105 | By enabling the `CONNECT_WITH_FRANZ` option, Ferdi-server can: | ||
106 | - Show the full Franz recipe library instead of only custom recipes | ||
107 | - Import Franz accounts | ||
108 | |||
109 | ## Supported databases and drivers | ||
110 | |||
111 | To use a different database than the default, SQLite3, enter the driver code below in your ENV configuration. | ||
112 | |||
113 | | Database | Driver | | ||
114 | | :----: | --- | | ||
115 | | MariaDB/MySQL | mysql | | ||
116 | | PostgreSQL | pg | | ||
117 | | SQLite3 | sqlite | | ||
118 | |||
119 | ## Supported mail connections (advanced) | ||
120 | |||
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 | |||
123 | | Mail Connection | ENV variables | | ||
124 | | :----: | --- | | ||
125 | | SMTP | SMTP_PORT, SMTP_HOST, MAIL_USERNAME, MAIL_PASSWORD, MAIL_SSL | | ||
126 | | SparkPost | SPARKPOST_API_KEY | | ||
127 | | Mailgun | MAILGUN_DOMAIN, MAILGUN_API_REGION, MAILGUN_API_KEY | | ||
128 | | (**Deprecated**) Ethereal | A disposable account is created automatically if you choose this option. | | ||
129 | |||
130 | ## Migrating from an existing Ferdi-server | ||
131 | |||
132 | If you are an existing Ferdi-server user using the built-in `SQlite` database, you should include the following variables: | ||
133 | | Parameter | Function | | ||
134 | | :----: | --- | | ||
135 | | `-p 3333:3333` | existing Ferdi-server users will need to update their container port mappings from `80:3333` to `3333:3333` | | ||
136 | | `-e DB_PASSWORD=development` | existing Ferdi-server users who use the built-in sqlite database should use the database name `development` | | ||
137 | | `-e DATA_DIR=/app/database` | existing Ferdi-server users who use the built-in sqlite database should add this environmental variable to ensure data persistence | | ||
138 | | `-v <path to data on host>=/app/databases` | existing Ferdi-server users who use the built-in sqlite database should use the volume name `/app/database` | | ||
139 | |||
140 | If you are an existing Ferdi-server user who usees an external database or different variables for the built-in `SQlite` database, you should updatae your parameterse acordingly. For exaple, if you aree using an exterenal MariaDB or MYSql database your unique parameters might look like this: | ||
141 | | Parameter | Function | | ||
142 | | :----: | --- | | ||
143 | | `-e DB_CONNECTION=mysql` | for specifying the database being used | | ||
144 | | `-e DB_HOST=192.168.10.1` | for specifying the database host machine IP | | ||
145 | | `-e DB_PORT=3306` | for specifying the database port | | ||
146 | | `-e DB_USER=ferdi` | for specifying the database user | | ||
147 | | `-e DB_PASSWORD=ferdipw` | for specifying the database password| | ||
148 | | `-e DB_DATABASE=adonis` | for specifying the database to be used| | ||
149 | | `-v <path to database>:/app/database` | this will strore Ferdi-server's database on the docker host for persistence | | ||
150 | | `-v <path to recipes>:/app/recipes` | this will strore Ferdi-server's recipes on the docker host for persistence | | ||
151 | |||
152 | **In eithr case, pleasee be sure to pass the correct variables to the new Ferdi-server container in order maintain access to your existing database.** | ||
153 | |||
154 | ## NGINX config block | ||
155 | |||
156 | To access Ferdi-server from outside of your home network on a subdomain use this server block: | ||
157 | |||
158 | ``` | ||
159 | # Ferdi-server | ||
160 | server { | ||
161 | listen 443 ssl http2; | ||
162 | server_name ferdi.my.website; | ||
163 | |||
164 | # all ssl related config moved to ssl.conf | ||
165 | include /config/nginx/ssl.conf; | ||
166 | |||
167 | location / { | ||
168 | proxy_pass http://<Ferdi-IP>:3333; | ||
169 | proxy_set_header X-Real-IP $remote_addr; | ||
170 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; | ||
171 | proxy_set_header Host $host; | ||
172 | proxy_set_header X-Forwarded-Proto $scheme; | ||
173 | } | ||
174 | } | ||
175 | ``` | ||
176 | |||
177 | ## Importing your Franz account | ||
178 | |||
179 | Ferdi-server allows you to import your full Franz account, including all its settings. | ||
180 | |||
181 | 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. | ||
182 | |||
183 | ## Transferring user data | ||
184 | |||
185 | Please refer to <https://github.com/getferdi/ferdi/wiki/Transferring-data-between-servers> | ||
186 | |||
187 | ## Creating and using custom recipes | ||
188 | |||
189 | Ferdi-server allows to extends the Franz recipe catalogue with custom Ferdi recipes. | ||
190 | |||
191 | For documentation on how to create a recipe, please visit [the official guide by Franz](https://github.com/meetfranz/plugins/blob/master/docs/integration.md). | ||
192 | |||
193 | To add your recipe to Ferdi-server, open `http://[YOUR FERDI-SERVER]/new` in your browser. You can now define the following settings: | ||
194 | - `Author`: Author who created the recipe | ||
195 | - `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`) | ||
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 | ||
198 | - `Recipe files`: Recipe files that you created using the [Franz recipe creation guide](https://github.com/meetfranz/plugins/blob/master/docs/integration.md). 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. | ||
199 | |||
200 | ### Listing custom recipes | ||
201 | |||
202 | Inside Ferdi, searching for `ferdi:custom` will list all your custom recipes. | ||
203 | |||
204 | ## Support Info | ||
205 | |||
206 | * Shell access while the container is running: `docker exec -it ferdi-server /bin/bash` | ||
207 | * To monitor the logs of the container in realtime: `docker logs -f ferdi-server` | ||
208 | |||
209 | ## Updating Info | ||
210 | |||
211 | Below are the instructions for updating the container to get the most recent version of Ferdi-server: | ||
212 | |||
213 | ### Via Docker Run/Create | ||
214 | |||
215 | * Update the image: `docker pull getferdi/ferdi-server` | ||
216 | * Stop the running container: `docker stop ferdi-server` | ||
217 | * Delete the container: `docker rm ferdi-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) | ||
219 | * Start the new container: `docker start ferdi-server` | ||
220 | * You can also remove the old dangling images: `docker image prune` | ||
221 | |||
222 | ### Via Docker Compose | ||
223 | |||
224 | * Update all images: `docker-compose pull` | ||
225 | * or update a single image: `docker-compose pull ferdi-server` | ||
226 | * Let compose update all containers as necessary: `docker-compose up -d` | ||
227 | * or update a single container: `docker-compose up -d ferdi-server` | ||
228 | * You can also remove the old dangling images: `docker image prune` | ||
229 | |||
230 | ## Building locally | ||
231 | |||
232 | If you want to build this image locally, please run this command from root of [Ferdi-server repository](https://github.com/getferdi/server/tree/master/): | ||
233 | ``` | ||
234 | docker build \ | ||
235 | --no-cache \ | ||
236 | --pull \ | ||
237 | -t getferdi/ferdi-server:latest . | ||
238 | ``` | ||
239 | |||
240 | ## License | ||
241 | Ferdi-server-docker and Ferdi-server are licensed under the MIT License. | ||
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml new file mode 100644 index 0000000..bd66ba2 --- /dev/null +++ b/docker/docker-compose.yml | |||
@@ -0,0 +1,38 @@ | |||
1 | version: "2" | ||
2 | services: | ||
3 | ferdi-server: | ||
4 | image: getferdi/ferdi-server | ||
5 | container_name: ferdi-server | ||
6 | environment: | ||
7 | - NODE_ENV=development | ||
8 | - EXTERNAL_DOMAIN=localhost | ||
9 | - DB_CONNECTION=sqlite | ||
10 | - DB_HOST=127.0.0.1 | ||
11 | - DB_PORT=3306 | ||
12 | - DB_USER=root | ||
13 | - DB_PASSWORD=password | ||
14 | - DB_DATABASE=ferdi | ||
15 | - DB_SSL=false | ||
16 | - MAIL_CONNECTION=smtp | ||
17 | - SMPT_HOST=127.0.0.1 | ||
18 | - SMTP_PORT=2525 | ||
19 | - MAIL_SSL=false | ||
20 | - MAIL_USERNAME=username | ||
21 | - MAIL_PASSWORD=password | ||
22 | - MAIL_SENDER=noreply@getferdi.com | ||
23 | - IS_CREATION_ENABLED=true | ||
24 | - IS_DASHBOARD_ENABLED=true | ||
25 | - IS_REGISTRATION_ENABLED=true | ||
26 | - CONNECT_WITH_FRANZ=false | ||
27 | - DATA_DIR=/data | ||
28 | - PUID=1000 | ||
29 | - PGID=1000 | ||
30 | volumes: | ||
31 | - ferdi-database-vol:/data | ||
32 | - ferdi-recipes-vol:/app/recipes | ||
33 | ports: | ||
34 | - 3333:3333 | ||
35 | restart: unless-stopped | ||
36 | volumes: | ||
37 | ferdi-database-vol: | ||
38 | ferdi-recipes-vol: | ||
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh new file mode 100755 index 0000000..0679530 --- /dev/null +++ b/docker/entrypoint.sh | |||
@@ -0,0 +1,37 @@ | |||
1 | #!/bin/sh | ||
2 | |||
3 | echo << EOL | ||
4 | ------------------------------------- | ||
5 | ____ ___ | ||
6 | / __/__ _______/ (_) | ||
7 | / _// -_) __/ _ / / | ||
8 | _/_/ \__/_/ \_,_/_/ | ||
9 | / __/__ _____ _____ ____ | ||
10 | _\ \/ -_) __/ |/ / -_) __/ | ||
11 | /___/\__/_/ |___/\__/_/ | ||
12 | Brought to you by getferdi.com | ||
13 | Support our Open Collective at: | ||
14 | https://opencollective.com/getferdi/ | ||
15 | EOL | ||
16 | |||
17 | # Create APP key if needed | ||
18 | if [[ -f "${DATA_DIR}/FERDI_APP_KEY.txt" ]]; then | ||
19 | echo " " | ||
20 | echo "**** App Key found ****" | ||
21 | APP_KEY=$(echo "${APP_KEY}") | ||
22 | echo "**** App Key set to $APP_KEY you can modify FERDI_APP_KEY.txt to update your key ****" | ||
23 | elif [[ -z "${APP_KEY}" ]]; then | ||
24 | echo "**** Generating Ferdi-server app key for first run ****" | ||
25 | adonis key:generate | ||
26 | APP_KEY=$(grep APP_KEY .env | cut -d '=' -f2) | ||
27 | echo "${APP_KEY}" > "${DATA_DIR}/FERDI_APP_KEY.txt" | ||
28 | echo "**** App Key set to $APP_KEY you can modify FERDI_APP_KEY.txt to update your key ****" | ||
29 | fi | ||
30 | |||
31 | export APP_KEY | ||
32 | |||
33 | node ace migration:run --force | ||
34 | |||
35 | chown -R ${PUID:-1000}:${PGID:-1000} $DATA_DIR /app | ||
36 | |||
37 | su-exec ${PUID:-1000}:${PGID:-1000} node server.js | ||
diff --git a/docker/logo.png b/docker/logo.png new file mode 100644 index 0000000..587e0b8 --- /dev/null +++ b/docker/logo.png | |||
Binary files differ | |||