| | |
*Screenshots captured from a live deployment. Replace with your own after deploying.*
---
## Prerequisites
- A [Railway](https://railway.app) account
- A [GitHub](https://github.com) account (to fork and deploy)
---
## One-Click Deploy
[](https://railway.com/new/template/stirling-pdf-1)
Click the button above and Railway will:
1. Clone this repository
2. Build the Docker container from the official `stirlingtools/stirling-pdf` image
3. Deploy with automatic HTTPS, health checks, and monitoring
4. Assign a wildcard domain (e.g., `stirling-pdf-production-xxxx.up.railway.app`)
---
## Environment Variables
Stirling-PDF is ready to go with zero configuration, but you can customise via these environment variables:
### Security & Authentication
| Variable | Default | Description |
|---|---|---|
| `SECURITY_ENABLELOGIN` | `true` | Enable or disable authentication |
| `SECURITY_INITIALLOGIN_USERNAME` | `admin` | Custom initial admin username |
| `SECURITY_INITIALLOGIN_PASSWORD` | `stirling` | Custom initial admin password (change on first login!) |
| `LOGIN_ATTEMPT_COUNT` | `5` | Failed login attempts before account lockout |
| `LOGIN_RESET_TIME_MINUTES` | `10` | Minutes before locked account auto-unlocks |
| `CSRF_DISABLED` | `false` | Set `true` to disable CSRF (not recommended for production) |
### System Configuration
| Variable | Default | Description |
|---|---|---|
| `PORT` | `8080` | HTTP port (Railway sets this automatically) |
| `SYSTEM_DEFAULTLOCALE` | `en-US` | Default language/locale (e.g., `de-DE`, `fr-FR`, `ja-JP`) |
| `TZ` | `UTC` | Server timezone |
| `SYSTEM_GOOGLEVISIBILITY` | `false` | Allow Google indexing via robots.txt |
| `UI_LOGOSTYLE` | `classic` | Logo style: `classic` or `modern` |
### Email (optional — for user invitations)
| Variable | Default | Description |
|---|---|---|
| `MAIL_ENABLED` | `false` | Enable SMTP email for user invitations |
| `MAIL_HOST` | — | SMTP server host |
| `MAIL_PORT` | `587` | SMTP server port |
| `MAIL_USERNAME` | — | SMTP username |
| `MAIL_PASSWORD` | — | SMTP password |
| `MAIL_FROM` | — | From address for invitation emails |
| `MAIL_ENABLEINVITES` | `false` | Enable email-based user invitations |
### Advanced Configuration
For full configuration options — OAuth 2.0, SAML SSO, external databases, LibreOffice settings, and more — see the [Stirling PDF Configuration Guide](https://docs.stirlingpdf.com/setup/server-configuration).
---
## Why Deploy Stirling PDF on Railway?
| Feature | Benefit |
|---|---|
| **Zero dependencies** | No database, Redis, or volumes needed — just deploy |
| **Single container** | No complex orchestration or multi-service setup |
| **50+ built-in tools** | Replace dozens of separate PDF utilities with one app |
| **REST API included** | Automate PDF workflows in your existing pipeline |
| **File processing is stateless** | Files auto-deleted after processing — no cleanup needed |
| **Multi-arch support** | Runs on any Railway region and hardware |
With Railway, you get automatic HTTPS, global CDN, health monitoring, and scalable infrastructure — without managing servers.
---
## Deploy and Host
### About Hosting
Stirling PDF runs as a single Docker container with no external dependencies. It uses file-based storage by default (no database required), making it an ideal zero-dependency deployment for Railway.
The default admin credentials are:
- **Username:** `admin`
- **Password:** `stirling`
You will be forced to change the password on first login when authentication is enabled.
### Health Endpoint
Railway uses the following endpoint for health checks:
- **URL:** `/api/v1/info/status`
- **Timeout:** 30 seconds
- **Start period:** 30 seconds (gives Java time to boot)
---
## Common Use Cases
- **Personal PDF toolkit** — Replace Acrobat with a self-hosted, private alternative
- **Team document processing** — Share PDF tools across a team without per-seat licenses
- **API-driven automation** — Integrate PDF conversion, OCR, and signing into CI/CD pipelines
- **Document signing workflows** — Self-hosted signing without third-party services
---
## Dependencies for Stirling PDF
### Deployment Dependencies
- **Runtime:** Java 17+ (bundled in container)
- **Storage:** File-based (default) — no database required
- **Optional:** PostgreSQL or MySQL for external database mode (not needed for basic usage)
---
## Local Development
```bash
# Clone this template
git clone https://github.com/INAPP-Mobile/railway-stirling-pdf.git
cd railway-stirling-pdf
# Run with Docker (standalone)
docker run -d -p 8080:8080 stirlingtools/stirling-pdf:latest
# Open http://localhost:8080
```
---
## License
Stirling PDF is open-core. The core PDF tools are MIT-licensed, with paid enterprise features available. See the [LICENSE](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/LICENSE) for details.
**Template License:** MIT — feel free to fork and adapt.
---
## Resources
- [Stirling PDF Documentation](https://docs.stirlingpdf.com)
- [Stirling PDF GitHub](https://github.com/Stirling-Tools/Stirling-PDF)
- [Stirling PDF API Docs](https://registry.scalar.com/@stirlingpdf/apis/stirling-pdf-processing-api/)
- [Railway Documentation](https://docs.railway.app)
- [Community Discord](https://discord.gg/HYmhKj45pU)
## Similar templates
- [Rocky Linux](https://railway.com/deploy/rocky-linux) — [Jul'26] Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.
Open this page in a browser: https://railway.com/deploy/stirling-pdf-1