diff options
author | Vijay A <avijayr@protonmail.com> | 2021-05-19 10:33:26 +0530 |
---|---|---|
committer | Vijay Raghavan Aravamudhan <vraravam@users.noreply.github.com> | 2021-05-19 10:34:38 +0530 |
commit | e3e17652c7d90fed0f981d68b875fec9ce71d041 (patch) | |
tree | fbd16ed0dedcbcc51f234b373744f7feacc3b1ff | |
parent | Bump lodash from 4.17.19 to 4.17.21 (diff) | |
download | ferdium-server-e3e17652c7d90fed0f981d68b875fec9ce71d041.tar.gz ferdium-server-e3e17652c7d90fed0f981d68b875fec9ce71d041.tar.zst ferdium-server-e3e17652c7d90fed0f981d68b875fec9ce71d041.zip |
[Housekeeping] Added missing hygiene configs/files for developer/contributor.
-rw-r--r-- | .gitignore | 3 | ||||
-rw-r--r-- | .npmrc | 2 | ||||
-rw-r--r-- | .nvmrc | 1 | ||||
-rw-r--r-- | CONTRIBUTING.md | 151 | ||||
-rw-r--r-- | README.md | 39 | ||||
-rw-r--r-- | package.json | 7 |
6 files changed, 187 insertions, 16 deletions
@@ -19,3 +19,6 @@ recipes/ | |||
19 | resources/announcements/*.json | 19 | resources/announcements/*.json |
20 | !resources/announcements/version.json | 20 | !resources/announcements/version.json |
21 | npm-debug.log | 21 | npm-debug.log |
22 | yarn-error.log | ||
23 | server*.log | ||
24 | .idea | ||
@@ -0,0 +1,2 @@ | |||
1 | save-exact = true | ||
2 | engine-strict = true | ||
@@ -0,0 +1 @@ | |||
14.16.1 | |||
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d276763 --- /dev/null +++ b/CONTRIBUTING.md | |||
@@ -0,0 +1,151 @@ | |||
1 | # Contributing to ferdi-server | ||
2 | |||
3 | :tada: First off, thanks for taking the time and your effort to make Ferdi better! :tada: | ||
4 | |||
5 | ## Table of contents | ||
6 | |||
7 | <!-- TOC depthFrom:2 depthTo:2 withLinks:1 updateOnSave:1 orderedList:0 --> | ||
8 | |||
9 | - [Contributing to ferdi-server](#contributing-to-ferdi-server) | ||
10 | - [Table of contents](#table-of-contents) | ||
11 | - [Code of Conduct](#code-of-conduct) | ||
12 | - [What should I know before I get started?](#what-should-i-know-before-i-get-started) | ||
13 | - [How Can I Contribute?](#how-can-i-contribute) | ||
14 | - [Setting up your Development machine](#setting-up-your-development-machine) | ||
15 | - [Install System-level dependencies](#install-system-level-dependencies) | ||
16 | - [Node.js, npm, node-gyp](#nodejs-npm-node-gyp) | ||
17 | - [Git](#git) | ||
18 | - [Clone repository with submodule](#clone-repository-with-submodule) | ||
19 | - [Install dependencies](#install-dependencies) | ||
20 | - [Styleguide](#styleguide) | ||
21 | - [Git Commit Messages format](#git-commit-messages-format) | ||
22 | - [Javascript Coding style-checker](#javascript-coding-style-checker) | ||
23 | |||
24 | <!-- /TOC --> | ||
25 | |||
26 | ## Code of Conduct | ||
27 | |||
28 | This project and everyone participating in it is governed by the [Ferdi Code of Conduct](https://github.com/getferdi/ferdi/blob/develop/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [stefan@adlk.io](mailto:stefan@adlk.io). | ||
29 | |||
30 | ## What should I know before I get started? | ||
31 | |||
32 | For the moment, Ferdi's development is a bit slow but all contributions are highly appreciated. [Check this issue for discussion](https://github.com/getferdi/ferdi/issues/956). | ||
33 | |||
34 | ## How Can I Contribute? | ||
35 | |||
36 | As a basic rule, before filing issues, feature requests or anything else. Take a look at the issues and check if this has not already been reported by another user. If so, engage in the already existing discussion. | ||
37 | |||
38 | ## Setting up your Development machine | ||
39 | |||
40 | ### Install System-level dependencies | ||
41 | |||
42 | #### Node.js, npm, node-gyp | ||
43 | |||
44 | Please make sure you are running the exact node version used by the developers/contributors as specified in the [nvmrc file](./.nvmrc). | ||
45 | |||
46 | Currently, these are the combinations of system dependencies that work on an intel-based machines for MacOS/Linux/Windows (building on an ARM-based machine is still a work-in-progress due to node-sass native dependencies) | ||
47 | |||
48 | ```bash | ||
49 | node -v | ||
50 | v14.16.1 | ||
51 | npm -v | ||
52 | 6.14.12 | ||
53 | node-gyp -v | ||
54 | v8.0.0 | ||
55 | ``` | ||
56 | |||
57 | #### Git | ||
58 | |||
59 | The version [2.23.0](https://github.com/git-for-windows/git/releases/tag/v2.23.0.windows.1) for Git is working fine for development. You can then use the console from Git to do the development procedure. | ||
60 | |||
61 | <!-- #### Debian/Ubuntu | ||
62 | |||
63 | ```bash | ||
64 | apt install libx11-dev libxext-dev libxss-dev libxkbfile-dev rpm | ||
65 | ``` | ||
66 | |||
67 | #### Fedora | ||
68 | |||
69 | ```bash | ||
70 | dnf install libX11-devel libXext-devel libXScrnSaver-devel libxkbfile-devel rpm | ||
71 | ``` | ||
72 | |||
73 | #### Windows | ||
74 | |||
75 | Please make sure you run this command as an administrator: | ||
76 | |||
77 | ```bash | ||
78 | npm i -g windows-build-tools --vs2015 | ||
79 | ``` | ||
80 | --> | ||
81 | |||
82 | ### Clone repository with submodule | ||
83 | |||
84 | ```bash | ||
85 | git clone https://github.com/getferdi/server.git | ||
86 | cd server | ||
87 | git submodule update --init --recursive | ||
88 | ``` | ||
89 | |||
90 | It is important you execute the last command to get the required submodules (recipes, server). | ||
91 | |||
92 | ### Install dependencies | ||
93 | |||
94 | - Run the following command to install all dependencies, and link sibling modules with ferdi-server. | ||
95 | |||
96 | ```bash | ||
97 | npm i | ||
98 | ``` | ||
99 | |||
100 | - Copy the `.env.example` file into `.env` and change the values to match your system. | ||
101 | |||
102 | ```bash | ||
103 | cp .env.example .env | ||
104 | ``` | ||
105 | |||
106 | _Note:_ | ||
107 | |||
108 | 1. Have env DB_SSL=true only if your database is postgres and it is hosted online on platforms like GCP, AWS, etc | ||
109 | 2. You will have to provide a value for `API_KEY` that is at least 16 characters long. | ||
110 | |||
111 | - If using sqlite for local development, create the database directory (whatever is set to `DATA` in `.env`) | ||
112 | |||
113 | ```bash | ||
114 | mkdir -p data | ||
115 | ``` | ||
116 | |||
117 | - Run the database migrations with | ||
118 | |||
119 | ```bash | ||
120 | node ace migration:refresh | ||
121 | ``` | ||
122 | |||
123 | - To get the full functionality, you will need to have an SMTP server running for local development. | ||
124 | |||
125 | <!-- ### Package recipe repository | ||
126 | |||
127 | Ferdi requires its recipes to be packaged before it can use it. When running Ferdi as a development instance, you'll need to package the local recipes before you can create any services inside Ferdi. | ||
128 | |||
129 | ```bash | ||
130 | cd recipes && npm i && npm run package | ||
131 | ``` --> | ||
132 | |||
133 | ### Start development app | ||
134 | |||
135 | ```bash | ||
136 | npm start --dev | ||
137 | ``` | ||
138 | |||
139 | ### Styleguide | ||
140 | |||
141 | #### Git Commit Messages format | ||
142 | |||
143 | - Use the present tense ("Add feature" not "Added feature") | ||
144 | - Use the imperative mood ("Move cursor to..." not "Moves cursor to...") | ||
145 | - Limit the first line to 72 characters or less | ||
146 | - Reference issues and pull requests liberally after the first line | ||
147 | - When only changing documentation, include `[ci skip]` in the commit description | ||
148 | |||
149 | #### Javascript Coding style-checker | ||
150 | |||
151 | - Please use `es-lint` and the defined rules to maintain a consistent style | ||
@@ -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 schemas | 82 | Alternatively, you can also use docker-compose v2 schemas |
@@ -89,7 +90,7 @@ After setting up the docker container we recommend you to set up an NGINX revers | |||
89 | container_name: ferdi-server | 90 | container_name: ferdi-server |
90 | environment: | 91 | environment: |
91 | - NODE_ENV=development | 92 | - NODE_ENV=development |
92 | - EXTERNAL_DOMAIN=<ferdi-serverdomain> | 93 | - EXTERNAL_DOMAIN=<ferdi-serverdomain> |
93 | - DB_CONNECTION=<database> | 94 | - DB_CONNECTION=<database> |
94 | - DB_HOST=<yourdbhost> | 95 | - DB_HOST=<yourdbhost> |
95 | - DB_PORT=<yourdbPORT> | 96 | - DB_PORT=<yourdbPORT> |
@@ -116,34 +117,32 @@ After setting up the docker container we recommend you to set up an NGINX revers | |||
116 | - <port>:80 | 117 | - <port>:80 |
117 | restart: unless-stopped | 118 | restart: unless-stopped |
118 | ``` | 119 | ``` |
120 | |||
119 | 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). | 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). |
120 | 122 | ||
121 | For more information on configuring the Docker image, visit the Docker image repository at <https://github.com/getferdi/server-docker>. | 123 | For more information on configuring the Docker image, visit the Docker image repository at <https://github.com/getferdi/server-docker>. |
122 | 124 | ||
123 | ### Manual setup | 125 | ### Manual setup |
126 | |||
124 | 1. Clone this repository | 127 | 1. Clone this repository |
125 | 2. Install the [AdonisJS CLI](https://adonisjs.com/) | 128 | 2. Install the [AdonisJS CLI](https://adonisjs.com/) |
126 | 3. Copy `.env.example` to `.env` and edit the [configuration](#configuration) to your needs | 129 | 3. Copy `.env.example` to `.env` and edit the [configuration](#configuration) to your needs |
127 | 4. Have env DB_SSL=true only if your database is postgres and it is hosted online on platforms like GCP, AWS, etc | 130 | 4. Have env DB_SSL=true only if your database is postgres and it is hosted online on platforms like GCP, AWS, etc |
128 | 5. Run `npm install` to install local dependencies | 131 | 5. Run `npm install` to install local dependencies |
129 | 6. Run the database migrations with | 132 | 6. Run the database migrations with |
133 | |||
130 | ```js | 134 | ```js |
131 | adonis migration:run | 135 | node ace migration:run |
132 | ``` | 136 | ``` |
137 | |||
133 | 7. Start the server with | 138 | 7. Start the server with |
134 | ```js | 139 | |
135 | adonis serve --dev | ||
136 | ``` | ||
137 | 8. If on previous step it does not run the server then run with | ||
138 | ```js | 140 | ```js |
139 | npm start | 141 | npm start |
140 | ``` | 142 | ``` |
141 | or | ||
142 | ```js | ||
143 | node server.js | ||
144 | ``` | ||
145 | 143 | ||
146 | ## Configuration | 144 | ## Configuration |
145 | |||
147 | franz-server's configuration is saved inside the `.env` file. Besides AdonisJS's settings, ferdi-server has the following custom settings: | 146 | franz-server's configuration is saved inside the `.env` file. Besides AdonisJS's settings, ferdi-server has the following custom settings: |
148 | - `IS_CREATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the [creation of custom recipes](#creating-and-using-custom-recipes) | 147 | - `IS_CREATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the [creation of custom recipes](#creating-and-using-custom-recipes) |
149 | - `IS_REGISTRATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the creation of new user accounts | 148 | - `IS_REGISTRATION_ENABLED` (`true` or `false`, default: `true`): Whether to enable the creation of new user accounts |
@@ -153,19 +152,23 @@ franz-server's configuration is saved inside the `.env` file. Besides AdonisJS's | |||
153 | - Import Franz accounts | 152 | - Import Franz accounts |
154 | 153 | ||
155 | ## Importing your Franz account | 154 | ## Importing your Franz account |
155 | |||
156 | ferdi-server allows you to import your full Franz account, including all its settings. | 156 | ferdi-server allows you to import your full Franz account, including all its settings. |
157 | 157 | ||
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. | 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. |
159 | 159 | ||
160 | ## Transferring user data | 160 | ## Transferring user data |
161 | |||
161 | Please refer to <https://github.com/getferdi/ferdi/wiki/Transferring-data-between-servers> | 162 | Please refer to <https://github.com/getferdi/ferdi/wiki/Transferring-data-between-servers> |
162 | 163 | ||
163 | ## Creating and using custom recipes | 164 | ## Creating and using custom recipes |
165 | |||
164 | ferdi-server allows to extends the Franz recipe catalogue with custom Ferdi recipes. | 166 | ferdi-server allows to extends the Franz recipe catalogue with custom Ferdi recipes. |
165 | 167 | ||
166 | 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). | 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). |
167 | 169 | ||
168 | To add your recipe to ferdi-server, open `http://[YOUR FERDI-SERVER]/new` in your browser. You can now define the following settings: | 170 | To add your recipe to ferdi-server, open `http://[YOUR FERDI-SERVER]/new` in your browser. You can now define the following settings: |
171 | |||
169 | - `Author`: Author who created the recipe | 172 | - `Author`: Author who created the recipe |
170 | - `Name`: Name for your new service. Can contain spaces and unicode characters | 173 | - `Name`: Name for your new service. Can contain spaces and unicode characters |
171 | - `Service ID`: Unique ID for this recipe. Does not contain spaces or special characters (e.g. `google-drive`) | 174 | - `Service ID`: Unique ID for this recipe. Does not contain spaces or special characters (e.g. `google-drive`) |
@@ -173,7 +176,13 @@ To add your recipe to ferdi-server, open `http://[YOUR FERDI-SERVER]/new` in you | |||
173 | - `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. | 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. |
174 | 177 | ||
175 | ### Listing custom recipes | 178 | ### Listing custom recipes |
179 | |||
176 | Inside Ferdi, searching for `ferdi:custom` will list all your custom recipes. | 180 | Inside Ferdi, searching for `ferdi:custom` will list all your custom recipes. |
177 | 181 | ||
182 | ## Contributing to ferdi-server's development | ||
183 | |||
184 | We welcome all contributors. Please read the [contributing guidelines](CONTRIBUTING.md) to setup your development machine and proceed. | ||
185 | |||
178 | ## License | 186 | ## License |
187 | |||
179 | ferdi-server is licensed under the MIT License | 188 | ferdi-server is licensed under the MIT License |
diff --git a/package.json b/package.json index 5b25aac..85a2082 100644 --- a/package.json +++ b/package.json | |||
@@ -4,10 +4,15 @@ | |||
4 | "adonis-version": "4.1.0", | 4 | "adonis-version": "4.1.0", |
5 | "description": "Ferdi server to replace the default Franz server.", | 5 | "description": "Ferdi server to replace the default Franz server.", |
6 | "main": "index.js", | 6 | "main": "index.js", |
7 | "engines": { | ||
8 | "node": "^14.16", | ||
9 | "npm": "^6.14", | ||
10 | "node-gyp": "^8.0" | ||
11 | }, | ||
7 | "scripts": { | 12 | "scripts": { |
8 | "start": "node server.js", | 13 | "start": "node server.js", |
9 | "test": "node ace test", | 14 | "test": "node ace test", |
10 | "lint": "eslint --fix ./" | 15 | "lint": "eslint --quiet --fix ./" |
11 | }, | 16 | }, |
12 | "keywords": [ | 17 | "keywords": [ |
13 | "adonisjs", | 18 | "adonisjs", |