--- title: "Offline PDF export library installation" canonical: "https://support.appfire.com/space/BTdc/3720216577/Offline%20PDF%20export%20library%20installation" format: markdown --- **Audience:** Jira Data Center administrators in air-gapped / offline environments **Scope:** Export library installation only (not export panel / template configuration) ## Overview BigTemplate ships export tooling **inside the plugin JAR** as source only. On startup it runs `npm install` and downloads Chromium — both require internet and fail on air-gapped servers. **Workaround:** Build the export folder on an **internet-connected machine** (same OS and CPU architecture as Jira), then copy it to the Jira temp directory. > ℹ️ **Important** > ℹ️ > ℹ️ - Deleting {java.io.tmpdir}/puppeteer-export and restarting Jira **does not** fix the problem — BigTemplate recreates the folder and retries online installation. > ℹ️ - **Do not** use Reinstall export libraries on air-gapped servers after manual installation. > ℹ️ > ℹ️ **Related documentation**: [BigTemplate Installation — Export Diagnostics](https://appfire.atlassian.net/wiki/spaces/BTdc/pages/3536388428/BigTemplate+installation#Export-diagnostics) ## Prerequisites **Jira server (air-gapped):** - Jira Data Center, BigPicture, and BigTemplate (licensed) - Node.js **≥ 20.15.0** and npm on the **Jira service PATH** - ~500 MB–1 GB free space in the temp directory **Preparation machine (internet-connected):** - Same **OS and CPU architecture** as the Jira server - Same **BigTemplate JAR** as installed on Jira - Node.js **≥ 20.15.0** ## Target path ``` {java.io.tmpdir}/puppeteer-export/ ``` Find the path via Export Diagnostics, `atlassian-jira.log`, or the JVM property `java.io.tmpdir`. Optional override: `pdf-export.user-specified.puppeteer-export.directory` ## Procedure ### 1. Install BigTemplate on air-gapped Jira Install Jira DC → BigPicture → BigTemplate → Node 20.15+ on system PATH → restart Jira. Export Diagnostics step 6 will fail until step 4 below — that is expected. ### 2. Extract source from the BigTemplate JAR (preparation machine) From `app-bigtemplate-jiraserver-.jar`, extract: ``` ppm/export/puppeteer-export.zip ``` Use either method: ``` jar xf app-bigtemplate-jiraserver-.jar ppm/export/puppeteer-export.zip ``` ``` unzip app-bigtemplate-jiraserver-.jar ppm/export/puppeteer-export.zip ``` Unpack into a working folder: ``` mkdir puppeteer-export-work unzip ppm/export/puppeteer-export.zip -d puppeteer-export-work ``` On Windows, if `unzip` is unavailable: ``` tar -xf ppm\export\puppeteer-export.zip -C puppeteer-export-work ``` The working folder must contain `package.json`, `check.js`, and `v2/`. ### 3. Install dependencies (preparation machine, with internet) ``` cd puppeteer-export-work export PLAYWRIGHT_BROWSERS_PATH=0 npm install npm run check-deps ``` On Windows (Command Prompt): ``` set PLAYWRIGHT_BROWSERS_PATH=0 npm install npm run check-deps ``` `npm run check-deps` must succeed. Confirm that `node_modules/playwright-core/.local-browsers/chromium-*` exists. ### 4. Copy to air-gapped Jira 1. Stop Jira. 2. Delete `{java.io.tmpdir}/puppeteer-export`. 3. Copy the **entire** contents of `puppeteer-export-work` to `{java.io.tmpdir}/puppeteer-export/`. - Include the full `node_modules` directory. - Do not create a nested `puppeteer-export/puppeteer-export/` structure. 4. Start Jira. ### 5. Verify | **Step** | **Check** | **Air-gapped expectation** | | --- | --- | --- | | 1 | npm status page | May fail — acceptable if steps 2–6 pass | | 2 | Node.js version | Must pass | | 3 | npm version | Must pass | | 4 | Temp directory read | Must pass | | 5 | Temp directory write | Must pass | | 6 | Export library installation | **Must pass** | Run a test PDF export. Step 1 red and step 6 green indicate a working setup. > **Export panel on issues:** If export does not appear on Jira issues, configure the global widget and per-project templates separately. That is not covered by this procedure. ## After a BigTemplate upgrade Repeat steps 2–4 using the **new** BigTemplate JAR. Do not reuse `node_modules` from an older version. ## Troubleshooting | **Issue** | **Fix** | | --- | --- | | Step 6 fails | Re-copy the full folder; verify `npm run check-deps` on the preparation machine | | Export fails, step 6 passes | Wrong OS bundle — rebuild on a machine matching the Jira server OS | | Steps 2–3 fail | Node.js or npm not on the Jira service PATH | | No export on issues | Separate topic: templates and widget configuration | For support, check `atlassian-jira.log` and search for `puppeteer-export`, `check-deps`, and `npm`. ## Network endpoints (preparation machine only) Required only during step 3 on the internet-connected machine, not on the air-gapped Jira server: - `registry.npmjs.org` — npm packages - Playwright CDN (e.g. `playwright.azureedge.net`) — Chromium download > Macro (refined-stepper) > > > Macro (refined-stepper-item) > > Install Jira DC → BigPicture → BigTemplate → Node 20.15+ on system PATH → restart Jira. > > Export Diagnostics step 6 will fail until step 4 below — that is expected. > > > > Macro (refined-stepper-item) > > From `app-bigtemplate-jiraserver-.jar`, extract: > > ``` > ppm/export/puppeteer-export.zip > > ``` > > Use either method: > > ``` > jar xf app-bigtemplate-jiraserver-.jar ppm/export/puppeteer-export.zip > > ``` > > ``` > unzip app-bigtemplate-jiraserver-.jar ppm/export/puppeteer-export.zip > > ``` > > Unpack into a working folder: > > ``` > mkdir puppeteer-export-work > unzip ppm/export/puppeteer-export.zip -d puppeteer-export-work > > ``` > > On Windows, if `unzip` is unavailable: > > ``` > tar -xf ppm\export\puppeteer-export.zip -C puppeteer-export-work > > ``` > > The working folder must contain `package.json`, `check.js`, and `v2/`. > > > > Macro (refined-stepper-item) > > > > > > Macro (refined-stepper-item)