Document application packaging and deployment (single JAR, Docker, systemd, PSGI)
I maintainer di solito rispondono entro 1 giorno
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Idoneità per principianti
- 58/100
- Tipo di issue
- Documentazione
- Chiarezza
- Specificata chiaramente
- Stato di attività
- Attiva
- Ambito
- documentation
Direzione di ricerca
Start by reading docs/getting-started/docker.md, examples/http_server_plack/README.md, the shadow-JAR configuration in build.gradle, and the PerlIncHandler/RuntimeScalar.java code that defines @INC. Draft docs/guides/deployment.md scenario by scenario, running the documented commands and the Docker build as you go. Link the guide from README.md and docs/README.md, then run make check-links; done means every scenario has a tested example and the Dockerfile builds and runs.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
Problem
PerlOnJava bundles 150+ modules in a single JAR and runs on Linux, macOS, and
Windows, but there is no documentation explaining how a user packages their own
Perl application for deployment. The gap between "it works after make" and
"I can ship this to a server" is undocumented.
Today a user who wants to deploy must reverse-engineer the JAR layout, figure
out how @INC resolves resources inside the JAR, and guess at the right
Dockerfile layers. This is the single largest barrier to the "single JAR"
value proposition and comes up immediately when presenting the project to new
users.
Requested deliverable
A new guide at docs/guides/deployment.md (linked from the README and the
docs index) covering the scenarios below. Each scenario should include a
complete, copy-pasteable example that a user can adapt.
1. Running a script from the filesystem
The simplest case: jperl points at a script and a lib/ directory on disk.
Document the directory layout, how to pass -Ilib, and how @INC search
order works (bundled modules, then filesystem paths, then JPERL_LIB if any).
2. Adding application code to the JAR
How to add .pl and .pm files to the shadow JAR so the result is a single
self-contained artifact. Cover:
- Where in the JAR tree application modules should go (the resource path that
maps to@INC). - A Gradle task or shell recipe that takes a source directory and produces an
augmented JAR. - How to set the entry-point script so
java -jar app.jarruns the
application directly. - Whether and how
jcpan-installed modules can be baked in.
3. Docker deployment
Extend the existing docs/getting-started/docker.md (or link to it) with a
production-oriented multi-stage Dockerfile that:
- Builds the augmented JAR in a builder stage.
- Copies only the JAR and a JRE into the final image.
- Sets
ENTRYPOINTso the container runs the application. - Shows how to add JDBC drivers.
The existing Docker page covers building PerlOnJava itself; this section
covers deploying an application on top of it.
4. systemd / process manager
A minimal example of running the JAR as a long-lived service: a systemd unit
file, or equivalent guidance for other process managers. Cover JVM memory
flags, restart policy, and log output.
5. PSGI / web application deployment
A worked example combining Plack::Handler::Netty with the JAR packaging from
scenario 2, producing a single JAR that starts an HTTP server. Link to the
existing examples/http_server_plack/ for the application code; this section
covers only the packaging and deployment side.
Acceptance criteria
docs/guides/deployment.mdexists and is linked fromREADME.mdand
docs/README.md.- Each scenario has a complete, tested example (commands and expected output).
make check-linkspasses.- The Dockerfile example builds and runs successfully.
Non-goals
- Changing the JAR layout or
@INCresolution (document what exists today). - Windows-specific deployment (a follow-up can add
.batand Windows Service
examples). - GraalVM native-image packaging (tracked separately in
dev/design/graalvm.md).
Context
- Existing Docker docs:
docs/getting-started/docker.md - Existing PSGI example:
examples/http_server_plack/README.md - JAR resource layout: controlled by
build.gradleshadow plugin configuration @INCresolution:src/main/java/org/perlonjava/runtime/RuntimeScalar.java
and thePerlIncHandlerclass- Related design doc:
dev/design/distro.md
- Lingua principale
- Perl
- Stelle
- 67
- Fork
- 8
- Merge medio
- 5h 12m
- PR unite (30g)
- 131
Preparare l'ambiente
- Include un Dockerfile o un file Docker Compose
- Nessun modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di fglock/PerlOnJava
-
area:cpan-port bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 70/100
fglock/PerlOnJava#2153 ·
I maintainer di solito rispondono entro 1 giorno
-
area:cpan-port area:parser bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
fglock/PerlOnJava#2137 ·
I maintainer di solito rispondono entro 1 giorno
-
area:backend area:cpan-port area:runtime bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
fglock/PerlOnJava#2071 ·
I maintainer di solito rispondono entro 1 giorno
-
area:runtime documentation enhancement
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
fglock/PerlOnJava#1579 ·
I maintainer di solito rispondono entro 1 giorno
-
area:cpan-port bug
Difficoltà 3/5 1-2 giorni Idoneità per principianti 62/100
fglock/PerlOnJava#2157 ·
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di fglock/PerlOnJava
Issue simili
-
Dev-output directory preparation accepts file-valued lib/include paths and fails on dangling linksApertateam-cli
Difficoltà 2/5 1-3 ore Idoneità per principianti 70/100
I maintainer di solito rispondono entro 2 giorni
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 66/100
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 93/100
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 73/100
inverse-inc/packetfence#9728 ·
I maintainer di solito rispondono entro 1 giorno
-
fix(char-create): show the real reason a character is refusedForse già presa @baphomello l’ha presa 1 giorno fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 84/100
I maintainer di solito rispondono entro 1 giorno