If you already have a working IdentityServer installation up and running then this walkthrough is for you.
This walkthrough will take you through the entire Docker configuration process, resulting in a working environment for the IdentityExpress AdminUI, with the UI and backend API running on the same machine and targeting an existing IdentityServer. This will also include migrating your user store to the AdminUI Identity Schema.
This walkthrough will assume you already have Docker installed on your machine.
Before beginning the installation, ensure Docker is configured as per the [Docker prerequisites] instructions.
Getting the Docker Compose File
For most basic installations, we can use the Docker Compose file made available upon purchase. This would have been emailed to you after payment or at the start of your trial.
Configuring the Docker Compose File
There are multiple variables that you can configure in the compose file depending on your setup:
We can configure both the internal and external ports used in the docker containers. This is in the format of
host:container. Please do not change the container port when using the compose file, however you are welcome to change the host port if your environment has any port clashes.
Environment variables are also available for setting application specifics. These are set in the following format in your Docker Compose file:
environment: - UiUrl=http://localhost:5000 - ApiUrl=http://localhost:5001 - AuthorityUrl=http://ids:5003
api container we have:
DbProviderThis sets the database type you are using. Supported types and their values are:
IdentityConnectionStringThe connection string for your Identity database (users)
IdentityServerConnectionStringThe connection string for your IdentityServer database (clients, resources & grants)
AuthorityUrlUrl of the IdentityServer installation protecting the UI
UiUrlUrl of the AdminUI frontend (the idxui container)
falseif you want to ensure IdentityServer discovery endpoint uses TLS. Must be
falseif you require AdminUI to run Entity Framework migrations for ASP.NET Identity DbContext's. This is recommended.
falseif you require AdminUI to run Entity Framework migrations for IdentityServer DbContext's. This is useful if you have a new instance of IdentityServer currently without databases.
IdentityDatabaseToMigrateConnectionString(optional) The connection string of your existing ASP.NET Core Identity Entity Framework database that will be migrated to the database used in
IdentityConnectionString(this must not be equal to
And for the
ui container we have:
AuthorityUrlUrl of the IdentityServer installation protecting AdminUI
ApiUrlUrl of the AdminUI backend (the idxapi container)
UiUrlUrl of the AdminUI frontend (the idxui container)
IdentityServer & Database Resolution
Ensure that your IdentityServer site is either: Publicly resolvable via DNS or running locally on the Docker host machine on all network devices (e.g: http://+:5555/). If you are running locally, ensure that the
AuthorityUrl setting uses the IP address of the local Docker network device.
Any used databases must accept remote connections. If this database is on your Docker host machine, you can use the IP address of your Docker network device in the connection string.
If you are running IdentityServer and the database locally to the Docker host machine, also ensure that your firewall allows connections on the necessary ports.
Before we run the containers we have one final step: authentication.
The docker images used for Admin UI are found in a private Docker registry, which is protected by a username and password. These credentials are supplied when you purchase AdminUI.
Once you have the credentials you run:
`docker login identityserverregistry.azurecr.io
The first time you run AdminUI, it will automatically migrate your user store to the AdminUI schema to a new database. This is a non destructive operation.
The first run will also extend your existing IdentityServer database with new tables and create Client and Resource entries for the AdminUI site.
For more details on the migration process, including how and when it runs, check out the Integrating with IdentityServer documentation.
Now we can run the Docker Compose file using the command:
This must be done in the location of the Docker Compose file or by providing the path using
You should now be able to access the IdentityExpress Admin UI on
If you have any issues with the installation process, please check our Frequently Asked Questions.
Otherwise, if this doesn't help, feel free to contact our support desk at [email protected]
Deploying Docker Images Separately
The Admin UI and API Docker images are designed to be scaled separately. This means you can place each image on separate machines each with their own load balancing policies.
Individual Docker Compose files are not available for the UI and API, however you can easily create these with a bit of Docker know-how, or use the docker run command directly.
docker run identityserverregistry.azurecr.io/idxui
This will run the UI image alone. A similar approach can then be taken with the API image, where the image is tagged
Ports used can then be set as
-p 5000:5000 and environment variables as
Making Docker Public with a Reverse Proxy
To make the Docker containers public, we first need to add a web server to the mix. This web server will act as a reverse proxy, forwarding all calls to our running Docker instances. These web servers do not need to dockerized.
IIS Reverse Proxy
To setup IIS to act as a reverse proxy, there are two prerequisites that need to be installed within IIS:
- URL Rewrite Module
- Application Request Routing
Once these are installed we can then go to the site we want to configure and select 'URL Rewrite' found in the IIS section.
We then need to use "Add Rule(s)...", found in the Actions section.
We can then use the Reverse proxy template, found in the Inbound and Outbound Rules section.
Now we need to set the Inbound Rule, telling IIS where to forward requests to. By default this would be http://localhost:5000. If your Docker container is running HTTPS, ensure you disable SSL Offloading, ensuring TLS is maintained.
We also need to configure an Outbound Rule, to allow IIS to return responses from our Docker container using your site URL instead of the Docker container responding directly. Here the From address needs to be the domain of you Docker container (e.g. http://localhost:5000) and the To address you sites address (e.g. api.docker.com).
Nginx Reverse Proxy
Running Docker Commands on Linux
If you're running Docker on a Linux host and you're having issues running these commands, check you have suitable permissions.