Install Echo Pro

Before you start

Use this page before your first go get, and when you set up CI, Docker or an offline build.

Install echo.labstack.com/pro v0.2.0 through go.labstack.io. You need Go 1.26 or later, an application module and an organisation download token. The module requires Echo v5.4.2. You do not need access to a private Git repository. The token only authenticates module downloads. Your application never checks it at run time.

Set up local development

1. Open your .netrc file in an editor. On Unix it is ~/.netrc; Windows uses %USERPROFILE%\_netrc. Add the entry below. Replace the organisation slug and token with your own. Keep the value in your credential manager and out of source control, shell history and logs.

machine go.labstack.io login <org> password <token>

2. Restrict the Unix file to its owner:

chmod 600 "$HOME/.netrc"

3. Configure the private module pattern, then install and verify the pinned version from your application module:

go env -w GOPRIVATE=echo.labstack.com
go get echo.labstack.com/[email protected]
go mod verify

If you already have GOPRIVATE patterns, append echo.labstack.com to that comma-separated list instead of replacing it. The pattern must include the bare host. If you set GONOSUMDB or GONOPROXY yourself, append to those lists too.

Go fetches https://echo.labstack.com/pro?go-get=1 and discovers the module proxy at https://go.labstack.io. Put the credentials on the go.labstack.io machine entry. A .netrc entry for echo.labstack.com alone does not authenticate downloads. GOPRIVATE bypasses the public proxy and checksum database for matching modules. Public dependencies continue through their normal public services.

go get writes the version to go.mod and its hashes to go.sum. go mod verify reports all modules verified when the downloaded cache matches its recorded hashes. Commit both module files. Next, run the getting-started tutorial.

Use a corporate module mirror

Configure go.labstack.io as an authenticated upstream of your corporate mirror. Store the registry token in the mirror’s upstream configuration. Use the mirror as the Go proxy:

go env -w GOPROXY=https://mirror.corp.example/go GONOSUMDB=echo.labstack.com GONOPROXY=none

Set GONOPROXY=none. Without it, GOPRIVATE makes Go skip the mirror for Pro. GONOSUMDB=echo.labstack.com excludes Pro from the public checksum database. Preserve your organisation’s other private patterns.

If GOPROXY lists a public proxy before go.labstack.io, Go sends the Pro module path and version to that public proxy. Go advances a comma-separated proxy chain on 404 or 410. A 401 or 403 means the token is missing, invalid or not entitled. Fix the token; do not add a public proxy as a fallback. To keep module names private, use direct discovery or your approved mirror.

Configure GitHub Actions

Store a customer registry token as the repository or environment secret ECHO_PRO_TOKEN. The workflow writes a temporary netrc with mode 600. It turns off module caching. It downloads and verifies modules, then tests and builds the application. An always-run step removes the credential. The workflow pins each Action to a full commit SHA and uses Go 1.27.3.

name: Application checks
on: [push, pull_request]
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-26.04
    env:
      GOPRIVATE: echo.labstack.com
      GONOPROXY: echo.labstack.com
      GONOSUMDB: echo.labstack.com
    steps:
      # https://github.com/actions/checkout/commit/3d3c42e5aac5ba805825da76410c181273ba90b1
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      # https://github.com/actions/setup-go/commit/b7ad1dad31e06c5925ef5d2fc7ad053ef454303e
      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          go-version: '1.27.3'
          cache: false
      - name: Configure registry credential
        env:
          ECHO_PRO_TOKEN: ${{ secrets.ECHO_PRO_TOKEN }}
          NETRC: ${{ runner.temp }}/echo-pro.netrc
        run: |
          set +x
          umask 077
          printf 'machine go.labstack.io login ci password %s\n' "$ECHO_PRO_TOKEN" > "$NETRC"
      - name: Download and test
        env:
          NETRC: ${{ runner.temp }}/echo-pro.netrc
        run: |
          go mod download
          go mod verify
          go test ./...
          go build ./...
      - name: Remove registry credential
        if: always()
        env:
          NETRC: ${{ runner.temp }}/echo-pro.netrc
        run: rm -f "$NETRC"

Save the workflow in your application’s workflow directory. Before you enable the job, commit go.mod (pinned to v0.2.0) and go.sum. Run this job only for trusted code. Any step in the job can read the secret. Fork pull requests do not receive repository secrets by default. Run checks for fork pull requests in a separate workflow that has no secret. If you turn on module caching later, restrict the cache to licensed users.

NETRC points Go at the temporary credential file. The token appears only in the credential-setup step’s environment. That step turns off shell tracing before it writes the file. The cleanup step runs even when the download fails. When you copy the workflow, update the Action pins under your own update policy.

Build an application image with Docker

Use a BuildKit-capable Docker builder. The Dockerfile builds ./cmd/server, which your application supplies. Echo Pro does not ship that command. Change the path to your main package. The download step mounts the netrc as a secret. The build step runs without network access.

FROM golang:1.27.3 AS build
WORKDIR /app
ENV GOPRIVATE=echo.labstack.com GONOPROXY=echo.labstack.com GONOSUMDB=echo.labstack.com CGO_ENABLED=0
COPY go.mod go.sum ./
RUN --mount=type=secret,id=netrc,target=/root/.netrc,required=true go mod download
COPY . .
RUN --network=none go build -mod=readonly -o /out/server ./cmd/server

FROM scratch
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=build /out/server /server
USER 65532:65532
ENTRYPOINT ["/server"]

Pass the credential as a build secret:

docker build --secret id=netrc,src="$HOME/.netrc" -t invoice-api:v0.2.0 .

Keep .netrc outside the build context. List local credential and config files in .dockerignore. Never pass the token as a build argument, environment instruction or copied file. The final image contains the static binary and CA certificates. Pass runtime secrets to the container when it starts, not during the build. Copy time-zone data too if your application loads named time zones at runtime. Pin the builder image to a reviewed digest in your application’s image-update process.

The Dockerfile is an application build template. Echo Pro’s documentation tests validate this file and its credential handling. Your own build still needs an entitled token, and you must test it.

Build without registry access

On a machine with registry access, vendor the dependencies. Move the source and vendor directory to the offline builder through your approved private channel:

go mod vendor
go test -mod=vendor ./...
go build -mod=vendor ./...

The vendor tree contains commercial source. Apply the same access controls as the module cache. Keep go.mod and go.sum with it. An air-gapped build cannot fetch missing dependencies. Test the transferred tree with network access disabled.

Diagnose 401 and 403

Probe the exact pinned metadata URL without printing the credential or response body:

curl --silent --show-error --netrc-file "$HOME/.netrc" --output /dev/null --write-out '%{http_code}\n' \
  https://go.labstack.io/echo.labstack.com/pro/@v/v0.2.0.info

A 200 confirms that this credential can read v0.2.0 metadata. A 401 means missing or invalid credentials. Check four things: the machine name is go.labstack.io; password holds the token; Go reads the netrc you expect (NETRC or your home directory); the token is not revoked. The registry ignores login and checks only password. A wrong slug does not cause 401. Do not put the token in a URL or paste it into diagnostics.

A 403 means the token is valid, but your organisation is not entitled to that version. Check the version you requested. Then ask support to check your organisation’s status. After a subscription lapses, the token can still download versions you were entitled to. A revoked organisation gets 403. Clearing the module cache or turning off checksums does not fix a 403.

Check checksum settings

Print these settings locally. Remove credentials before you share the output:

go env GOPROXY GOPRIVATE GONOPROXY GONOSUMDB GOSUMDB GOFLAGS GOAUTH
go list -m echo.labstack.com/pro

If Go contacts sum.golang.org for Pro, check the effective GONOSUMDB and GOPRIVATE patterns. An explicit GONOSUMDB overrides the default inherited from GOPRIVATE. Exclude only echo.labstack.com, so public modules still use the checksum database.

Verify a checksum mismatch

Keep existing go.sum hashes. On a checksum mismatch, verify the download with the release manifest and the public signing key from onboarding. Do not delete the go.sum line to make the build pass.

Update module files

-mod=readonly has been the default for builds since Go 1.16 when vendoring is not selected. It rejects builds that need to update go.mod. Use go get for an intentional dependency update, then review go.mod and go.sum. go get has no -mod flag, and it ignores -mod in GOFLAGS.

Refresh vendor files

GOFLAGS=-mod=vendor makes builds and tests use the vendor tree. A new import fails until you run go mod vendor again. In the Dockerfile, the download step must fetch every dependency, because the build step is offline.

Check proxy routing

If a corporate proxy is unexpectedly bypassed, inspect GONOPROXY.

Check registry credentials

If Go sends no credentials to the registry, check GOAUTH and the NETRC path. Do not print a proxy URL containing credentials into CI logs.