aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md93
1 files changed, 29 insertions, 64 deletions
diff --git a/README.md b/README.md
index b379559..6a45b08 100644
--- a/README.md
+++ b/README.md
@@ -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
6Official Server software for the [Ferdi Messaging Browser](https://getferdi.com) 6Official 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?
23A custom server allows you to manage the data of all registered users yourself and add your own recipes to the repository. 23A custom server allows you to manage the data of all registered users yourself and add your own recipes to the repository.
24 24
25If you are not interested in doing this you can use our official instance of Ferdi server at <https://api.getferdi.com>. 25If 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
39The easiest way to set up Ferdi server on your server is with Docker. 39The easiest way to set up Ferdi-server on your server is with Docker.
40 40
41The 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). 41The 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).
42After 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. 42After 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
441. Pull the Docker image 461. Pull the Docker image
45 47
46 ```sh 48 ```sh
47 docker pull getferdi/ferdi-server 49 docker pull getferdi/ferdi-server
48 ``` 50 ```
492. Create a new Docker container with your desired configuration 512. 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
1213. 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). 863. 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
123For more information on configuring the Docker image, visit the Docker image repository at <https://github.com/getferdi/server-docker>. 88For 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
146franz-server's configuration is saved inside the `.env` file. Besides AdonisJS's settings, ferdi-server has the following custom settings: 111franz-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
156ferdi-server allows you to import your full Franz account, including all its settings. 121Ferdi-server allows you to import your full Franz account, including all its settings.
157 122
158To 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. 123To 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
166ferdi-server allows to extends the Franz recipe catalogue with custom Ferdi recipes. 131Ferdi-server allows to extends the Franz recipe catalogue with custom Ferdi recipes.
167 132
168For documentation on how to create a recipe, please visit [the official guide by Franz](https://github.com/meetfranz/plugins/blob/master/docs/integration.md). 133For 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
170To add your recipe to ferdi-server, open `http://[YOUR FERDI-SERVER]/new` in your browser. You can now define the following settings: 135To 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
180Inside Ferdi, searching for `ferdi:custom` will list all your custom recipes. 145Inside 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
184We welcome all contributors. Please read the [contributing guidelines](CONTRIBUTING.md) to setup your development machine and proceed. 149We 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
188ferdi-server is licensed under the MIT License 153Ferdi-server is licensed under the MIT License