diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..45ac77b9 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -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) ! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..70dfb989 --- /dev/null +++ b/CONTRIBUTING.md @@ -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 git@github.com: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 diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..7a1a2f82 --- /dev/null +++ b/LICENSE.md @@ -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. diff --git a/README.md b/README.md index 78528b04..05a692d9 100644 --- a/README.md +++ b/README.md @@ -7,21 +7,111 @@ 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 @@ -29,7 +119,15 @@ $ 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 | | -------------------- | -------------------------------------------------------------------------------- | @@ -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)