Skip to content

feat(docker): modernize and harden the multi-architecture node workflow - #3

Open
3for wants to merge 8 commits into
developfrom
fix_docker_only_pr
Open

3for wants to merge 8 commits into
developfrom
fix_docker_only_pr

Conversation

@3for

@3for 3for commented Aug 26, 2026

Copy link
Copy Markdown
Owner

What does this PR do?

  • Modernizes the maintained Docker workflow for amd64 and arm64.
  • Supports local and remote image builds with source-aligned Mainnet configuration.
  • Runs FullNode as a non-root user and improves persistent-data protection.
  • Updates Mainnet/private-network behavior and removes the outdated Nile mode.
  • Adds dedicated Docker build, runtime, and smoke-test CI.
  • Updates the related deployment and migration documentation.

Why are these changes required?

The existing Docker workflow had fallen behind current java-tron development. It ran nodes as root, lacked consistent multi-architecture validation, and could use configuration from a different source than the node binary.

These changes provide a safer, reproducible, and maintainable first-party Docker workflow.

This PR has been tested by:

  • Unit Tests

    • Docker helper and lifecycle regression tests
    • CI selector and gate tests
    • Build-context filtering tests
    • JVM options and launcher tests
    • ShellCheck and Bash syntax checks
  • Manual Testing

    • BuildKit validation for both Dockerfiles
    • Real Docker build-context filtering
    • Runtime permission and restrictive umask checks
    • Mainnet/private configuration and container lifecycle verification

Follow up

  • Publish a compatible versioned non-root multi-architecture image.
  • Pin JDK/runtime dependencies and improve image provenance metadata.
  • Expand Docker CI selection to cover all distribution inputs.
  • Handle standalone start.sh hardening in a separate PR.

Extra details

This is a compatibility-affecting change. Existing data created by root-based images may require a one-time ownership migration.

The helper defaults to a locally built image because the current official latest image does not meet the new non-root runtime contract. Nile nodes should continue using the Nile-specific repository and tron-docker workflow.

This PR builds and validates images but does not publish them.

@3for 3for changed the title Fix docker only pr feat(docker): modernize and harden the multi-architecture node workflow Aug 26, 2026
@3for
3for force-pushed the fix_docker_only_pr branch 8 times, most recently from 7401335 to 230c45e Compare August 26, 2026 11:06
xxo1shine and others added 8 commits September 11, 2026 14:15
…#6930)

Node and network API responses populated two fields from the wrong source values because of copy-and-paste mapping errors.

Map needSyncFromPeer from the corresponding peer state and assign UDP inbound traffic to the udpInTraffic protobuf field.
…me (tronprotocol#6950)

* chore(deps): upgrade grpc-java from 1.83.0 to 1.83.1

1. bump grpcVersion to 1.83.1 to pick up the upstream fix for
   grpc/grpc-java#12930 (PR grpc/grpc-java#12942), which enforces
   connection.remote().maxActiveStreams(maxStreams) at handler startup
2. drop GrpcNettyMaxConcurrentStreamsLimiter, the local protocol-negotiator
   shim that applied the same limit while 1.83.0 left the remote endpoint
   unbounded until the client acknowledged SETTINGS

* chore(deps): upgrade jackson from 2.18.6 to 2.18.10

bump jackson-databind from 2.18.6 to 2.18.10 to pick up cumulative fixes from the 2.18.x line

* chore(deps): upgrade logback to 1.3.16 and slf4j to 2.0.17

1. bump logback-classic from 1.2.13 to 1.3.16 and slf4j-api,
   jcl-over-slf4j, jul-to-slf4j from 1.7.36 to 2.0.17; logback 1.3
   requires the slf4j 2.0 provider model, and 1.3.16 is the last 1.3.x
   release and the ceiling for the x86_64 JDK 8 build, since 1.5.x
   requires JDK 11
2. rename DelayingShutdownHook to DefaultShutdownHook in the toolkit
   logback.xml; logback 1.3 removed the old class and only auto-maps
   the legacy name with a startup warning
3. drop the CONSOLE appender from the toolkit logback.xml; no logger
   ever referenced it, so it never emitted output on 1.2 either, and
   logback 1.3 now flags it with an unreferenced-appender warning
4. accept one known 1.3.x behavior change: SizeAndTimeBasedRollingPolicy
   now throttles its maxFileSize comparison to once per 60s
   (SimpleInvocationGate) instead of the adaptive ~100-800ms gate of
   1.2.13, so under sustained heavy logging a file can overshoot the
   500MB cap by up to 60s of writes before the %i rollover fires;
   time-based rollover and totalSizeCap/maxHistory cleanup are ungated
   and unaffected
5. note for operators running a custom --log-config file: well-formed
   1.2-era configs using standard elements keep working unchanged
   (jmxConfigurator degrades to an ignored-property warning, the legacy
   shutdown hook name is auto-mapped), and malformed XML still fails
   fast via TronError(LOG_LOAD) exactly as on 1.2; however, a config
   that references an uninstantiable class (e.g. a custom appender
   missing from the classpath) now aborts the whole appender-ref phase
   instead of losing just that one appender, so the node starts with no
   log output while the ERROR statuses are printed to stdout by
   LogService

* chore(deps): upgrade commons-lang3/collections4 and drop commons-math

1. bump commons-lang3 from 3.4 to 3.20.0; the runtime classpath already
   resolved 3.18.0 through libp2p 2.2.9's transitive requirement, so
   align the declaration with what actually ships and move past the
   CVE-2025-48924 range that the nominal 3.4 still sits in
2. bump commons-collections4 from 4.1 to 4.6.0
3. remove commons-math 2.2; no source file imports
   org.apache.commons.math and nothing else in the dependency graph
   requests it

* chore(deps): remove joda-time and use JDK time APIs

1. drop the joda-time 2.3 dependency.
2. replace the six new DateTime(millis) log-formatting call sites in
   DynamicPropertiesStore, DposTask and DposService with a new
   Time.getIsoTimeString helper backed by java.time; its formatter
   (yyyy-MM-dd'T'HH:mm:ss.SSSXXX in the system zone) reproduces joda's
   DateTime.toString() output byte for byte where the JDK and joda 2.3
   time-zone databases agree (UTC nodes are unaffected); zones whose
   rules changed after joda's 2013-era tzdb, e.g. Europe/Moscow, now
   render the corrected offset for the same instant.
3. replace DateTime.now() day arithmetic in four test classes with the
   java.time equivalent, ZonedDateTime.now().minusDays(n)/plusDays(n)
   .toInstant().toEpochMilli(), keeping joda's calendar semantics
   one-to-one, and map plain DateTime.now().getMillis() to
   System.currentTimeMillis()
* feat(api): sanitize HTTP API error responses

Standard HTTP error paths used to expose internal details to clients:
Util.processError prefixed every message with the Java exception class
name, several servlets printed raw Throwable.getMessage() directly, and
the two solidity query endpoints returned bare-text error bodies.

Centralize the client-facing text decision in Util.processError:

* keep the raw non-blank message only for the exact runtime types
  JsonFormat.ParseException, ContractValidateException and
  MaintenanceUnavailableException; a null, empty or whitespace-only
  message falls back to "internal server error"
* preserve the events-deprecation message only for the exact
  IllegalArgumentException type carrying EVENTS_DEPRECATED_MSG
* write the fixed rate-limit and INVALID address messages, along with
  existing GetBlock validation messages, through the package-private
  writeAuditedError helper; these audited callers bypass exception
  classification, and printErrorMsg is private to the shared writer
* return {"Error":"internal server error"} for every other exception,
  with no exception class name

Client-visible changes:

* all processError-based error bodies lose the "class <FQCN> : "
  prefix; unclassified raw messages become "internal server error"
* the rate-limit rejection body becomes
  {"Error":"lack of computing resources"} on every endpoint extending
  RateLimiterServlet, including full-node, solidity and PBFT /jsonrpc
* gettransactionbyid / gettransactioninfobyid on solidity return
  standard {"Error":...} JSON instead of bare text
* validateaddress, getBrokerage and getReward replace leaked library
  messages in their failure branches with existing fixed texts; the
  "INVALID address" body is now written via writeAuditedError and loses
  the space after the colon
* getblock keeps its exact error bodies (refactor only)

Cover Solidity transaction and transaction-info GET/POST input errors,
backend failures, successful lookups and missing records directly with
mocked Wallet calls and in-memory requests and responses. Replace the
transaction servlet tests that accidentally exercised POST in both cases,
changed global stdout and used a shared temporary response file.

Verify both endpoint and global rate-limit rejections across the three
JSON-RPC servlet variants, including status, response body and the absence
of business dispatch on rejection.

HTTP status codes, success responses, request validation rules and
gRPC behavior are unchanged. JSON-RPC behavior is unchanged except for
the shared HTTP rate-limit response described above.

Closes tronprotocol#6936

* fix(api): keep server-side failure logging at error level

The previous commit routed four catch-all blocks through the shared
processError entry point, which logs at debug. Those four catches cover
server-side work only: getburntrx, getnodeinfo and getpendingsize read
no request parameters, and in getreward malformed addresses are already
handled by the preceding DecoderException | IllegalArgumentException
catch. Their failures therefore left no trace under the default log
configuration, where the API topic is INFO.

Add a dedicated processServerError entry point that logs at error and
then applies the same sanitization, and use it at those four call sites.
Logging the exception once inside the helper keeps a single record at
any log level, instead of pairing an error log in the servlet with the
debug log in the shared path.

The shared Exception entry point keeps debug on purpose: its callers
also cover request parsing, so an unauthenticated client can fail it
cheaply and repeatedly, and an unconditional stack trace per request
would amplify that into log pressure. Distinguishing client from server
faults on that path is the parameter/internal split tracked as follow-up
in tronprotocol#6936.

Client-facing responses are unchanged.
Build source-aligned amd64 and arm64 images with a direct non-root FullNode entrypoint. Harden local and remote build contexts, configuration handling, runtime mounts, lifecycle operations, JVM defaults, and deployment guidance.
Add path-aware amd64 and arm64 image builds, remote-source coverage, persistent BuildKit caches, and a fail-closed aggregate gate. Cover Docker helper behavior, image invariants, launcher parsing, lifecycle operations, and build-context filtering.
@3for
3for force-pushed the fix_docker_only_pr branch from 230c45e to 02f7d61 Compare September 18, 2026 09:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants