diff --git a/docs/content/advanced_theming.md b/docs/content/advanced_theming.md
index 40c2e5ad3afc9bbc5eacca3ce5e84e6d84bde94b..641a0b2b1bd42c9408672ea56d15a301b5fda618 100644
--- a/docs/content/advanced_theming.md
+++ b/docs/content/advanced_theming.md
@@ -20,15 +20,15 @@ The background color uses a theme variable, but the hover color does not as ther
```js static
const myTheme = {
- colorBackground: 'white';
+ colorBackground: 'white';
cssOverrides: {
- MyComp: css\`
- &:hover {
- background-color: 'magenta';
- }
- \`
- }
+ MyComp: css`
+ &:hover {
+ background-color: 'magenta';
+ }
+ `
+ }
}
```
@@ -75,14 +75,14 @@ There are two lines here to enable writing an override in the theme, either (a)
```js static
const MyTheme = {
- colorBackground: 'white',
+ colorBackground: 'white',
colorPrimary: 'blue',
cssOverrides: {
- MyComp: css\`
- background: 'green'
- \`
- }
+ MyComp: css`
+ background: 'green';
+ `,
+ },
}
```
@@ -90,16 +90,16 @@ In the case of (b), when part of a larger object, the theme is defined:
```js static
const MyTheme = {
- colorBackground: 'white',
+ colorBackground: 'white',
colorPrimary: 'blue',
cssOverrides: {
- MyComp: {
- Root: css\`
- background: 'green'
- \`
- }
- }
+ MyComp: {
+ Root: css`
+ background: 'green';
+ `,
+ },
+ },
}
```
@@ -156,7 +156,7 @@ The `headingScale` function provides an easy way to conform to a heading scale d
```js static
const MyTheme = {
- fontSizeHeading4: \`${headingScale(12, 1.2, 4)}px\` // evaluates to 17.28
+ fontSizeHeading4: `${headingScale(12, 1.2, 4)}px`, // evaluates to 17.28
}
```
diff --git a/docs/content/faq.md b/docs/content/faq.md
index a82528a0a1e7ad99809baefdadc68cd269cf1aa8..46f4b31ad8931e52054c9dd0e79178bbb7b63680 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -1,5 +1,3 @@
-# FAQ - Frequently Asked Questions
-
This page documents snags, issues and problems experienced by developers of PubSweet apps. The aim is to then either fix or properly document the behaviour in order to streamline the experience for future contributors.
Feel free to add your own questions – and answers if you have them.
@@ -14,7 +12,7 @@ Feel free to add your own questions – and answers if you have them.
Check whether docker engine service is running or not. It's good to check this in case `docker-compose` can’t access it.
-```
+```bash
$ sudo service docker status
â— docker.service - Docker Application Container Engine
Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
@@ -30,23 +28,23 @@ $ sudo service docker status
Check Docker's unix socket file whether it has correct owner or not.
-```
+```bash
$ sudo ls -la /var/run/docker.sock
srw-rw---- 1 root docker 0 Dec 21 19:16 /var/run/docker.sock
```
## Is your user in docker's user group ?
-```
+```bash
$ docker-compose up -d postgres
ERROR: Couldn't connect to ËœDocker daemon at http+docker://localhost - is it running?
```
-You need to use sudo if your user is not in docker's user group. Even if you use sudo,
-you may encounter other permission issues between host and container filesystems when you mounted volume to containers.
+You need to use sudo if your user is not in docker's user group. Even if you use sudo,
+you may encounter other permission issues between host and container filesystems when you mounted volume to containers.
You can add your user to docker user group with the following command.
-```
+```bash
$ sudo usermod -aG docker ${USER}
$ su - $USER
```
@@ -57,7 +55,7 @@ You should then logout and login into the host again.
Sometimes we see problems like the following when trying to `setupdb` or start the application:
-```
+```bash
$ pubsweet start
info: Starting PubSweet app
info: No "start" script defined in app. Falling back to "pubsweet server" behavior.
@@ -76,7 +74,7 @@ One of the following things might be happening:
If `postgres` is running you should see the following by running: `docker ps`
-```
+```bash
user@server:~$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a9db084764be postgres "docker-entrypoint..." 3 months ago Up 2 months 0.0.0.0:5440->5432/tcp a9db084764be_xpub_postgres_1
@@ -84,7 +82,7 @@ a9db084764be postgres "docker-entrypoint..." 3 months ago
Otherwise start the postgres docker service by following the steps in the README file of the application. Probably it will be:
-```
+```bash
$ yarn start:services
```
@@ -92,7 +90,7 @@ $ yarn start:services
The default configuration is in the folder `config/default.js` of your app. Please, souble the check the guide in the README file of the project for the correct way of configuring your app. Also in the config folder you will find other files like `developement.js`, `test.js`. Those files overwrite the `default.js` configuration depending on the environment that you run your app in. This can be checked by running:
-```
+```bash
user@server:~/Projects$ echo $NODE_ENV
development
```
@@ -104,7 +102,7 @@ You can set your environment by performing `export NODE_ENV=development` that wi
There are two ports that should be open. First one is the web app port which usually is 3000 - but this is configured from the config file of the application - and the second one is the database port (Postgres) which is usually 5432.
Using `telnet` or `nc` tool we can check if these ports are open :
-```
+```bash
$ nc -zv localhost 5432
Ncat: Version 7.50 ( https://nmap.org/ncat )
Ncat: Connected to ::1:5432.
@@ -113,13 +111,13 @@ Ncat: 0 bytes sent, 0 bytes received in 0.01 seconds.
In case that fails we should open the ports from the firewall list, using ufw or iptables by performing the following command:
-```
+```bash
ufw allow 5432
```
or
-```
+```bash
sudo iptables -A INPUT -p tcp -d 0/0 -s 0/0 --dport 3000 -j ACCEPT
```
diff --git a/docs/content/setup.md b/docs/content/setup.md
new file mode 100644
index 0000000000000000000000000000000000000000..7733842d0392a195c235075440eb75ef6b94907d
--- /dev/null
+++ b/docs/content/setup.md
@@ -0,0 +1,108 @@
+There are a number of ways of running the application in development.
+
+1. Hybrid - runs backing services with Docker but keeps the Node process on the host. Recommended for most developers.
+2. Docker - runs everything in Docker. Easiest to get started but has limitations.
+3. No Docker - doesn't require Docker. Requires a bit more up front set up.
+
+## Hybrid
+
+### Requirements
+
+- Node.JS >8.9
+- Docker
+
+### Setup
+
+```bash
+yarn
+yarn start:services
+# in another terminal
+yarn server
+# or for running tests (db has to be running)
+yarn test
+```
+
+### Explanation
+
+This the recommended way to develop PubSweet applications as it minimises system software dependencies and maximises flexibility.
+
+- `yarn` installs JavaScript dependencies
+- `yarn start:services` uses Docker Compose to start containers for the backing services (at present just the PostgreSQL database)
+- `yarn server` runs `pubsweet server` which does a number of things:
+ - set up the database if necessary, including a default user (with credentials `admin`/`password` by default)
+ - build client side application with Webpack
+ - start server application with Express
+
+## Full Docker
+
+### Requirements
+
+- Docker
+
+### Setup
+
+```bash
+docker-compose up
+# or `yarn start` if you have Node
+# or `pubsweet start` if you have PubSweet CLI
+```
+
+### Explanation
+
+This is the easiest way to get up and running after cloning a PubSweet application.
+
+Docker Compose does the following:
+
+- start containers for the backing services (database)
+- start a container and mount the code from the host into the it
+- run `yarn` in the container to install dependencies
+- run `pubsweet server` (see above for details of what this does)
+
+This setup has a number of drawbacks:
+
+- file watching and reloading is slower
+- harder to debug Node process
+- can't `npm link` dependencies outside of the project root
+- can lead to issues with file permissions
+
+## No Docker
+
+### Requirements
+
+- Node >8.9
+- PostgreSQL >9.6
+
+### Setup
+
+Start PostgreSQL server according to your OS, create a database and configure the connection details in the PubSweet application.
+
+```bash
+yarn
+yarn server
+```
+
+If you setup a user and password for you PostgreSQL database and you get an error like
+
+```bash
+error: error: password authentication failed for user ...
+```
+
+you can write the correct credentials in config/default.js, in `pubsweet-server.db` like so
+
+```js static
+ 'pubsweet-server': {
+ db: {
+ user: ...,
+ password: ...,
+ // these are optional, in case you don't use default
+ host: ...,
+ database: ...,
+ port: ...
+ },
+```
+
+More information on the db javascript object [here](https://node-postgres.com/api/pool).
+
+### Explanation
+
+By installing PostgreSQL server natively on you machine, you remove the need for Docker but that requires a bit more up front configuration. See above for details of what the `server` command does.
diff --git a/docs/styleguide.config.js b/docs/styleguide.config.js
index bd6892bfa64eed7004d0ba386d1049b85d0610c8..9e914d53744ae7a82d03593ef497409b15f673b6 100644
--- a/docs/styleguide.config.js
+++ b/docs/styleguide.config.js
@@ -102,6 +102,10 @@ module.exports = {
name: 'How can I debug?',
content: './content/how_can_i_debug.md',
},
+ {
+ name: 'Setup',
+ content: './content/setup.md',
+ },
{
name: 'FAQ',
content: './content/faq.md',
@@ -124,11 +128,11 @@ module.exports = {
components: '../packages/ui/src/molecules/*.js',
},
{
- name: 'Core-components',
- components: '../packages/components/!(xpub-*|model-*)/**/*.{jsx,js}',
+ name: 'Core components',
+ components: '../packages/components/!(xpub-*|model-*)/**/*.{js,jsx}',
},
{
- name: 'Xpub-components',
+ name: 'Xpub components',
components: '../packages/components/xpub-*/**/*.{jsx,js}',
},
],
diff --git a/packages/components/Login/index.js b/packages/components/Login/index.js
deleted file mode 100644
index e885e0590b3cc02fb91c11839cea1ce2a0b54fe5..0000000000000000000000000000000000000000
--- a/packages/components/Login/index.js
+++ /dev/null
@@ -1,3 +0,0 @@
-import Login from './src/LoginContainer'
-
-export default Login
diff --git a/packages/components/Login/package.json b/packages/components/Login/package.json
index 9a65f23c3e8e7743b79300319b3aa5c69e5051e5..822ac2122d2c79f213be5ca9efe82aaafd5b60b3 100644
--- a/packages/components/Login/package.json
+++ b/packages/components/Login/package.json
@@ -2,7 +2,7 @@
"name": "pubsweet-component-login",
"version": "2.1.1",
"description": "Basic login component for PubSweet",
- "main": "index.js",
+ "main": "src/index.js",
"author": "Collaborative Knowledge Foundation",
"license": "MIT",
"dependencies": {
diff --git a/packages/components/Login/Login.md b/packages/components/Login/src/Login.md
similarity index 100%
rename from packages/components/Login/Login.md
rename to packages/components/Login/src/Login.md
diff --git a/packages/components/Login/src/index.js b/packages/components/Login/src/index.js
new file mode 100644
index 0000000000000000000000000000000000000000..02ae6934bcca2584104d86bad4f2ef766ea0cb60
--- /dev/null
+++ b/packages/components/Login/src/index.js
@@ -0,0 +1,3 @@
+import Login from './LoginContainer'
+
+export default Login
diff --git a/packages/components/Signup/index.js b/packages/components/Signup/index.js
deleted file mode 100644
index ce5d7de642c988287390b34b9c4cb4540b9a0306..0000000000000000000000000000000000000000
--- a/packages/components/Signup/index.js
+++ /dev/null
@@ -1,3 +0,0 @@
-import Signup from './src/SignupContainer'
-
-export default Signup
diff --git a/packages/components/Signup/package.json b/packages/components/Signup/package.json
index 510b8ba5e8ca5490265199c3fcdc3373161da725..eab99b5ea3ee32dbbcb5bb83965e02806d40f772 100644
--- a/packages/components/Signup/package.json
+++ b/packages/components/Signup/package.json
@@ -2,14 +2,14 @@
"name": "pubsweet-component-signup",
"version": "1.0.41",
"description": "Basic signup form component for PubSweet",
- "main": "index.js",
+ "main": "src/index.js",
"author": "Collaborative Knowledge Foundation",
"license": "MIT",
"dependencies": {
"@pubsweet/ui": "^9.1.3",
"@pubsweet/ui-toolkit": "2.0.7",
"formik": "^1.3.0",
- "prop-types": "^15.5.10",
+ "prop-types": "^15.5.10",
"recompose": "^0.26.0"
},
"peerDependencies": {
diff --git a/packages/components/Signup/Signup.md b/packages/components/Signup/src/Signup.md
similarity index 100%
rename from packages/components/Signup/Signup.md
rename to packages/components/Signup/src/Signup.md
diff --git a/packages/components/Signup/src/index.js b/packages/components/Signup/src/index.js
new file mode 100644
index 0000000000000000000000000000000000000000..dd5ad57fa268fb800524f20051bfc5127aa92b49
--- /dev/null
+++ b/packages/components/Signup/src/index.js
@@ -0,0 +1,3 @@
+import Signup from './SignupContainer'
+
+export default Signup
diff --git a/packages/components/SortableList/package.json b/packages/components/SortableList/package.json
index b428867855f45310bb53f3c3f6fc6bdeb822fe48..f006034a6caf6dda421c9835db15b98ca62f8181 100644
--- a/packages/components/SortableList/package.json
+++ b/packages/components/SortableList/package.json
@@ -1,7 +1,7 @@
{
"name": "pubsweet-component-sortable-list",
"version": "0.1.13",
- "main": "src",
+ "main": "src/",
"license": "MIT",
"dependencies": {
"react-dnd": "^2.5.4",
diff --git a/packages/components/SortableList/SortableList.md b/packages/components/SortableList/src/SortableList.md
similarity index 100%
rename from packages/components/SortableList/SortableList.md
rename to packages/components/SortableList/src/SortableList.md