-
Notifications
You must be signed in to change notification settings - Fork 186
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
5a8f74a
commit 43a558c
Showing
1 changed file
with
51 additions
and
49 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,78 +1,80 @@ | ||
| # Speckle Server | ||
| # Server | ||
|
|
||
| The next iteration of the Speckle Server. | ||
| [](https://twitter.com/SpeckleSystems) [](https://discourse.speckle.works) | ||
| [](https://speckle-works.slack.com/join/shared_invite/enQtNjY5Mzk2NTYxNTA4LTU4MWI5ZjdhMjFmMTIxZDIzOTAzMzRmMTZhY2QxMmM1ZjVmNzJmZGMzMDVlZmJjYWQxYWU0MWJkYmY3N2JjNGI) [](https://speckle.systems) | ||
|
|
||
| [](https://github.com/Speckle-Next/SpeckleServer/) [](https://codecov.io/gh/Speckle-Next/SpeckleServer) | ||
| #### Status | ||
|
|
||
| [](https://github.com/Speckle-Next/SpeckleServer/) [](https://codecov.io/gh/Speckle-Next/SpeckleServer) | ||
|
|
||
| ## Contributing | ||
| ## Disclaimer | ||
| This is an early alpha release, not meant for use in production! We're working to stabilise the 2.0 API, and until then there will be breaking changes. You have been warned! | ||
|
|
||
| ### Local debugging & testing | ||
| ## Introduction | ||
|
|
||
| To debug, simply run `npm run dev:server`. To test, run `npm run test:server`. To run tests in interactive mode, run `npm run test:server:watch`. | ||
| This is the Speckle Server 2.0. It consists of two distinct parts: | ||
|
|
||
| #### Requirements | ||
| - The server application itself, which is a nodejs app exposing a GraphQL API, | ||
| - The frontend application, which is a static vuejs app. | ||
|
|
||
| 1. Duplicate and rename `.env-example` to `.env`. | ||
| For example usage, do check out the tests! We'll be also adding preliminary documentation [on our forum](https://discourse.speckle.works/c/speckle-insider/10). | ||
|
|
||
| 2. You will need to have a postgres instance running on the default settings, with two databases present, named `speckle2_dev` and `speckle2_test`. | ||
| ## Developing and Debugging | ||
|
|
||
| > For getting postgres running on osx, check out [postgres.app](https://postgresapp.com/), and the classic [pgadmin](https://www.pgadmin.org/download/pgadmin-4-macos/). | ||
| To get started, first clone this repo. | ||
|
|
||
| 3. You will also need Redis installed. | ||
| ### Setup | ||
|
|
||
| > For which you can use the [redis.app](https://jpadilla.github.io/redisapp/). | ||
| To run the Server in debug mode: | ||
|
|
||
| ### How to commit to this repo | ||
| When pushing commits to this repo, please follow the following guidelines: | ||
| - Duplicate and rename `.env-example` to `.env` & fill it in! | ||
| - Make sure a postgres instance is running locally, with two databases present, named `speckle2_dev` and `speckle2_test`. | ||
| - Make sure a redis instance is running locally. | ||
| - Run `npm install` | ||
| - Run `npm run dev:server` 🚀 | ||
|
|
||
| - Install [commitizen](https://www.npmjs.com/package/commitizen#commitizen-for-contributors) globally (`npm i -g commitizen`). | ||
| - When ready to commit, type in the commandline `git cz` & follow the prompts. | ||
| - Install eslint globally `npm i -g eslint` | ||
| - if using VS code install the `eslint` extension | ||
| - we also recommend setting it to run on save by adding the following VS Code setting | ||
| ``` | ||
| "editor.codeActionsOnSave": { | ||
| "source.fixAll.eslint": true | ||
| } | ||
| ``` | ||
| To run the Frontend locally in debug mode: | ||
|
|
||
| ## Modules | ||
| - Switch your working directory to `/frontend` | ||
| - Run `npm install` | ||
| - Run `npm run dev:frontend` from the Server root folder, or `npm run serve` from `/frontend`. | ||
|
|
||
| The server dynamically loads individual 'modules' from each top level folder in `./modules`. It first loads the core modules, and thereafter others. | ||
| To build the frontend, simply run `npm run build:frontend`. | ||
|
|
||
| Modules can create new and alter old database tables, if the knex migration files are present in a `migrations` subfolder (e.g., `./modules/your-module/migrations/my-new-table.js`). Make sure to add a date in front of your migration file. | ||
| > Tips: | ||
| > Postgres: For getting postgres, check out [postgres.app](https://postgresapp.com/), and the classic [pgadmin](https://www.pgadmin.org/download/pgadmin-4-macos/). | ||
| > Redis: you can use the [redis.app](https://jpadilla.github.io/redisapp/). | ||
| ### Structure | ||
| ### Testing | ||
|
|
||
| A module should contain in its root folder an index.js file that exposes an init function: | ||
| The Server is quite throughly covered by tests. Once you have followed the setup steps above, you can run all the tests by hitting `npm run test:server`. | ||
|
|
||
| ```js | ||
| exports.init = ( app ) => { | ||
| // Your module's initialisation code | ||
| } | ||
| ``` | ||
| For testing specific functionality, check out the npm scripts in `package.json` - they are breaking down the tests piecemeal. When working on the Server, we've always found useful to run in watch mode only the tests pertaining to what we were working on (e.g., `npm run test:server:objects`). | ||
|
|
||
| Any database migration files should be stored and named accordingly in a `migrations` folder. Moreover, modules should include test files. These should be located in `tests`. Here's a sample structure: | ||
| ## Contributing | ||
|
|
||
| ``` | ||
| Please make sure you read the [contribution guidelines](CONTRIBUTING.md) for an overview of the best practices we try to follow. | ||
|
|
||
| |-- index.js // entry file | ||
| |-- migrations | ||
| `-- myTable.js | ||
| `-- tests | ||
| `-- example.spec.js | ||
| When pushing commits to this repo, please follow the following guidelines: | ||
|
|
||
| - Install [commitizen](https://www.npmjs.com/package/commitizen#commitizen-for-contributors) globally (`npm i -g commitizen`). | ||
| - When ready to commit, type in the commandline `git cz` & follow the prompts. | ||
| - Install eslint globally `npm i -g eslint` | ||
| - VS code: install the `eslint` extension | ||
| - VS code: we also recommend setting it to run on save by adding the following VS Code setting | ||
| ``` | ||
| "editor.codeActionsOnSave": { | ||
| "source.fixAll.eslint": true | ||
| } | ||
| ``` | ||
|
|
||
| // TODO | ||
|
|
||
| ## API | ||
|
|
||
| ### GraphQl | ||
| ## Community | ||
|
|
||
| // TODO | ||
| ### REST | ||
| The Speckle Community hangs out in two main places, usually: | ||
| - on [the forum](https://discourse.speckle.works) | ||
| - on [the chat](https://speckle-works.slack.com/join/shared_invite/enQtNjY5Mzk2NTYxNTA4LTU4MWI5ZjdhMjFmMTIxZDIzOTAzMzRmMTZhY2QxMmM1ZjVmNzJmZGMzMDVlZmJjYWQxYWU0MWJkYmY3N2JjNGI) | ||
|
|
||
| Depecrated. | ||
| Do join and introduce yourself! | ||
|
|
||
| ## License | ||
| Unless otherwise described, the code in this repository is licensed under the Apache-2.0 License. Please note that some modules, extensions or code herein might be otherwise licensed. This is indicated either in the root of the containing folder under a different license file, or in the respective file's header. If you have any questions, don't hesitate to get in touch with us via [email](mailto:[email protected]). |