diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 93 |
1 files changed, 29 insertions, 64 deletions
@@ -2,10 +2,10 @@ | |||
2 | <img src="./logo.png" alt="" width="300"/> | 2 | <img src="./logo.png" alt="" width="300"/> |
3 | </p> | 3 | </p> |
4 | 4 | ||
5 | # ferdi-server | 5 | # Ferdi-server |
6 | Official Server software for the [Ferdi Messaging Browser](https://getferdi.com) | 6 | Official Server software for the [Ferdi Messaging Browser](https://getferdi.com) |
7 | 7 | ||
8 | - [ferdi-server](#ferdi-server) | 8 | - [Ferdi-server](#ferdi-server) |
9 | - [Why use a custom Ferdi server?](#why-use-a-custom-ferdi-server) | 9 | - [Why use a custom Ferdi server?](#why-use-a-custom-ferdi-server) |
10 | - [Features](#features) | 10 | - [Features](#features) |
11 | - [Setup](#setup) | 11 | - [Setup](#setup) |
@@ -16,13 +16,13 @@ Official Server software for the [Ferdi Messaging Browser](https://getferdi.com) | |||
16 | - [Transferring user data](#transferring-user-data) | 16 | - [Transferring user data](#transferring-user-data) |
17 | - [Creating and using custom recipes](#creating-and-using-custom-recipes) | 17 | - [Creating and using custom recipes](#creating-and-using-custom-recipes) |
18 | - [Listing custom recipes](#listing-custom-recipes) | 18 | - [Listing custom recipes](#listing-custom-recipes) |
19 | - [Contributing to ferdi-server's development](#contributing-to-ferdi-servers-development) | 19 | - [Contributing to Ferdi-server's development](#contributing-to-ferdi-servers-development) |
20 | - [License](#license) | 20 | - [License](#license) |
21 | 21 | ||
22 | ## Why use a custom Ferdi server? | 22 | ## Why use a custom Ferdi-server? |
23 | A custom server allows you to manage the data of all registered users yourself and add your own recipes to the repository. | 23 | A custom server allows you to manage the data of all registered users yourself and add your own recipes to the repository. |
24 | 24 | ||
25 | If you are not interested in doing this you can use our official instance of Ferdi server at <https://api.getferdi.com>. | 25 | If you are not interested in doing this you can use our official instance of Ferdi-server at <https://api.getferdi.com>. |
26 | 26 | ||
27 | ## Features | 27 | ## Features |
28 | - [x] User registration and login | 28 | - [x] User registration and login |
@@ -30,23 +30,25 @@ If you are not interested in doing this you can use our official instance of Fer | |||
30 | - [x] Workspace support | 30 | - [x] Workspace support |
31 | - [x] Functioning service store | 31 | - [x] Functioning service store |
32 | - [x] User dashboard | 32 | - [x] User dashboard |
33 | - [x] Export/import data to other ferdi-servers | 33 | - [x] Export/import data to other Ferdi-servers |
34 | - [ ] Password recovery | 34 | - [ ] Password recovery |
35 | - [ ] Recipe update | 35 | - [ ] Recipe update |
36 | 36 | ||
37 | ## Setup | 37 | ## Setup |
38 | ### with Docker | 38 | ### with Docker |
39 | The easiest way to set up Ferdi server on your server is with Docker. | 39 | The easiest way to set up Ferdi-server on your server is with Docker. |
40 | 40 | ||
41 | The Docker image can be run as is, with the default sqlite database or you can modifying your ENV variables to use an external database (e.g. MySQL, MariaDB, Postgres, etc). | 41 | The 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). |
42 | After setting up the docker container we recommend you to set up an NGINX reverse proxy to access ferdi-server outside of your home network and protect it with an SSL certificate. | 42 | After setting up the docker container we recommend you set up an NGINX reverse proxy to access Ferdi-server outside of your home network and protect it with an SSL certificate. |
43 | |||
44 | **Warning**, please note that the use of the previous `config.txt` is now deprecated and a number of environmental 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 environmental variables to your container at runtime. If you are an existing Ferdi-server user, please see [the Ferdi docker documentation](./docker/README.md) for more information about migrating to the new image. | ||
43 | 45 | ||
44 | 1. Pull the Docker image | 46 | 1. Pull the Docker image |
45 | 47 | ||
46 | ```sh | 48 | ```sh |
47 | docker pull getferdi/ferdi-server | 49 | docker pull getferdi/ferdi-server |
48 | ``` | 50 | ``` |
49 | 2. Create a new Docker container with your desired configuration | 51 | 2. Create a *new* Docker container with your desired configuration **Existing users please seee the warning above.** |
50 | 52 | ||
51 | ```sh | 53 | ```sh |
52 | docker create \ | 54 | docker create \ |
@@ -71,56 +73,19 @@ After setting up the docker container we recommend you to set up an NGINX revers | |||
71 | -e IS_DASHBOARD_ENABLED=true \ | 73 | -e IS_DASHBOARD_ENABLED=true \ |
72 | -e IS_REGISTRATION_ENABLED=true \ | 74 | -e IS_REGISTRATION_ENABLED=true \ |
73 | -e CONNECT_WITH_FRANZ=true \ | 75 | -e CONNECT_WITH_FRANZ=true \ |
74 | -p <port>:80 \ | 76 | -e DATA_DIR=data \ |
75 | -v <path to data>:/config \ | 77 | -p <port>:3333 \ |
76 | -v <path to database>:/app/database \ | 78 | -v <path to data>:/data \ |
77 | -v <path to recipes>:/app/recipes \ | 79 | -v <path to recipes>:/app/recipes \ |
78 | --restart unless-stopped \ | 80 | --restart unless-stopped \ |
79 | getferdi/ferdi-server | 81 | getferdi/ferdi-server |
80 | ``` | 82 | ``` |
81 | 83 | ||
82 | Alternatively, you can also use docker-compose v2 schemas | 84 | Alternatively, you can also use docker-compose v2 schema. An example can be found [in the docker folder](./docker/docker-compose.yml). |
83 | |||
84 | ```sh | ||
85 | --- | ||
86 | version: "2" | ||
87 | services: | ||
88 | ferdi-server: | ||
89 | image: getferdi/ferdi-server | ||
90 | container_name: ferdi-server | ||
91 | environment: | ||
92 | - NODE_ENV=development | ||
93 | - EXTERNAL_DOMAIN=<ferdi-serverdomain> | ||
94 | - DB_CONNECTION=<database> | ||
95 | - DB_HOST=<yourdbhost> | ||
96 | - DB_PORT=<yourdbPORT> | ||
97 | - DB_USER=<yourdbuser> | ||
98 | - DB_PASSWORD=<yourdbpass> | ||
99 | - DB_DATABASE=<yourdbdatabase> | ||
100 | - DB_SSL=true/false | ||
101 | - MAIL_CONNECTION=<mailsender> | ||
102 | - SMPT_HOST=<smtpmailserver> | ||
103 | - SMTP_PORT=<smtpport> | ||
104 | - MAIL_SSL=true/false | ||
105 | - MAIL_USERNAME=<yourmailusername> | ||
106 | - MAIL_PASSWORD=<yourmailpassword> | ||
107 | - MAIL_SENDER=<sendemailaddress> | ||
108 | - IS_CREATION_ENABLED=true/false | ||
109 | - IS_DASHBOARD_ENABLED=true/false | ||
110 | - IS_REGISTRATION_ENABLED=true/false | ||
111 | - CONNECT_WITH_FRANZ=true/false | ||
112 | volumes: | ||
113 | - <path to data>:/config | ||
114 | - <path to database>:/app/database | ||
115 | - <path to recipes>:/app/recipes | ||
116 | ports: | ||
117 | - <port>:80 | ||
118 | restart: unless-stopped | ||
119 | ``` | ||
120 | 85 | ||
121 | 3. Optionally, you can now [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). | 86 | 3. 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). |
122 | 87 | ||
123 | For more information on configuring the Docker image, visit the Docker image repository at <https://github.com/getferdi/server-docker>. | 88 | For more information on configuring the Docker image, please read [the Ferdi docker documentation](./docker/README.md). |
124 | 89 | ||
125 | ### Manual setup | 90 | ### Manual setup |
126 | 91 | ||
@@ -143,19 +108,19 @@ For more information on configuring the Docker image, visit the Docker image rep | |||
143 | 108 | ||
144 | ## Configuration | 109 | ## Configuration |
145 | 110 | ||
146 | franz-server's configuration is saved inside the `.env` file. Besides AdonisJS's settings, ferdi-server has the following custom settings: | 111 | franz-server's configuration is saved inside an `.env` file. Besides AdonisJS's settings, Ferdi-server has the following custom settings: |
147 | - `IS_CREATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the [creation of custom recipes](#creating-and-using-custom-recipes) | 112 | - `IS_CREATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the [creation of custom recipes](#creating-and-using-custom-recipes) |
148 | - `IS_REGISTRATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the creation of new user accounts | 113 | - `IS_REGISTRATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the creation of new user accounts |
149 | - `IS_DASHBOARD_ENABLED` (`true` or `false`, default: `true`): Whether to enable the user dashboard | 114 | - `IS_DASHBOARD_ENABLED` (`true` or `false`, default: `true`): Whether to enable the user dashboard |
150 | - `CONNECT_WITH_FRANZ` (`true` or `false`, default: `true`): Whether to enable connections to the Franz server. By enabling this option, ferdi-server can: | 115 | - `CONNECT_WITH_FRANZ` (`true` or `false`, default: `true`): Whether to enable connections to the Franz server. By enabling this option, Ferdi-server can: |
151 | - Show the full Franz recipe library instead of only custom recipes | 116 | - Show the full Franz recipe library instead of only custom recipes |
152 | - Import Franz accounts | 117 | - Import Franz accounts |
153 | 118 | ||
154 | ## Importing your Franz account | 119 | ## Importing your Franz account |
155 | 120 | ||
156 | ferdi-server allows you to import your full Franz account, including all its settings. | 121 | Ferdi-server allows you to import your full Franz account, including all its settings. |
157 | 122 | ||
158 | 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. | 123 | 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. |
159 | 124 | ||
160 | ## Transferring user data | 125 | ## Transferring user data |
161 | 126 | ||
@@ -163,26 +128,26 @@ Please refer to <https://github.com/getferdi/ferdi/wiki/Transferring-data-betwee | |||
163 | 128 | ||
164 | ## Creating and using custom recipes | 129 | ## Creating and using custom recipes |
165 | 130 | ||
166 | ferdi-server allows to extends the Franz recipe catalogue with custom Ferdi recipes. | 131 | Ferdi-server allows to extends the Franz recipe catalogue with custom Ferdi recipes. |
167 | 132 | ||
168 | 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). | 133 | 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). |
169 | 134 | ||
170 | To add your recipe to ferdi-server, open `http://[YOUR FERDI-SERVER]/new` in your browser. You can now define the following settings: | 135 | To add your recipe to Ferdi-server, open `http://[YOUR FERDI-SERVER]/new` in your browser. You can now define the following settings: |
171 | 136 | ||
172 | - `Author`: Author who created the recipe | 137 | - `Author`: Author who created the recipe |
173 | - `Name`: Name for your new service. Can contain spaces and unicode characters | 138 | - `Name`: Name for your new service. Can contain spaces and unicode characters |
174 | - `Service ID`: Unique ID for this recipe. Does not contain spaces or special characters (e.g. `google-drive`) | 139 | - `Service ID`: Unique ID for this recipe. Does not contain spaces or special characters (e.g. `google-drive`) |
175 | - `Link to SVG image`: Direct link to a 1024x1024 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 | 140 | - `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 |
176 | - `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. | 141 | - `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. |
177 | 142 | ||
178 | ### Listing custom recipes | 143 | ### Listing custom recipes |
179 | 144 | ||
180 | Inside Ferdi, searching for `ferdi:custom` will list all your custom recipes. | 145 | Inside Ferdi, searching for `ferdi:custom` will list all of your custom recipes. |
181 | 146 | ||
182 | ## Contributing to ferdi-server's development | 147 | ## Contributing to Ferdi-server's development |
183 | 148 | ||
184 | We welcome all contributors. Please read the [contributing guidelines](CONTRIBUTING.md) to setup your development machine and proceed. | 149 | We welcome all contributors. Please read the [contributing guidelines](CONTRIBUTING.md) to setup your development machine and proceed. |
185 | 150 | ||
186 | ## License | 151 | ## License |
187 | 152 | ||
188 | ferdi-server is licensed under the MIT License | 153 | Ferdi-server is licensed under the MIT License |