Skip to content

Fast Start

Use this page when you want the shortest safe path from zero to a working {{ product_name }} operator session. The alpine-admin-cli is a remote gRPC client, so the flow ends the moment you can read live server metadata with an authenticated session.

Before you start

Required baseline

Use Java 25 only. You also need a running alpine-server whose alpine.conf exposes the alpine-admin service with the one-time initialization gate enabled and a private shared secret configured.

Checklist:

  • Java 25 available: java -version
  • A reachable alpine-server is running and exposes the alpine-admin service.
  • In that server's alpine.conf, the admin initialization gate is configured:
    • alpine.services.alpine-admin.initialization.enabled = true
    • alpine.services.alpine-admin.initialization.secret = "<private 32-or-more-byte secret>"
  • You launch every command from your distribution package with bin/admin.sh.

Where the server configuration lives

The initialization gate keys are documented in the Deployment configuration overview and in Reference: alpine.conf. The shipped secret is a development placeholder; override it with a private random value before any real bootstrap.

Bootstrap flow

The five steps below run in order. Step 1 is a pre-OIDC, HMAC-gated bootstrap that needs no login. Steps 2 and 3 are local and write to ${HOME}/.config/alpinepki/. Step 4 is the first command that reaches the live server.

1. Run the one-time bootstrap (init)

This one-time call sets the global administrator OIDC provider on the server. It is authenticated by a JWT signed with the shared initialization secret from alpine.conf, so it does not require a prior login. The issuer and audience identify the OIDC provider the server will trust for administrator tokens.

bin/admin.sh init \
  --oidc-issuer-claim https://idp.example.com/realms/alpine \
  --oidc-audience-claim alpine-admin \
  --init-secret <private 32-or-more-byte secret>

Init notes

  • -i/--oidc-issuer-claim and -a/--oidc-audience-claim are required.
  • --init-secret must match the server's alpine.services.alpine-admin.initialization.secret and be at least 32 bytes. Omit it to be prompted instead of passing it on the command line.
  • The provided secret is wiped from memory after the call completes.

2. Create a host profile (profile hosts create)

The host profile is the local connection record that later server commands target. It is stored under ${HOME}/.config/alpinepki/hosts/. This command is local and needs no login.

bin/admin.sh profile hosts create \
  -n prod-admin \
  --host alpine.example.com \
  --port 5051 \
  --trust-anchors /etc/alpine/ca-bundle.pem

Host profile notes

  • -n/--name is the on-disk key for the profile.
  • --host and --port are required on create. 5051 is the typical gRPC admin port.
  • TLS is on by default; point --trust-anchors at the server CA bundle (PEM). Add --client-cert and --client-key together for mutual TLS.
  • Use --plaintext for development or test endpoints only (it cannot be combined with TLS material).

3. Authenticate (profile authn login)

Log in over OIDC (device-code or PKCE) and store the sealed tokens as a named login on the host profile. The login — its OIDC client config plus the PIN-sealed tokens — is embedded inside the host connection profile under ${HOME}/.config/alpinepki/hosts/. This command is local — it talks to your identity provider, not the {{ product_name }} server.

bin/admin.sh profile authn login \
  -n prod-admin \
  --login admin \
  --oidc-issuer https://idp.example.com/realms/alpine \
  --oidc-client-id alpine-admin-cli \
  --oidc-flow DEVICE_CODE

Login notes

  • -n/--name selects the host profile created in step 2; --login names the login within it.
  • --oidc-issuer and --oidc-client-id are required. --oidc-flow accepts DEVICE_CODE (default) or AUTH_CODE_PKCE.
  • Scopes default to openid,profile,offline_access; keep offline_access to obtain a refresh token. Override with --oidc-scope.
  • You are prompted for a PIN that seals the stored tokens at rest.

4. Run your first read command (server info)

This is the first command that reaches the live server. It confirms the connection, TLS, and your authenticated session in one step by reading the running server's version, git commit, build time, and public key.

bin/admin.sh -p prod-admin server info

Selecting a profile

The global -p/--profile option selects the host profile for a single invocation and is placed before the command path. The default profile name is default-admin. If you named your profile default-admin, you can omit -p.

What to open next

If you need to... Open this page
Configure the server's alpine.conf and overrides Deployment configuration overview
Look up the init gate keys exactly Reference: alpine.conf
Run admin commands after bootstrap Admin CLI overview
Manage host profiles profile hosts
Manage OIDC logins profile authn
Re-read server metadata any time server info

FAQ

Why does init not need a host profile or login?

init is a pre-OIDC bootstrap call. The server gates it with a shared-secret HS256 HMAC interceptor, so the request is authenticated by a JWT signed with the initialization secret rather than an OIDC session. After init succeeds, the administrator logs in normally with profile authn login.

Which commands need a host profile and login first?

Every server-touching command does. The only exceptions are init (HMAC-signed) and the local profile hosts and profile authn commands, which never reach the server.

Where are profiles and logins stored?

Host connection profiles — including their embedded OIDC logins (with PIN-sealed tokens) — are stored under ${HOME}/.config/alpinepki/hosts/.

What is the fastest post-bootstrap validation?

Run bin/admin.sh -p <profile> server info. It exercises the connection, TLS, and your authenticated session and returns the running server's metadata.