Docker

Deploy FoxIDs in Docker Desktop on a dev or test machine.

This is a description of how to make a default deployment and log in for the first time.

Pre requirements:

  • You have Docker Desktop installed.
  • You have basic knowledge about Docker.

This is a list of useful commands in the end of this description.

This deployment include:

  • Two websites one for FoxIDs and one for the FoxIDs Control (Client and API) in two docker images foxids/foxids and foxids/foxids-control or generated from code with Dockerfile files.
  • The two websites is exposed on two different ports.
  • MongoDB is a NoSQL database and contains all data including tenants, environments and users. Deployed with the official MongoDB Docker image.
  • Redis cache holds sequences (e.g., login and logout), data cache to improve performance and handle counters to secure authentication against various attacks. Deployed with the official Redis Docker image.
  • Logs are written to stdout where the logs can be picked up by Docker.

Optionally use PostgreSql instead of MongoDB and optionally opt out Redis and save cache data in the database (MongoDB or PostgreSql). Without a Redis cache you need to select None as data cache.

Deployment

The deployment is carried out in the described order.

Get ready

Clone the git repository or download as ZIP. The Docker yaml configuration files is in the ./Docker folder.
Open a console and navigate to the ./Docker folder.

Volume

You need a volume for MongoDB with the name foxids-data where data is saved.

Either create a volume for MongoDB on your Windows host file system in e.g., the folder C:\data\foxids-data. Important: create the folders before running the command.

docker volume create --driver local --opt type=none --opt device=C:\data\foxids-data --opt o=bind foxids-data

OR, create a volume for MongoDB which is managed by Docker.

docker volume create foxids-data

Deploy containers

The two FoxIDs websites is configured with either images from Docker Hub or images generated from code with Dockerfile files. And optional configured to use either only HTTP or both HTTP/HTTPS with a development certificate.
The official MongoDB and Redis images is pulled from Docker Hub.

Email provider
You can optionally configure a global email provider or later configure email providers per environment. FoxIDs supports sending emails with SendGrid and SMTP.

The global email provider is configured in the docker-compose-image.yaml or the docker-compose-project.yaml file on the foxids service in the environment: section.
This example show how to add Outlook / Microsoft 365 with SMTP:

- name: "Settings__Smtp__FromEmail"
    value: "[email protected]"
- name: "Settings__Smtp__FromName" # Optional from name associated to the email address 
    value: "e.g, my company name"
- name: "Settings__Smtp__Host"
    value: "smtp.office365.com"
- name: "Settings__Smtp__Port"
    value: "587"
- name: "Settings__Smtp__Username"
    value: "[email protected]"
- name: "Settings__Smtp__Password"
    value: "xxxxxxx"

Deploy
Create the deployment, select one of the three following ways:

  1. All based on images from Docker Hub and with HTTP
docker-compose -f docker-compose-image.yaml -f docker-compose.development-http.yaml up -d
  1. Partial based on images generated from code with Dockerfile files and with HTTP
docker-compose -f docker-compose-project.yaml -f docker-compose.development-http.yaml up -d
  1. Partial based on images generated from code with Dockerfile files and with HTTP/HTTPS - require the development certificate to be present.
docker-compose -f docker-compose-project.yaml -f docker-compose.development-https.yaml up -d

First login

Open your FoxIDs Control site (http://localhost:8801 or https://localhost:8401) in a browser. It should redirect to the FoxIDs site where you login with the default admin user [email protected] and password FirstAccess! (you are required to change the password on first login).
You are then redirected back to the FoxIDs Control site in the master tenant. You can add more tenants in the master tenant and e.g., configure admin users.

Then click on the main tenant and authenticate once again with the same default admin user email and password (the default admin user email and password is the same for both the master tenant and the main tenant, but it is two different users).
You are now logged into the main tenant and can start to configure your applications and authentication methods.

Useful commands

This is a list of commands which may be useful during deployment to view details and to make deployment changes.

Tear down the deployment

docker-compose -f docker-compose-image.yaml -f docker-compose.development-http.yaml down
# or
docker-compose -f docker-compose-project.yaml -f docker-compose.development-http.yaml down
# or
docker-compose -f docker-compose-project.yaml -f docker-compose.development-https.yaml down

Build image with Dockerfile file

docker build -f ./src/foxids/Dockerfile . -t foxids:x.x.x    # x.x.x is the version
# or
docker build -f ./src/foxids.control/Dockerfile . -t foxids-control:x.x.x    # x.x.x is the version

Stop container

docker stop xxx

Remove container

docker rm xxx

Remove image

docker rmi xxx

List volumes

docker volume ls

Remove volume

docker volume rm xxx

Remove all unused volumes

docker volume prune

Show logs in container

Docker logs xxx