Skip to content

Commit fa35180

Browse files
bmblbbmblb
authored
Merge pull request #12 from bryntum/doc-update
Guide updated
2 parents f7d1b5c + 2809190 commit fa35180

File tree

5 files changed

+174
-106
lines changed

5 files changed

+174
-106
lines changed

‎README.md‎

Lines changed: 50 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,87 @@
1-
# Standalone export server
1+
# PDF export server
22

3-
This package contains the sources for an executable service which builds PDF and PNG files out of HTML fragments.
3+
This repository contains sources for a server which builds PDF and PNG files out of HTML fragments.
4+
Server is designed to work with [Bryntum PDF Export feature](https://bryntum.com/products/grid/docs/api/Grid/feature/export/PdfExport).
5+
See compatibility table between Export server and other Bryntum products in this [table](docs/compatibility.md).
46

7+
Live demos available here:
8+
- [Gantt](https://bryntum.com/products/gantt/examples/export/)
9+
- [Scheduler](https://bryntum.com/products/scheduler/examples/export/)
10+
- [Grid](https://bryntum.com/products/grid/examples/export/)
11+
12+
#### Features
513
- Uses headless chromium browser.
6-
- Easy OS (Linux, Windows, Mac) independent build/install into binary or runnable as NodeJS instance.
14+
- Runnable as NodeJS instance.
15+
- Docker container available at [Docker Hub](https://hub.docker.com/r/bryntum/pdf-export-server)
716
- Written in JavaScript and fully adaptable.
8-
- Can be used as standalone service or as an intermediary between your (C#, Java, PHP) frontend and backend. Just catch
9-
the HTML fragments, call the service and serve the binary.
10-
11-
## Compatibility
12-
13-
| pdf-export-server | ExtScheduler/ExtGantt | Bryntum Grid/Scheduler/Gantt |
14-
|---|---|---|
15-
| 1.0.0 | * | * |
17+
- Can be used as standalone service or as an intermediary between your (C#, Java, PHP) frontend and backend.
1618

17-
## Usage
19+
## Getting started
1820

19-
To start PDF export server you only need to install packages and run a node command:
21+
### Using NodeJS
2022

23+
1. Check out this repository
24+
```shell
25+
~$ git clone git@github.com:bryntum/pdf-export-server.git
26+
~$ cd pdf-export-server
27+
```
28+
2. Install packages
2129
```shell
2230
pdf-export-server$ npm i
23-
pdf-export-server$ node ./src/server.js
31+
```
32+
3. Start the server
33+
```shell
34+
pdf-export-server$ npm run start
2435
Access-Control-Allow-Origin: *
2536
Http server started on port 8080
2637
```
2738

28-
<a name="cli"></a>
29-
30-
## Configuration
39+
Multiple configuration options are available as you can see in the [configuration](docs/configuration.md) guide.
3140

32-
You can specify application options in the app.config.js or by passing them from the CLI.
3341

34-
```shell
35-
pdf-export-server$ node ./src/server.js --help
36-
37-
Usage: ./server [OPTION]
38-
39-
-h, --http=PORT Start http server on port
40-
-H, --https=PORT Start https server on port
41-
-c, --cors=HOST CORS origin, default value "*". Set to "false" to disable CORS
42-
-m, --maximum=SIZE Maximum upload size (default 50mb)
43-
-r, --resources=PATH The absolute path to the resource directory. This path will be accessible via the webserver
44-
--max-workers=WORKERS Maximum amount of workers (puppeteer instances) (default: 5)
45-
--level=LEVEL Specify log level (error, warn, verbose). Default "error"
46-
--timeout=TIMEOUT Request timeout time in seconds
47-
--quick Provide to only wait for page load event
48-
--no-sandbox Provide to pass no-sandbox argument to chromium
49-
--no-config Provide to ignore app.config.js
50-
--verbose Alias for --level=verbose
51-
--help Show help message
52-
```
42+
### Using image from Docker Hub
5343

54-
The following command starts a server with HTTP and HTTPS on ports 8080 and 8081 respectively:
44+
For your convenience we have pre-built container available on
45+
[Docker Hub](https://hub.docker.com/r/bryntum/pdf-export-server).
5546

47+
1. Pull it
5648
```shell
57-
pdf-export-server$ node ./src/server.js -h 8080 -H 8081 -m 100mb
49+
$ docker pull bryntum/pdf-export-server
5850
```
59-
60-
The flag -m above extends the upload capacity to 100 MB.
61-
62-
##### Workers
63-
64-
To speed up the export we parallelize it using puppeteer instances (workers). It is slower than using tabs, but much
65-
easier to restart the export if browser or tab fails. By default, there are 5 workers which feel fine on machines with
66-
as much as 1 GB RAM. In general, it takes about 2-3 seconds to generate one PDF page, depending on network speed and
67-
overall system performance. Workers amount is not limited.
68-
69-
##### Resources
70-
<a name="CORS"></a>
71-
When sending HTML fragments to the server, the server launches puppeteer and tries to generate PDF-files based on the
72-
provided input. In case the CSS stylesheets are not accessible to the server (for example the resources are protected
73-
by a login session), you can make use of the built-in web-server to serve resources.
74-
75-
In this case configure the export feature with `translateURLsToAbsolute`.
76-
77-
```javascript
78-
new Grid({
79-
features : {
80-
pdfExport : {
81-
exportServer : 'http://export-host:8081',
82-
translateURLsToAbsolute : 'http://export-host:8081/resources'
83-
}
84-
}
85-
})
51+
2. Create `docker-compose.yml` and configure image/port forwarding
52+
```yaml
53+
version: "3.9"
54+
services:
55+
web:
56+
image: "bryntum/pdf-export-server:1.0.1"
57+
ports:
58+
- "8080:8080"
8659
```
87-
88-
This tells the export plugin to change all the used stylesheet URLs to be fetched from
89-
`http://export-host:8081/resources`. Then copy all the resources your application uses to the export server keeping the
90-
folder hierarchy. After this map the virtual `http://export-host:8081/resources` to the real folder on your export
91-
server:
92-
60+
3. Start container
9361
```shell
94-
pdf-export-server$ node ./src/server.js -r /web/application/styles
62+
$ docker compose -f docker-compose.yml up
9563
```
9664

97-
The path can be either absolute (`/web/application/styles`) or relative (`web/application/styles`),
98-
for example when you start the export server with the export demo locally.
99-
100-
So if you're running the export demo from the localhost, for example `http://lh/bryntum-suite/grid/examples/export/`,
101-
you need to copy the folders starting from the `bryntum-suite` to the `examples/_shared/server/web/application/styles`,
102-
keeping only resources the demo uses (css files, fonts etc.).
103-
104-
##### Security
105-
106-
Be careful which folder to set open with the -r option; php, aspx/cs, config files won't be interpreted but served as
107-
download when hit. Only point folders which contain resources needed for generating the page, like fonts, CSS or image
108-
files.
109-
11065
## Links
11166
- [Architecture](docs/architecture.md)
11267
- [Server protocol](docs/protocol.md)
11368
- [Building executable](docs/building.md)
11469
- [Docker](docs/docker.md)
70+
- [Compatibility table](docs/compatibility.md)
71+
- [Configuration options](docs/configuration.md)
72+
- [Troubleshooting](docs/troubleshooting.md)
11573

11674
## FAQ
11775

11876
### Exported PDF/PNG doesn't look correct
11977

12078
Most likely server couldn't get access to the resources. See [architecture](docs/architecture.md) guide for detailed
121-
information or [resources section](#CORS) for short summary.
79+
information, [resources section](#CORS) for short summary and [troubleshooting](docs/troubleshooting.md) guide for
80+
debugging tips.
81+
82+
### PDF/PNG file is not generated
83+
84+
Most likely there is a problem on the server, see [troubleshooting](docs/troubleshooting.md) guide for help.
12285

12386
### Cannot export using HTTPS
12487

‎docs/architecture.md‎

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -302,22 +302,3 @@ regular client which is browsing `http://production.org/app`
302302

303303
Of course, we can let PDF export server to have a local copy of resources like in the scenario with local web server and
304304
remove export server.
305-
306-
## Troubleshooting
307-
308-
It is difficult to see what's going on in the export server - it is remote, it uses headless
309-
browser. Before diving into debugging actual server we may try using extensive logging:
310-
311-
```shell
312-
$ node src/server.js --verbose
313-
```
314-
315-
This config will log page errors and if there were problems loading resources you can see similar message
316-
in the log file:
317-
318-
```
319-
2022-05-13T14:58:47.745Z error: [Worker@3qj8yt1k45egung7cd13n] Page 3/50 reports: Access to font at
320-
'http://localhost/grid/resources/fonts/Lato-Regular.woff2' from origin 'null' has been blocked by CORS policy: No
321-
'Access-Control-Allow-Origin' header is present on the requested resource.
322-
location: about:blank
323-
```

‎docs/compatibility.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
## Compatibility
2+
3+
| pdf-export-server | ExtScheduler/ExtGantt | Bryntum Grid/Scheduler/Gantt |
4+
|-------------------|---|---|
5+
| 1.0.0 | * | * |
6+
| 1.0.1 | * | * |

‎docs/configuration.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Configuration
2+
3+
You can specify application options in the app.config.js or by passing them from the CLI.
4+
5+
```shell
6+
pdf-export-server$ node ./src/server.js --help
7+
8+
Usage: ./server [OPTION]
9+
10+
-h, --http=PORT Start http server on port
11+
-H, --https=PORT Start https server on port
12+
-c, --cors=HOST CORS origin, default value "*". Set to "false" to disable CORS
13+
-m, --maximum=SIZE Maximum upload size (default 50mb)
14+
-r, --resources=PATH The absolute path to the resource directory. This path will be accessible via the webserver
15+
--max-workers=WORKERS Maximum amount of workers (puppeteer instances) (default: 5)
16+
--level=LEVEL Specify log level (error, warn, verbose). Default "error"
17+
--timeout=TIMEOUT Request timeout time in seconds
18+
--quick Provide to only wait for page load event
19+
--no-sandbox Provide to pass no-sandbox argument to chromium
20+
--no-config Provide to ignore app.config.js
21+
--verbose Alias for --level=verbose
22+
--help Show help message
23+
```
24+
25+
The following command starts a server with HTTP and HTTPS on ports 8080 and 8081 respectively:
26+
27+
```shell
28+
pdf-export-server$ node ./src/server.js -h 8080 -H 8081 -m 100mb
29+
```
30+
31+
The flag -m above extends the upload capacity to 100 MB.
32+
33+
##### Workers
34+
35+
To speed up the export we parallelize it using puppeteer instances (workers). It is slower than using tabs, but much
36+
easier to restart the export if browser or tab fails. By default, there are 5 workers which feel fine on machines with
37+
as much as 1 GB RAM. In general, it takes about 2-3 seconds to generate one PDF page, depending on network speed and
38+
overall system performance. Workers amount is not limited.
39+
40+
##### Resources
41+
<a name="CORS"></a>
42+
When sending HTML fragments to the server, the server launches puppeteer and tries to generate PDF-files based on the
43+
provided input. In case the CSS stylesheets are not accessible to the server (for example the resources are protected
44+
by a login session), you can make use of the built-in web-server to serve resources.
45+
46+
In this case configure the export feature with `translateURLsToAbsolute`.
47+
48+
```javascript
49+
new Grid({
50+
features : {
51+
pdfExport : {
52+
exportServer : 'http://export-host:8081',
53+
translateURLsToAbsolute : 'http://export-host:8081/resources'
54+
}
55+
}
56+
})
57+
```
58+
59+
This tells the export plugin to change all the used stylesheet URLs to be fetched from
60+
`http://export-host:8081/resources`. Then copy all the resources your application uses to the export server keeping the
61+
folder hierarchy. After this map the virtual `http://export-host:8081/resources` to the real folder on your export
62+
server:
63+
64+
```shell
65+
pdf-export-server$ node ./src/server.js -r /web/application/styles
66+
```
67+
68+
The path can be either absolute (`/web/application/styles`) or relative (`web/application/styles`),
69+
for example when you start the export server with the export demo locally.
70+
71+
So if you're running the export demo from the localhost, for example `http://lh/bryntum-suite/grid/examples/export/`,
72+
you need to copy the folders starting from the `bryntum-suite` to the `examples/_shared/server/web/application/styles`,
73+
keeping only resources the demo uses (css files, fonts etc.).
74+
75+
##### Security
76+
77+
Be careful which folder to set open with the -r option; php, aspx/cs, config files won't be interpreted but served as
78+
download when hit. Only point folders which contain resources needed for generating the page, like fonts, CSS or image
79+
files.

‎docs/troubleshooting.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Troubleshooting
2+
3+
### Check logs
4+
5+
It is difficult to see what's going on in the export server - it is remote, it uses headless
6+
browser. Before diving into debugging actual server we may try using extensive logging:
7+
8+
```shell
9+
$ node src/server.js --verbose
10+
```
11+
12+
This config will log page errors and if there were problems loading resources you can see similar message
13+
in the log file:
14+
15+
```
16+
2022-05-13T14:58:47.745Z error: [Worker@3qj8yt1k45egung7cd13n] Page 3/50 reports: Access to font at
17+
'http://localhost/grid/resources/fonts/Lato-Regular.woff2' from origin 'null' has been blocked by CORS policy: No
18+
'Access-Control-Allow-Origin' header is present on the requested resource.
19+
location: about:blank
20+
```
21+
22+
### Inspect outgoing request
23+
24+
Sometimes paths to resources might be generated incorrectly. If your PDF does not look correct, this is recommended
25+
first step to take.
26+
27+
1. Open network tab
28+
2. Run export
29+
3. Find outgoing request
30+
4. Open `Payload` tab
31+
5. Expand object, copy HTML string
32+
6. Create file on a local filesystem, paste HTML string
33+
7. Save file with `.html` extension
34+
8. Open this file in a browser, preferably via a web server (there are a number of simple web server for static files,
35+
e.g. [serve](https://www.npmjs.com/package/serve) package on the NPM)
36+
37+
The page you will be looking at in a browser is similar to what a headless browser on the server will. You can see which
38+
resource were not loaded and why, inspect paths etc. It can take several iterations to configure your JS app to generate
39+
correct HTML at that point export server should handle it too.

0 commit comments

Comments
 (0)