Skip to content

Commit

Permalink
Merge pull request #95 from KnpLabs/doc/add-documentation
Browse files Browse the repository at this point in the history 
Add documentation
  • Loading branch information
@alexpozzi
alexpozzi authored Aug 24, 2021
2 parents a30d3c4 + fba85ea commit da79483
Show file tree
Hide file tree
Showing 4 changed files with 274 additions and 24 deletions.
64 changes: 64 additions & 0 deletions CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@

# Contributor Covenant Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to make participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment
include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

## Scope

This Code of Conduct applies within all project spaces, and it also applies when
an individual is representing the project or its community in public spaces.
Examples of representing a project or community include using an official
project e-mail address, posting via an official social media account, or acting
as an appointed representative at an online or offline event. Representation of
a project may be further defined and clarified by project maintainers.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

[homepage]: https://www.contributor-covenant.org

## Contact
If you have any questions or feedback, [please ping us](https://twitter.com/KNPLabs) !
78 changes: 78 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@

# Thanks for contributing!

:+1: First of all, thanks for contributing! The team is happy to help if you
have any questions. :feet:
The following is a set of guidelines for contributing to the server-side-renderer
repository, which is hosted by the [KNP Labs Organization](https://github.com/KnpLabs)
on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose
changes to this document opening a pull request. :shipit:

## Code of Conduct

This project and everyone participating in it is governed by the following
[Code of Conduct](https://github.com/KnpLabs/server-side-renderer/blob/master/CODE_OF_CONDUCT.md).
By participating, you are expected to uphold this code.

## Reporting a bug

#### Before submitting a bug
- Verify that you are using the latest server-side-renderer version;
- Double-check the [documentation](https://github.com/KnpLabs/server-side-renderer/blob/master/README.md)
to see if you're not misusing the library;
- Check if the issue has already been reported. If it has, and the issue is still
open, add a comment to the existing issue instead of opening a new one.

#### How to submit a (good) bug report
To report a server-side-renderer bug please open a [GitHub issue](https://github.com/KnpLabs/server-side-renderer/issues)
following the rules below.

- Use a clear and descriptive title for the issue to identify the problem;
- Describe the steps needed to reproduce the bug including a code example when
possible;
- Give as much detail as possible about your environment (version, configuration, context, ...);

## Suggesting enhancements

To suggest enhancements please open a [GitHub issue](https://github.com/KnpLabs/server-side-renderer/issues)
following the rules below.

- Use a clear and descriptive title for the issue to identify the problem;
- Provide a step-by-step description of the suggested enhancement in as many
details as possible;
- Explain why this enhancement would be useful with one or more use cases;

## Contributing to the code

A pull request, is the best way to provide a bug fix or to propose enhancements to this repository.

When submitting a pull request please be sure to follow the same rules described
above in [Reporting a bug](#reporting-a-bug) and [Suggesting enhancements](#suggesting-enhancements)
sections depending on the nature of your change.

> Before starting to work on a large change please open an issue to ask the
maintainers if they are fine with it (no one likes to work for nothing!).

1. Fork the repository
2. Once the repository has been forked clone it locally
```
git clone [email protected]:USERNAME/server-side-renderer.git
```
3. Create a new branch
```
git checkout -b BRANCH_NAME master
```
4. Code!!!
5. Add/Update tests (if needed)
6. Update documentation (if needed)
7. Run the tests and make sure that they are passing
```
make test
```
8. Fix code style issues
```
make fix-js
```
9. Squash your commits
10. Rebase your branch on master and fix merge conflicts
11. Open the pull request
19 changes: 19 additions & 0 deletions LICENSE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
Copyright (c) 2021 KNPLabs

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.
137 changes: 113 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,29 +7,127 @@ Server-side-renderer

## Description

Docker image to server side render html pages using a browser (supports SPAs)
Docker image to server side render dynamic html pages using a browser.

This service exposes a web-service that lets you request the dynamic html
pages rendering. Html pages are rendered using a headless browser (at the
moment only Chrome is supported).

This service is scalable and you can add as many replicas as you want in order
to support a high number of requests. Every replica manages one request at a
time and, if all the replicas are busy the following requests will be queued
and processed sequentially.

Every replica can be configured to be a manager, a worker or both (see the
[configuration](#configuration) section to find out how to configure them).

### Manager

Managers are responsible to expose the web-service to let other services
request page renderings. They are adding requests to the Redis queue and
waiting for them to complete before returning the response to the client.

### Workers

Workers are responsible to render requested pages regularly polling for
available jobs in the Redis queue.

## Requirements

1. docker >= v19.03
2. docker-compose >= 1.19.0
3. redis

## How to use

### Basic usage

Run:

```bash
docker run --name my-server-side-renderer -e "QUEUE_REDIS_DSN=redis://my-redis-host:6379" -p 80:8080 -d knplabs/server-side-renderer
```

After that you should be able to access the service via `http://localhost/render?url=https://your-website.com/your-dynamic-page`.

### Docker compose usage

Create a `docker-compose.yaml` file with the following content:

```yaml
version: '3.8'

services:
manager:
image: knplabs/server-side-renderer
depends_on:
- redis
environment:
- QUEUE_REDIS_DSN=redis://redis:6379
ports:
- "80:8080"

redis:
image: redis:6.2.2-buster
```
## Setup on local environment
Run:
```bash
docker-compose -f docker-compose.yaml up -d
```

After that you should be able to access the service via `http://localhost/render?url=https://your-website.com/your-dynamic-page`.

## Configuration

Service configuration is entirely done via environment variables.

| Environment variable | Mandatory | Description |
| ---------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `LOG_LEVEL` | | Sets the log level. Accepted values are `DEBUG`, `INFO`, `WARNING`, `ERROR`. Default `INFO`. |
| | | |
| `QUEUE_REDIS_DSN` | * | Redis queue DSN. |
| `QUEUE_JOB_STALE_TIMEOUT` | | Defines how many milliseconds a job can stay in the queue without being picked by a worker. Default `10000`. |
| `QUEUE_JOB_TIMEOUT` | | Defines how many milliseconds a job can take to complete after being picked by a worker. Default `30000`. |
| | | |
| `MANAGER_ENABLED` | | Enables or disables the manager role. Accepted values are `0` (false) and `1` (true). Default `1`. |
| `MANAGER_HTTP_SERVER_HOST` | | Manager's web-server host. Default `0.0.0.0`. |
| `MANAGER_HTTP_SERVER_PORT` | | Manager's web-server port. Default `8080`. |
| | | |
| `WORKER_ENABLED` | | Enables or disables the worker role. Accepted values are `0` (false) and `1` (true). Default `1`. |
| `WORKER_RENDERER_TIMEOUT` | | Defines how many milliseconds the browser can take to render the requested page. Default 20000. |
| `WORKER_RENDERER_AUTHORIZED_REQUEST_DOMAINS` | | Defines a comma separated list of renderer's authorized request domains. This feature can be used to block some unwanted requests (for security or for performance reason) made by the dynamic html page you requested to render (wildcards are supported). Default `*` which means that all domains are allowed. |
| `WORKER_RENDERER_AUTHORIZED_REQUEST_RESOURCES` | | Defines a comma separated list of renderer's authorized request resource types. Accepted values are `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`, `websocket`, `manifest`, `other`. Default `*` which means that all resource types are allowed. |
| `WORKER_RENDERER_CHROME_OPTIONS` | | Defines a comma separated list of Chrome renderer's options (coma separated). Accepted values are listed [here](https://peter.sh/experiments/chromium-command-line-switches). Default `--disable-dev-shm-usage, --disable-gpu, --disable-setuid-sandbox, --disable-software-rasterizer, --headless, --no-sandbox, --safebrowsing-disable-auto-update, --use-gl=disabled`. |

You also have the possibility to run a post render script which is executed by the browser instance after the page has finished rendering and before returning the html content to the client.
In order to do so you can just override the default [post render script](/scripts/postRender.js) placed in the container's `/app/scripts` folder (see [docker-compose.test.js](/docker-compose.test.js) as an example).

## Setup a local environment

There is a `.env.dist` at the root directory that can be clone into `.env`.
It's up to you to edit these env vars according to your local environment.

**Note**: the `make dev` command will copy the `.env.dist` file into `.env` if it does not exist.

### Installation
### Start the local environment

```sh
$ make dev
```

This command will build and start the docker containers and update dependencies.

## Make commands
### Run tests

```sh
$ make test
```

This command will run unit and end to end tests.

## Available make targets

| Command | Description |
| -------------------- | -------------------------------------------------------------------------------- |
Expand All @@ -38,32 +136,23 @@ This command will build and start the docker containers and update dependencies.
| `start` | Start the docker-compose stack |
| `stop` | Stop the docker-compose stack |
| `install-deps` | Install front dependencies |
| | |
| `test` | Runs the tests (unit + end to end) |
| | |
| `lint-dockerfiles` | Runs the Dockerfile's linter |
| `lint-js` | Runs the JavaScript's linter |
| `fix-js` | Fixes JavaScript code styles issues |
| | |
| `build` | Build docker image (image tag required) |
| `push` | Push docker image on DockerHub (image tag required) |
| `push-latest` | Push docker image with latest tag (image tag required) |

## Test commands

| Command | Description |
| -------------------- | ------------------------------------- |
| `test` | Runs the tests (unit + end to end) |

## Linting commands

| Command | Description |
| -------------------- | ----------------------------------- |
| `lint-dockerfiles` | Runs the Dockerfile's linter |
| `lint-js` | Runs the JavaScript's linter |
| `fix-js` | Fixes JavaScript code styles issues |

## How to use

TODO

## Maintainers

Anyone can contribute to this repository (and it's warmly welcomed!). The following
people maintain and can merge into this library:
Everyone is welcome to contribute to this repository. Please be sure to check
the [contributing guidelines](https://github.com/KnpLabs/server-side-renderer/blob/master/CONTRIBUTING.md)
before opening an issue or a pull request.

The following people maintain and can merge into this library:
- [@alexpozzi](https://github.com/alexpozzi)
- [@hlegay](https://github.com/hlegay)

0 comments on commit da79483

Please sign in to comment.