Commit d033fa40 authored by Alexandros Georgantas's avatar Alexandros Georgantas

Update README.md

parent d468463f
......@@ -16,13 +16,13 @@ git clone https://gitlab.coko.foundation/editoria/booksprints.git
cd booksprints
```
Make sure you use you use `node >= 8.3`.
Make sure you use an LTS version of node `node = 12.16.1`.
### nvm
To determine which version of Node you are running type `node -v`.
If the version is not 8.3 or greater you will need to use nvm to prescribe a specific node version. Installation of nvm is covered here https://github.com/creationix/nvm#installation
If the version is not 12.16.1 you will need to use nvm to prescribe a specific node version. Installation of nvm is covered here https://github.com/creationix/nvm#installation
Once nvm is installed use the command `nvm install 8.3`
Once nvm is installed use the command `nvm install 12`
For further information on how to use nvm see https://www.sitepoint.com/quick-tip-multiple-versions-node-nvm/
......@@ -31,7 +31,7 @@ For further information on how to use nvm see https://www.sitepoint.com/quick-ti
npm install -g yarn
```
You should also have `yarn 1.3.2` or higher installed (out-of-date versions may cause installation errors).
You should also have `yarn 1.19.1` or higher installed (out-of-date versions may cause installation errors).
### Install Docker and docker-compose
Instalation instructions can be found:
......@@ -41,43 +41,10 @@ Instalation instructions can be found:
Prefer latest stable version of docker (18.x.x) and docker-compose (1.2x.x)
### Install Dependencies
Install all dependencies and navigate to the editoria app folder.
```sh
yarn
cd packages/editoria-app
```
Create a `config/local-development.json` file.
Edit that to enter your database secret as well as placeholders for INK credentials [INK](https://gitlab.coko.foundation/INK/ink-api).
In this file, add the following:
```json
{
"pubsweet-server": {
"secret": "<your-secret-here>"
},
"pubsweet-component-ink-backend": {
"inkEndpoint": "< your-ink-api-endpoint >",
"email": "< your-ink-email >",
"password": "< your-ink-password >",
"recipes": {
"editoria-typescript": "< editoria-typescript-recipe-id >"
}
}
}
```
INK credentials are optional, you don't need them to run Editoria, you will just not be able to upload Word (docx) files.
If you do wish to use INK we recommend using a demo instance of INK hosted by Coko in your initial Editoria setup. Please contact the team on https://mattermost.coko.foundation/coko/channels/editoria in order to get the required credentials and information.
Go to the root folder of your cloned Editoria and run `yarn`
If you want to run your own instance of [INK](https://gitlab.coko.foundation/INK/ink-api), be sure that:
* the `<your-ink-api-endpoint>` in `local-development.json` ends with a trailing slash
* if INK is running as a service on a port, ensure it is on port `3000`
* If INK and Editoria are on the same server, Editoria should be set to run on another port than `3000`, AND the `postgres` docker component for INK should run on a different port (`4321` instead of `5432`for instance).
Again, if you need to test editoria, asking for the credentials will be the fastest way to be set up.
Create environment files for each profile of the application under `editoria-app/config`.
eg. `editoria-app/config/development.env`
Create environment files for each profile of the application under `editoria-vanilla/config`.
eg. `editoria-vanilla/config/development.env`
Within your environment files, export the variables you want:
```sh
......@@ -87,11 +54,9 @@ export POSTGRES_PASSWORD='' (*) (***) (by from both docker-compose.yml and pubsw
export POSTGRES_HOST='' (-)
export POSTGRES_DB='' (*) (***) (used by both docker-compose.yml and pubsweet server)
export POSTGRES_PORT='' (*) (***) (used by both docker-compose.yml and pubsweet server)
export LANGUAGE_PORT='8090'
export LANGUAGE_ENDPOINT='http://localhost'
export SERVER_PORT='' (**)
export INK_ENDPOINT='' (*) (**)
export INK_USERNAME='' (*) (**)
export INK_PASSWORD='' (*) (**)
export INK_EDITORIA_TYPESCRIPT='' (*) (**)
export MAILER_USER='' (*) (**)
export MAILER_PASSWORD='' (*) (**)
export MAILER_SENDER='' (*) (**)
......@@ -100,6 +65,7 @@ export PASSWORD_RESET_URL='' (*) (**)
export PASSWORD_RESET_SENDER='' (*) (**)
export NODE_ENV='' (**)
```
(*)Required for the application to be functional
(-) Optional
......@@ -115,54 +81,62 @@ source <your-env-file>
Get the database docker container up and running:
```sh
yarn start:services
yarn start:postgres
```
Create a database and enter credentials for an admin user account (a postgres db should already be up and running):
```sh
yarn resetdb
```
Open a new terminal session and source again your environment file. Create a new database for the app by running `yarn setupdb` and follow the CLI to create also the admin user (this will happen once uppon your first configuration of the app)
Follow the prompts to enter user credentials and complete the database setup.
When your db is ready you can start the server:
`yarn server`
_**Note**: If you want to use a non-default database, see [Pubsweet development setup](https://gitlab.coko.foundation/pubsweet/pubsweet/wikis/Development:%20setup#setup-2)._
When the server boots succesfully open a new terminal session, source again your environment file and run `yarn start:services` which will initialise and start all the additional required Editoria's services.
At this point you are good to go and use the app
You're good to go. Open a separate terminal in the same folder and run the app with:
If for some reason want to reset your app's db you could run:
```sh
yarn server
yarn resetdb
```
Clean your docker cache and containers before the first time you run the application (under editoria-app) or if changes occur in either env variables, docker-compose.yml, local-development, local-production, etc.:
If you want to clean your docker cache and containers e.g. changes occur in either env variables, docker-compose.yml, development.env, production.env, etc.:
```sh
docker-compose down
docker-compose rm -fv
rm -rf data
rm -rf database
```
The above action will require you to run `yarn setupdb` again and also ALL YOUR DATA WILL BE LOST
IT IS REALLY IMPORTANT TO MAKE SURE THAT YOUR ENV FILE IS SOURCED BEFORE RUNNING ANY OF THE FOLLOWING:
`yarn start:postgres`
`yarn start:services`
`yarn setupdb`
`yarn server`
## Developer info
see also the [Pubsweet wiki](https://gitlab.coko.foundation/pubsweet/pubsweet/wikis/home) for developer notes.
## FAQ
### I'm getting user errors running `yarn start:services` or `yarn server`
### I'm getting user errors running `yarn start:postgres` or `yarn server`
It's crucial to use the same user when installing Editoria and running the Editoria database services. These commands are:
* Running `yarn` from Editoria's root directory. This installs Editoria and its dependencies
* Running `yarn start:server` for the first time sets up a database to use with Editoria. This configures a database that expects that the same user that is running this command has also run `yarn` from Editoria's root directory.
* Running `yarn start:postgres` for the first time sets up a database to use with Editoria. This configures a database that expects that the same user that is running this command has also run `yarn` from Editoria's root directory.
If you see user errors running `yarn start:services` or `yarn server`, your best bet is to clear the existing data and start the install anew, as the same user.
If you see user errors running `yarn start:postgres` or `yarn server`, your best bet is to clear the existing database as well as your node_modules and start installing the app from the beginnig.
First, delete all the Docker data:
```
docker-compose down
docker-compose rm -fv
rm -rf data
rm -rf database
rm -rf node_modules
```
Then, follow the steps for a clean install.
### When running `yarn start:services`, I get a `Bind for 0.0.0.0:5432 failed: port is already allocated` error
### When running `yarn start:postgres`, I get a `Bind for 0.0.0.0:5432 failed: port is already allocated` error
Something (probably postgres) is already running on the port that the Docker database services try to use (5432). Solution for Ubuntu:
1. `lsof -i tcp:5432`: lists the processes running on port 5432
......@@ -188,7 +162,7 @@ docker-compose rm -fv
`docker-compose rm -fv` will remove the container and it's anonymous volumes.
`rm -rf data` will delete the content from your database
`rm -rf database` will delete the content from your database
* Now you could run `source <your-env-file>` and start again the services and server
......@@ -201,17 +175,6 @@ docker-compose rm -fv
These values are needed in order the docker container which hosts the PostrgesDB of the application to be initialised correctly.
### I am facing issues when trying to boot-up the application which are related to INK API
Ink is the process manager developped by Coko. Editoria uses Ink mainly to convert Microsoft Word .docx into proper HTML to be used in Editoria (among other things).
Since it has been one of the requirements from the begginning, running Editoria means that you need to have access to an instance of INK before runnning it, thus the appropriate configuration should be in place in order for Editoria to start properly.
INK's configuration could either be placed in:
* `local.development.json`
* `development.json`
* `<profile>.env`
Please contact the team on https://mattermost.coko.foundation/coko/channels/editoria in order to get the required credentials
### How can I access the epub file?
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment