Skip to content
Snippets Groups Projects

Update README.md to reflect folder structure of ucp repo

Open Update README.md to reflect folder structure of ucp repo
ckcosner/ucp:patch-1 into master
Open Chris Cosner requested to merge ckcosner/ucp:patch-1 into master
Compare
and
1 file
+ 39
− 34
Compare changes
  • Side-by-side
  • Inline
README.md
+ 39
− 34
# Editoria
This is the Editoria monorepo.
This is the Editoria UCP monorepo.
It consists of the main Editoria application, as well as the different [Pubsweet](https://gitlab.coko.foundation/pubsweet) components and helper libraries that the app is made of.
@@ -43,17 +43,17 @@ The current features on our list are the following:
Get your copy of the repository.
```sh
git clone https://gitlab.coko.foundation/editoria/editoria.git
cd editoria
git clone https://gitlab.coko.foundation/editoria/ucp.git
cd ucp
```
Make sure you use you use `node >= 8.3`.
### Node.js
Make sure you have `node >= 8.6` installed.
### 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
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 8.6` to set the active version of node (`nvm install 11.9` for version 11.9).
For further information on how to use nvm see https://www.sitepoint.com/quick-tip-multiple-versions-node-nvm/
@@ -62,23 +62,23 @@ 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.3.2` or higher installed (out-of-date versions may cause installation errors). If the version that comes with your OS is lower, install manually, as described here: https://yarnpkg.com/en/docs/install.
### Install Docker and docker-compose
Instalation instructions can be found:
### Install Docker and Docker-Compose
Installation instructions:
* https://docs.docker.com/install/
* https://docs.docker.com/compose/install/
Prefer latest stable version of docker (18.x.x) and docker-compose (1.2x.x)
Use the latest stable version, currently docker (18.x.x) and docker-compose (1.2x.x)
### Install Dependencies
Install all dependencies and navigate to the editoria app folder.
Now install all dependencies and navigate to the `config/` folder.
```sh
yarn
cd packages/editoria-app
cd config
```
Create a `config/local-development.json` file.
Create a `local-development.json` file in the `config/ folder`.
Edit that to enter your database secret, as well as to connect to [INK](https://gitlab.coko.foundation/INK/ink-api).
In this file, add the following:
```json
@@ -106,8 +106,8 @@ If you do want to run your own instance of [INK](https://gitlab.coko.foundation/
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 `ucp/config/`.
eg. `ucp/config/development.env`
Within your environment files, export the variables you want:
```sh
@@ -130,17 +130,17 @@ export PASSWORD_RESET_URL='' (*) (**)
export PASSWORD_RESET_SENDER='' (*) (**)
export NODE_ENV='' (**)
```
(*)Required for the application to be functional
(\*)Required for the application to be functional
(-) Optional
(**) This key-value pairs could be either declared as env variables or either in the corresponding config file e.g. `local-development.json`, `development.json`, etc
(\*\*) This key-value pairs could be either declared as env variables or either in the corresponding config file e.g. `local-development.json`, `development.json`, etc
(***) These fields should by any means exist in the env source file for the correct initialization of the docker container which holds the database of the application
(\*\*\*) These fields should by any means exist in the env source file for the correct initialization of the docker container which holds the database of the application
Import the environment variables into the current shell session:
```sh
source <your-env-file>
source development.env
```
Get the database docker container up and running:
@@ -148,22 +148,28 @@ Get the database docker container up and running:
yarn start:services
```
Create a database and enter credentials for an admin user account (a postgres db should already be up and running):
Leave the current terminal open, open a new terminal, and navigate to the same folder, i.e., `ucp/config/`.
Import the environment variables, create a database and enter credentials for an admin user account:
```sh
source development.env
yarn resetdb
```
Follow the prompts to enter user credentials and complete the database setup.
Follow the prompts to enter user credentials and complete the database setup. Utilize the credentials you gave in `local-development.json`.
_**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)._
Make sure your server's firewall is open for port 7070/tcp or whatever you gave as `SERVER_PORT` in `development.env`.
You're good to go. Open a separate terminal in the same folder and run the app with:
While still in `ucp/config/` now run the app with:
```sh
yarn server
```
Point your browser to your server with :7070 at the end of the URL (or your chosen port). You should see Editoria's Books page.
### Clean Docker cache
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.:
Clean your docker cache and containers whenever you restart the application (under ucp/config/) or if changes occur in .env variables, docker-compose.yml, local-development.json, local-production.json, etc.:
```sh
docker-compose down
docker-compose rm -fv
@@ -171,8 +177,7 @@ rm -rf data
```
## Developer info
see also the [Pubsweet wiki](https://gitlab.coko.foundation/pubsweet/pubsweet/wikis/home) for developer notes.
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`
@@ -222,19 +227,19 @@ docker-compose rm -fv
* Now you could run `source <your-env-file>` and start again the services and server
### Which are the absolute required key-value pairs for an env file?
### Which key-value pairs are absolutely required in an env file?
* POSTGRES_USER
* POSTGRES_PASSWORD
* POSTGRES_DB
* POSTGRES_PORT
These values are needed in order the docker container which hosts the PostrgesDB of the application to be initialised correctly.
These values are needed so that the docker container that hosts the PostrgesDB of the application be initialized 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 is the process manager developed 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 beginning, running Editoria means that you need to have access to an instance of INK before running 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`
@@ -245,7 +250,7 @@ Please contact the team on https://mattermost.coko.foundation/coko/channels/edit
### How can I access the epub file?
EPUB files are created and stored in the `uploads` directory (`editoria/packages/editoria-app/uploads`) every time the book is exported with the "EXPORT BOOK" button on the top right of the book. Be sure to sort by created date to ensure you're getting the most recent file.
EPUB files are created and stored in the `uploads` directory (`ucp/uploads`) every time the book is exported with the "EXPORT BOOK" button on the top right of the book. Be sure to sort by created date to ensure you're getting the most recent file.
### Does the HTML out of Editoria support accessibility including the use of Alt tags?
We are working with Benetech to fully understand and plan for accessibility. This development is on our development roadmap.
@@ -258,7 +263,7 @@ This is on our development roadmap.
### Can Editoria integrate with other tools and services?
Yes. Editoria’s architecture is all API-orientated and can be easily extended for third party service integration. For more information, visit https://editoria.pub
### Can notes be moved to backmatter (rather than footnotes)?
At this moment no, but it is on the Editoria roadmap. Options will include same page, back of book, or margin notes.
@@ -283,4 +288,4 @@ Using the "Upload Word Files" button, you can upload multiple .docx files with o
Additionally:
* By default, files in the Body are regular, numbered chapters. Frontmatter and backmatter components are always unnumbered.
* a "00" anywhere in filename will make it an unnumbered chapter (only in Body)
* "pt0" anywhere in filename will upload the .docx as a Part (only in Body)
\ No newline at end of file
* "pt0" anywhere in filename will upload the .docx as a Part (only in Body)