// Shared quickstart sections for containers and compose pages (after Initial setup).
// Requires :quickstart: and page-level config attributes on the including page.

[#_slurm_web_secret_keys]
== Slurm-web secret keys

Before starting gateway services, generate two secret files with the
`slurm-web` CLI: a gateway session secret to secure server-side login state
during authentication flows, and a https://jwt.io/[JSON Web Token] (JWT) signing
key for authentication between Slurm-web components. Both files must be stored
in the persistent storage mounted at [.path]#`/var/lib/slurm-web/`# in agent and
gateway containers — see <<_storage_layout,Storage layout>>.

Generate the gateway session secret key (default
[.path]#`/var/lib/slurm-web/session.key`#) with:

:tab-body: partial$quickstart/containers/commands/session-key.adoc
include::partial$quickstart/containers/runtime-tabs.adoc[]

Generate the JWT signing key (default [.path]#`/var/lib/slurm-web/jwt.key`#)
with:

:tab-body: partial$quickstart/containers/commands/jwt-key.adoc
include::partial$quickstart/containers/runtime-tabs.adoc[]

[sidebar]
--
.More links

* xref:overview:architecture.adoc#protocols[Protocols and security] involved in Slurm-web architecture
* xref:usage:manpages/slurm-web-gen-session-key.adoc[`slurm-web gen-session-key` command manpage]
* xref:usage:manpages/slurm-web-gen-jwt-key.adoc[`slurm-web gen-jwt-key` command manpage]
--

[#_slurm_jwt_siging_key]
== Slurm JWT siging key

For Slurm-web authentication to `slurmrestd`, copy the Slurm JWT signing key
into the agent secrets directory as [.path]#`slurmrestd.key`#:

ifeval::["{quickstart}" == "containers"]
[source,console]
----
# cp /var/spool/slurm/jwt_hs256.key /var/lib/slurm-web/slurmrestd.key
----

Restrict access to this sensitive file with read permission to the _slurm-web_
system user only:

[source,console]
----
# chown slurm-web:slurm-web /var/lib/slurm-web/slurmrestd.key
# chmod 400 /var/lib/slurm-web/slurmrestd.key
----
endif::[]

ifeval::["{quickstart}" == "compose"]
[source,console]
----
# cp /var/spool/slurm/jwt_hs256.key ./keys/slurmrestd.key
----

Restrict access to this sensitive file with read permission only:

[source,console]
----
# chmod 400 ./keys/slurmrestd.key
----
endif::[]

NOTE: With this configuration, Slurm-web agent automatically generates its
tokens with short lifespan for authentication to `slurmrestd`. As an
alternative, Slurm-web supports _static_ tokens. Please refer to
xref:conf:slurmrestd.adoc[`slurmrestd` configuration page] for more details.

To test Slurm-web agent and `slurmrestd` service configuration parameters, you
can run
xref:usage:manpages/slurm-web-connect-check.adoc[`slurm-web connect-check`]
command. It tries to send HTTP request to `slurmrestd` with Slurm-web agent
configuration parameters and reports the status. For example:

:tab-body: partial$quickstart/containers/commands/connect-check.adoc
include::partial$quickstart/containers/runtime-tabs.adoc[]

[#_first_access]
== First Access

Slurm-web is now ready to start!

ifeval::["{quickstart}" == "containers"]
Start the _agent_ and _gateway_ containers:
endif::[]

ifeval::["{quickstart}" == "compose"]
Start the stack:
endif::[]

:tab-body: partial$quickstart/containers/commands/first-access.adoc
include::partial$quickstart/containers/runtime-tabs.adoc[]

Connect your browser to the _gateway_ on http://localhost:5011. You should see
the dashboard of the configured cluster:

image:conf:slurm-web_policy_admin.png[]

[NOTE]
====
ifeval::["{quickstart}" == "containers"]
By default, the `docker run` / `podman run` commands above publish the gateway
on port TCP/5011 of the container host. Adjust the `-p` option to expose a
different host port.
endif::[]

ifeval::["{quickstart}" == "compose"]
By default, the reference stack publishes the gateway on port TCP/5011 of the
Compose host. Adjust the `ports:` section in [.path]#`compose.yaml`# to expose a
different host port.
endif::[]

The `[ui] host` value must match the URL used in the browser, including scheme,
host, port and path. Define it in [.path]#`gateway.ini`# when Slurm-web is
exposed on a different public URL:

[source,ini]
----
[ui]
host=http://HOSTNAME_OR_IP:5011
----

Actual values depend on your DNS hostname or the public IP address of the host.

Slurm-web is now available on: http://HOSTNAME_OR_IP:5011

Please refer to
xref:conf:conf/gateway.adoc[gateway configuration reference documentation] for
more details.
====

ifeval::["{quickstart}" == "compose"]
With the reference stack, the agent API is also published on port TCP/5012 of
localhost. The optional Prometheus UI is available at
http://localhost:9090[http://localhost:9090] after
<<_metrics_optional,Metrics>> is configured.
endif::[]

TIP: In case of failure, please refer to
xref:misc:troubleshooting.adoc#containers[troubleshooting guide] for help.

.More details
****
* xref:conf:conf/gateway.adoc[Gateway configuration reference documentation]
****

include::partial$quickstart/going-further.adoc[]
