# Install and deploy native HTTP

[العربية](deployment.ar.md) · [Runnable guide](guide.en.md) · [Reference](reference.en.md)

## Install the selected tool

ASPL 0.5.0 is staged locally. Do not substitute the public 0.4.0 archive for
these examples. Contributors prepare the controlled release with
`make native-http-release`, `make distribution-current`, and
`make verify-distribution-current`. See [packaging](../http-native-packaging.md)
for the pinned glibc 2.34 build. Copy its immutable archive/checksum inputs to a working directory:

```sh
mkdir -p build/http-install
cp build/distribution/0.5.0/aspl-0.5.0-x86_64-linux-gnu.tar.xz build/distribution/0.5.0/SHA256SUMS build/http-install/
cd build/http-install
sha256sum --check SHA256SUMS
tar -tvJf aspl-0.5.0-x86_64-linux-gnu.tar.xz
tar -xJf aspl-0.5.0-x86_64-linux-gnu.tar.xz
./aspl-0.5.0-x86_64-linux-gnu/aspl --version
```

Require a passing checksum and `aspl 0.5.0`. SHA-256 checks integrity, not
publisher identity. Install the extracted tool in your user bin directory and select it on PATH:

```sh
install -d "$HOME/.local/bin"
install -m 0755 ./aspl-0.5.0-x86_64-linux-gnu/aspl "$HOME/.local/bin/aspl"
export PATH="$HOME/.local/bin:$PATH"
aspl --version
```

The archive contains the tool, `DEPENDENCIES.json`, both
ASPL licenses and complete incorporated notices. A clean installation already
contains supplied declarations and prepared core/HTTP templates with private
static native dependencies. There is no separate HTTP package or backend install.
The supported target is baseline x86-64 Linux, glibc 2.34 or later, with loader
`/lib64/ld-linux-x86-64.so.2`, `libc.so.6` and `libm.so.6`.

`check` and `build` are offline and do not load application foreign libraries,
start networking, or invoke a C compiler/assembler/linker. Any HTTP import in
the module graph selects the HTTP template, even unused. A graph without HTTP
uses the core template. Native HTTP initialization waits for an actual operation.
Generated executables need no ASPL or source modules after relocation. They
still need application certificate/key/private-CA files and declared foreign
shared libraries. Relative file paths resolve from the process working directory.

## Trust and failure timing

Default trust is discovered at first HTTPS use, before connecting. Select the
first existing file in this order:

1. `/etc/ssl/certs/ca-certificates.crt`
2. `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem`
3. `/etc/ssl/cert.pem`
4. `/etc/pki/tls/certs/ca-bundle.crt`
5. `/etc/ssl/certs/ca-bundle.crt`

When all five are absent, scan `/etc/ssl/certs/` in byte-name order. Parse regular
files and symlinks to regular files, deduplicating resolved device/inode pairs.
Ignore nonregular entries. An existing unusable selected store returns
`http.ca_load_failed`; it does not fall through to another store. Environment
variables such as `SSL_CERT_FILE` do not override discovery. A private PEM CA
file selected through `use_private_ca=true` replaces this search. False requires
an empty `ca_file`. Successful parsed trust is pinned for the execution; file
changes require a new execution. Missing trust does not affect checking,
building, nonnetworked execution or plain HTTP.

HTTPS requires TLS 1.2 or 1.3, chain/date verification and matching DNS/IP SANs.
A Common Name does not establish identity. DNS wildcards cover one leftmost
label. IP addresses require matching binary IP SANs. Repair CA availability,
certificate dates, chain or URL/SAN mismatch; never disable verification.
See [the TLS input bounds](reference.en.md#tls-inputs) for supported keys and limits.

## Direct TLS

For a local exercise, generate an unencrypted RSA key and a short-lived
self-signed CA/certificate with the required local SANs. Run from the repository
root, which is the examples' working directory:

```sh
openssl req -x509 -newkey rsa:2048 -nodes -days 2 \
  -subj /CN=localhost -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1' \
  -keyout server.key -out server.pem
chmod 600 server.key
aspl check docs/examples/http/en/direct-tls.aspl
aspl build -o build/http-guide/tls-service docs/examples/http/en/direct-tls.aspl
./build/http-guide/tls-service
```

Create `build/http-guide` first if it does not exist. The HTTPS client in the
guide explicitly trusts this certificate. In deployment, use your application's
PEM certificate chain and matching unencrypted private key. Keep the key readable
only by the service account. ASPL loads both at startup, checks their match,
and does not reload them. Restart with renewed files. Each listener has one
chain/key; hostname certificate selection and client certificates are excluded.

Startup is all-or-nothing. Bad files use `http.tls_config_failed`; resolution,
binding and listening failures use their respective stable codes. Earlier
listeners and allocations are rolled back before `serve` returns failure.
Correct the configuration and start a new execution. Even failed startup freezes
runtime configuration and consumes that execution's one serving invocation.
Port zero is invalid. IPv6 listeners are IPv6-only; configure separate IPv4/IPv6
listeners for explicit dual-stack service.

## Plain HTTP behind a reverse proxy

Run the plain service on loopback 8080. Configure your reverse proxy to terminate
TLS with its certificate/key and send HTTP/1.1 requests to `127.0.0.1:8080`.
For an existing nginx deployment, the location can use:

```nginx
location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Connection "";
}
```

Configure the public TLS listener and certificates in the proxy separately.
ASPL sees a plain connection from the proxy. Forwarded scheme/address headers
remain ordinary application data and do not change routing, authority or TLS
metadata. Define your application's proxy trust policy before using them for
security decisions. The `/stop` route is an exercise endpoint; restrict it in
an application deployment.

## Migration and unsupported profiles

ASPL 0.5.0 intentionally changes source and private bytecode to version 5.
Replace `==` with `matches` or `match`, `!=` with `not matches` or `not match`,
and unary `!` with `not`. Arabic equality is `يطابق` or `تطابق`, negation is
`لا`, `ليس` or `ليست`; use `ليس يطابق` for inequality. Keep word `and` / `و`
and `or` / `أو`. Former symbols and user declarations of newly reserved aliases
receive source diagnostics. Check every module, rename conflicting user names,
and rebuild from source. Version-4 bytecode is rejected with rebuild guidance;
bytecode is a private format. Previously generated executables retain their old
runtime and do not acquire HTTP support by installing a new tool.

The browser playground and private embedding API report
`unsupported-supplied-library-profile` for an HTTP import, including an unused
one, before source effects. Independently admitted bytecode also rejects HTTP
catalog/types in those profiles. Use the native CLI or Console with the selected
0.5.0 native executable. These are separate from APL app data requests.

## Evidence and release preparation

Current native proof records cover [ownership](../http-native-ownership.md),
[bounded DNS/TLS/gzip](../http-native-bounds.md),
[managed lifecycle](../http-native-lifecycle.md) and
[controlled packaging](../http-native-packaging.md). Historical OpenSSL and
component prototypes contain failures and scoped samples; they do not describe
the current Mbed TLS implementation or establish all-path bounds. The 10 ms
poll/wake value is a responsiveness target, not a hard real-time guarantee.
The common HTTP cleanup deadline defaults to 1000 ms and cannot be set lower.
Successful samples are not all-host maximum guarantees.

Ticket 18 remains responsible for final aggregate verification before declaring
the implementation complete. Stage the website from immutable versioned release
inputs using [the website workflow](../../projects/website/README.md). Keep
existing locale/playground/download routes and historical version bytes. This
documentation work does not deploy, publish, retag or recommend a release.