SmartFarming Deployment (local and staging)

This README describes the steps to deploy the SmartFamring App to the local Docker Desktop (Local environment), and at the same time, to the DockerHub server (Staging environment).

⚠️ Important:
At the time of writing this README, the way to deploy to production isn't determined yet.

Notes

Assumptions

The instructions in this README are intended to be run from a Windows development environment.

Command execution

All commands in this README are executed from the local SmartFarming root folder as base path:

i.e.

cd C:\smartfarming_local_root_folder

DockerHub Server

IP Address: 172.23.3.25

The root folder for SmartFarming on the DockerHub server is:

cd /home/sysadmin/SmartFarming

Folder Structure

The local deployment directory contains following data:

dir C:\smartfarming_root_local_folder\Deployment

smartfarming/
├── ...
├── Deployment/
│ ├── mariadb_init_scripts/
│ ├── staging-area/
│ ├── .gitkeep
│ ├── .gitignore
│ ├── Deploy-SmartFarming.ps1
│ ├── Dockerfile.mariadb
│ └── README_DEPLOY.md
├── ...

mariadb_init_scripts

This folder contains initialization scripts for the docker db container. This folder exists on the local development environment, as well as on the DockerHub server. Both locations are not synced.

staging-area

This folder serves as temporary storage, from which all files, which needs to be transferred to the DockerHub server, will be copied.

How to deploy?

⚠️ Important:

The deployment can only be performed, once the One-Time setup is complete!

Please make sure the One-Time setup (see chapter below), is fullfilled properly.

Run the Deployment Script

.\Deployment\Deploy-SmartFarming.ps1

In short, this script performs:

  • deploy the app to local docker desktop
  • exports the local docker images
  • transfers the exported images to the DockerHub server
  • imports the images on the DockerHub server
  • runs the imported images on the DockerHub server using docker compose up -d (detached mode)

ℹ️ Info: Show console log on DockerHub

In order to run docker compose in attached (foreground) mode to view console log messages...

access the DockerHub server via SSH:

ssh sysadmin@172.23.3.25

Run docker compose in attached (foreground) mode:

docker compose up

ℹ️ Info: Import database dump on local development environment

When setting up the database container locally for the first time, make sure to import a staging database dump so your local database is initialized with the correct data. This is a one-time step and only needed when the local DB container is created initially.

One-Time Setup

ℹ️ Info: In general, the following steps need to be completed only once.

Docker Desktop

Ensure that Docker Desktop is installed and running on your local development environment.

Create a certificate for Https

Please refer to the certificate creation manual.

Prepare environment file .env

The docker-compose.yml file uses placeholders that are replaced with values defined in a .env file.

Within your local SmartFarming root folder:

Copy the example environment file:

copy .env.example .env

Then open .env and fill in the required values.

Example .env for your local development environment

Please adapt as needed to reflect your settings.

MYSQL_ROOT_PASSWORD="root"                  # Root password for the database
MYSQL_DATABASE="SmartFarming"               # Database name (must match the connection string)
MYSQL_USER="biadmin"                        # Database username (must match the connection string)
MYSQL_PASSWORD=""                           # Database user password (must match the connection string)
MYSQL_SERVER="mariadb"						# Service name in docker-compose.yaml

RUN_ENVIRONMENT="Development"               # UI environment (use "Staging" for deployment)
BASE_PUBLIC_URL="https://localhost:9999"    # Base public URL for the UI

UI_HTTP_PORT="5044"                         # HTTP port for the UI (default: 5044)
UI_HTTPS_PORT="9999"                        # HTTPS port for the UI (default: 9999)

Example .env for the staging environment

⚠️ Important:
The .env file for the staging environment already exists on the DockerHub server. Update it only if really required!

vi /home/sysadmin/SmartFarming/.env

Create appsettings.xyz.json for authentication config

The SmartFarming app requires an environment-specific configuration file — e.g. appsettings.Development.json and appsettings.Staging.json — inside the SmartFarmingUI project folder.

Local Development

If not already existing, switch to the SmartFarmingUI directory:

cd .\SmartFarmingUI

... and create a file named appsettings.Development.json with the following content:

{
  "Authentication:Microsoft:ClientSecret": "replace_with_client_secret",
  "Authentication:Microsoft:ClientId": "replace_with_client_id",
  "Authentication:Microsoft:TenantId": "replace_with_tenant_id"
}

⚠️ Important:
The setting-values above are environment-specific and must be provided by your supervisor. The development and staging environments use different values.

Staging Environment (DockerHub server)

If not already existing, switch to the SmartFarmingUI directory:

cd .\SmartFarmingUI

...and create a file named appsettings.Staging.json with the following content:

{
  "Authentication:Microsoft:ClientSecret": "replace_with_client_secret",
  "Authentication:Microsoft:ClientId": "replace_with_client_id",
  "Authentication:Microsoft:TenantId": "replace_with_tenant_id"
}

⚠️ Important:
The setting-values above are environment-specific and must be provided by your supervisor. The development and staging environments use different values.

Set up passwordless SSH Login to the DockerHub server

The deployment script connects to the DockerHub server via SSH. To avoid entering your password multiple times, it’s recommended to set up passwordless SSH authentication to the server:

Generate an SSH key (if not already existing)

Run the following on your local development machine:

ssh-keygen -t rsa -b 4096 -C "bi-it@espas.ch"

Press Enter to accept the default location (~/.ssh/id_rsa).

Optionally, leave the passphrase empty or define one.

Copy your public key to clipboard for next step:

Get-Content $env:USERPROFILE\.ssh\id_rsa.pub | Set-Clipboard

Copy the public key to the DockerHub server (manually)

Connect to the DockerHub server:

ssh sysadmin@172.23.3.25

On the server, execute:

mkdir -p ~/.ssh
nano ~/.ssh/authorized_keys

Paste your public key into the authorized_keys file and save it.

Helpful commands during script development

Docker Administration

# List running containers managed by Docker Compose
docker compose ps

# Stop and remove containers, networks, and resources created by Docker Compose
docker compose down

# Start services defined in docker-compose.yml (creates containers if needed)
docker compose up

# Start services in detached mode (runs in the background)
docker compose up -d

# Remove all unused images (dangling + unreferenced)
docker image prune -a

# List all Docker volumes on the host
docker volume ls

# Remove a specific Docker volume (e.g. "mydata")
docker volume rm mydata

# Remove all unused Docker volumes
docker volume prune

Docker Development

# Install the ping utility inside a container for debugging
apt update && apt install iputils-ping -y

# Check if MySQL is running in the container
docker exec -it mariadb /bin/bash
netstat -tuln | grep 3306

# Open a bash shell inside the UI container
docker exec -it smartfarming_ui /bin/bash
Edit this page