Document application packaging and deployment (single JAR, Docker, systemd, PSGI)

未关闭
#2,142 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
58/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
docker, dockerfile, java, markdown, perl, shell
领域
documentation

调研方向

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.

由索引模型根据 Issue 内容生成。

描述

documentation enhancement help wanted

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.jar runs 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 ENTRYPOINT so 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.md exists and is linked from README.md and
    docs/README.md.
  • Each scenario has a complete, tested example (commands and expected output).
  • make check-links passes.
  • The Dockerfile example builds and runs successfully.

Non-goals

  • Changing the JAR layout or @INC resolution (document what exists today).
  • Windows-specific deployment (a follow-up can add .bat and 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.gradle shadow plugin configuration
  • @INC resolution: src/main/java/org/perlonjava/runtime/RuntimeScalar.java
    and the PerlIncHandler class
  • Related design doc: dev/design/distro.md
主要语言
Perl
星标
67
派生
8
平均合并
5 小时 12 分钟
30 天内合并 PR
131

环境准备

  • 提供 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

fglock/PerlOnJava 的其他 Issue

查看 fglock/PerlOnJava 的全部 Issue

相似的 Issue

更多 Perl Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。