Skip to content
Snippets Groups Projects
Commit 197894e8 authored by Jure's avatar Jure
Browse files

docs: add setup docs, fix theming and faq

parent cec8875d
No related branches found
No related tags found
No related merge requests found
......@@ -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
}
```
......
# 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
```
......
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.
......@@ -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}',
},
],
......
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