The /.well-known/ directory is a standardized location defined by RFC 8615.
It is used to host configuration files and metadata that allow external services (such as mobile app linking, authentication, or security policies) to integrate with the application.

This guide explains how to configure the PWA to serve files from the /.well-known/ directory at the root of a web server.

Apple App Site Association

The AASA (short for apple-app-site-association) is a file that lives on your website and associates your website domain with your native app (see What Is An AASA (apple-app-site-association) File?).

A detailed guide on how to create the apple-app-site-association file can be found at Apple Developer: Supporting Associated Domains.

How to configure the PWA to serve the AASA file

Save the AASA File

Place the file apple-app-site-association in the nginx folder.

Dockerfile Adaption

Add the following lines to nginx/Dockerfile:

RUN mkdir -p /usr/share/nginx/html/.well-known
COPY apple-app-site-association /usr/share/nginx/html/.well-known/apple-app-site-association

Multi-Channel Configuration

Add the following location block to the nginx/templates/multi-channel.conf.tmpl file within the server block and next to the existing location blocks:

# apple-app-site-association
location = /.well-known/apple-app-site-association {
    allow all;
    auth_basic off;

    default_type application/json;
    root /usr/share/nginx/html;
}

Verify the Configuration

Test the endpoint after deployment:

curl -i https://yourdomain.com/.well-known/apple-app-site-association

The endpoint should return Content-Type: application/json with the JSON content.

To test the apple-app-site-association file when running the PWA on your local system, you can use the following commands:

docker compose up --build -d
curl -i http://localhost:4200/.well-known/apple-app-site-association

Further References

• RFC 8615: Well-Known Uniform Resource Identifiers (URIs)
• Apple Developer: Supporting Associated Domains