diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 36 |
1 files changed, 22 insertions, 14 deletions
@@ -1,5 +1,5 @@ | |||
1 | <p align="center"> | 1 | <p align="center"> |
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 |
@@ -16,6 +16,7 @@ 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 | - [License](#license) | 20 | - [License](#license) |
20 | 21 | ||
21 | ## Why use a custom Ferdi server? | 22 | ## Why use a custom Ferdi server? |
@@ -37,7 +38,7 @@ If you are not interested in doing this you can use our official instance of Fer | |||
37 | ### with Docker | 38 | ### with Docker |
38 | 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. |
39 | 40 | ||
40 | 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 modifying your ENV variables to use an external database (e.g. MySQL, MariaDB, Postgres, etc). |
41 | 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 to set up an NGINX reverse proxy to access ferdi-server outside of your home network and protect it with an SSL certificate. |
42 | 43 | ||
43 | 1. Pull the Docker image | 44 | 1. Pull the Docker image |
@@ -47,11 +48,11 @@ After setting up the docker container we recommend you to set up an NGINX revers | |||
47 | ``` | 48 | ``` |
48 | 2. Create a new Docker container with your desired configuration | 49 | 2. Create a new Docker container with your desired configuration |
49 | 50 | ||
50 | ```sh | 51 | ```sh |
51 | docker create \ | 52 | docker create \ |
52 | --name=ferdi-server \ | 53 | --name=ferdi-server \ |
53 | -e NODE_ENV=development \ | 54 | -e NODE_ENV=development \ |
54 | -e EXTERNAL_DOMAIN=<ferdi-serverdomain> \ | 55 | -e EXTERNAL_DOMAIN=<ferdi-serverdomain> \ |
55 | -e DB_CONNECTION=<database> \ | 56 | -e DB_CONNECTION=<database> \ |
56 | -e DB_HOST=<yourdbhost> \ | 57 | -e DB_HOST=<yourdbhost> \ |
57 | -e DB_PORT=<yourdbport> \ | 58 | -e DB_PORT=<yourdbport> \ |
@@ -75,7 +76,7 @@ After setting up the docker container we recommend you to set up an NGINX revers | |||
75 | -v <path to database>:/app/database \ | 76 | -v <path to database>:/app/database \ |
76 | -v <path to recipes>:/app/recipes \ | 77 | -v <path to recipes>:/app/recipes \ |
77 | --restart unless-stopped \ | 78 | --restart unless-stopped \ |
78 | getferdi/ferdi-server | 79 | getferdi/ferdi-server |
79 | ``` | 80 | ``` |
80 | 81 | ||
81 | Alternatively, you can also use docker-compose v2 schema. An example can be found [in the docker folder](./docker/docker-compose.yml). | 82 | Alternatively, you can also use docker-compose v2 schema. An example can be found [in the docker folder](./docker/docker-compose.yml). |
@@ -85,29 +86,26 @@ After setting up the docker container we recommend you to set up an NGINX revers | |||
85 | For more information on configuring the Docker image, please read [the ferdi docker documentation](./docker/README.md). | 86 | For more information on configuring the Docker image, please read [the ferdi docker documentation](./docker/README.md). |
86 | 87 | ||
87 | ### Manual setup | 88 | ### Manual setup |
89 | |||
88 | 1. Clone this repository | 90 | 1. Clone this repository |
89 | 2. Install the [AdonisJS CLI](https://adonisjs.com/) | 91 | 2. Install the [AdonisJS CLI](https://adonisjs.com/) |
90 | 3. Copy `.env.example` to `.env` and edit the [configuration](#configuration) to your needs | 92 | 3. Copy `.env.example` to `.env` and edit the [configuration](#configuration) to your needs |
91 | 4. Have env DB_SSL=true only if your database is postgres and it is hosted online on platforms like GCP, AWS, etc | 93 | 4. Have env DB_SSL=true only if your database is postgres and it is hosted online on platforms like GCP, AWS, etc |
92 | 5. Run `npm install` to install local dependencies | 94 | 5. Run `npm install` to install local dependencies |
93 | 6. Run the database migrations with | 95 | 6. Run the database migrations with |
96 | |||
94 | ```js | 97 | ```js |
95 | adonis migration:run | 98 | node ace migration:run |
96 | ``` | 99 | ``` |
100 | |||
97 | 7. Start the server with | 101 | 7. Start the server with |
98 | ```js | 102 | |
99 | adonis serve --dev | ||
100 | ``` | ||
101 | 8. If on previous step it does not run the server then run with | ||
102 | ```js | 103 | ```js |
103 | npm start | 104 | npm start |
104 | ``` | 105 | ``` |
105 | or | ||
106 | ```js | ||
107 | node server.js | ||
108 | ``` | ||
109 | 106 | ||
110 | ## Configuration | 107 | ## Configuration |
108 | |||
111 | franz-server's configuration is saved inside the `.env` file. Besides AdonisJS's settings, ferdi-server has the following custom settings: | 109 | franz-server's configuration is saved inside the `.env` file. Besides AdonisJS's settings, ferdi-server has the following custom settings: |
112 | - `IS_CREATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the [creation of custom recipes](#creating-and-using-custom-recipes) | 110 | - `IS_CREATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the [creation of custom recipes](#creating-and-using-custom-recipes) |
113 | - `IS_REGISTRATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the creation of new user accounts | 111 | - `IS_REGISTRATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the creation of new user accounts |
@@ -117,19 +115,23 @@ franz-server's configuration is saved inside the `.env` file. Besides AdonisJS's | |||
117 | - Import Franz accounts | 115 | - Import Franz accounts |
118 | 116 | ||
119 | ## Importing your Franz account | 117 | ## Importing your Franz account |
118 | |||
120 | ferdi-server allows you to import your full Franz account, including all its settings. | 119 | ferdi-server allows you to import your full Franz account, including all its settings. |
121 | 120 | ||
122 | 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. | 121 | 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 | 122 | ||
124 | ## Transferring user data | 123 | ## Transferring user data |
124 | |||
125 | Please refer to <https://github.com/getferdi/ferdi/wiki/Transferring-data-between-servers> | 125 | Please refer to <https://github.com/getferdi/ferdi/wiki/Transferring-data-between-servers> |
126 | 126 | ||
127 | ## Creating and using custom recipes | 127 | ## Creating and using custom recipes |
128 | |||
128 | ferdi-server allows to extends the Franz recipe catalogue with custom Ferdi recipes. | 129 | ferdi-server allows to extends the Franz recipe catalogue with custom Ferdi recipes. |
129 | 130 | ||
130 | 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). | 131 | 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). |
131 | 132 | ||
132 | To add your recipe to ferdi-server, open `http://[YOUR FERDI-SERVER]/new` in your browser. You can now define the following settings: | 133 | To add your recipe to ferdi-server, open `http://[YOUR FERDI-SERVER]/new` in your browser. You can now define the following settings: |
134 | |||
133 | - `Author`: Author who created the recipe | 135 | - `Author`: Author who created the recipe |
134 | - `Name`: Name for your new service. Can contain spaces and unicode characters | 136 | - `Name`: Name for your new service. Can contain spaces and unicode characters |
135 | - `Service ID`: Unique ID for this recipe. Does not contain spaces or special characters (e.g. `google-drive`) | 137 | - `Service ID`: Unique ID for this recipe. Does not contain spaces or special characters (e.g. `google-drive`) |
@@ -137,7 +139,13 @@ To add your recipe to ferdi-server, open `http://[YOUR FERDI-SERVER]/new` in you | |||
137 | - `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. | 139 | - `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. |
138 | 140 | ||
139 | ### Listing custom recipes | 141 | ### Listing custom recipes |
142 | |||
140 | Inside Ferdi, searching for `ferdi:custom` will list all your custom recipes. | 143 | Inside Ferdi, searching for `ferdi:custom` will list all your custom recipes. |
141 | 144 | ||
145 | ## Contributing to ferdi-server's development | ||
146 | |||
147 | We welcome all contributors. Please read the [contributing guidelines](CONTRIBUTING.md) to setup your development machine and proceed. | ||
148 | |||
142 | ## License | 149 | ## License |
150 | |||
143 | ferdi-server is licensed under the MIT License | 151 | ferdi-server is licensed under the MIT License |