These are some of the required steps, tips, and tricks when it comes to running an app on a local machine. The primary goal is to be able to iterate over changes and verifying them without needing to deploy the app to the test environment.
- Prerequisites
- Setup
- Changing configuration
- Multiple apps at the same time (running LocalTest locally)
- Changing test data
- Known issues
- Newest .NET 6 SDK
- Newest Git
- A code editor - we like Visual Studio Code
- Also install recommended extensions ( f.ex. C#)
- Podman Desktop/Podman (Linux users can also use native Docker) or Docker Desktop (Windows and Mac) This might require you to purchase a license. On mac with apple silicone (M1, M2, M3):
- vfkit
git clone https://github.com/Altinn/app-localtest
cd app-localtestThis mode supports running one app at a time. If you need to run multiple apps at once, stop the localtest container with podman stop localtest and follow the instructions below to run LocalTest locally outside Docker/Podman.
Important
If you are using an mac with either a M1, M2 or M3 chip you may need to use applehv instead of qemu as the podman machine driver.
This can be done by setting the environment variable CONTAINERS_MACHINE_PROVIDER to applehv before running the command below.
To add this to your zsh profile run the following command: echo "export CONTAINERS_MACHINE_PROVIDER=applehv" >> ~/.zprofile
If you are using Podman Desktop you also need to add these lines in ~/.config/containers/containers.conf (check if the [machine] section already exists):
[machine]
provider = "applehv"
Start the containers with the following command:
podman compose --file podman-compose.yml up -d --buildOptionally, if you want access to Grafana and a local monitoring setup based on OpenTelemetry:
podman compose --file podman-compose.yml --profile "monitoring" up -d --build
# Grafana should be available at http://local.altinn.cloud:8000/grafana
# Remember to enable the 'UseOpenTelemetry' configuration flag in the appsettings.json of the appNote
If you are using linux or mac you can use the Makefile to build and run the containers.
make podman-start-localtest
Important
Are you running podman version < 4.7.0 you need to use the following command instead:
podman-compose --file podman-compose.yml up -d --build
or the make command:
make podman-compose-start-localtest
Localtest should now be runningn on port 8000 and can be accessed on http://local.altinn.cloud:8000.
This mode supports running one app at a time. If you need to run multiple apps at once, stop the localtest container with docker stop localtest and follow the instructions below to run LocalTest locally outside Docker.
docker compose up -d --buildOptionally, if you want access to Grafana and a local monitoring setup based on OpenTelemetry:
docker compose --profile "monitoring" up -d --build
# Grafana should be available at http://local.altinn.cloud/grafana
# Remember to enable the 'UseOpenTelemetry' configuration flag in the appsettings.json of the appNote
If you are using linux or mac you can use the Makefile to build and run the containers.
make docker-start-localtest
Localtest should now be runningn on port 80 and can be accessed on http://local.altinn.cloud:80.
There is a preview helper script that will execute the correct commands in a cross-platform way. Either docker or podman must be installed.
./run.cmdOptionally, if you want access to Grafana and a local monitoring setup based on OpenTelemetry:
./run.cmd -mIf the localtest setup is already running, it will restart.
To stop localtest
./run.cmd stopThis step requires that you have already created an app, added a data model, and cloned the app to your local environment.
Move into the App folder of your application.
Example: If your application is named my-awesome-app and is located in the folder C:\my_applications, run the following command:
cd C:\my_applications\my-awasome-app\AppRun the application:
dotnet runThe app and local platform services are now running locally. The app can be accessed on http://local.altinn.cloud.
Log in with a test user, using your app name and org name. This will redirect you to the app.
The Docker Compose config can be changed with local environment variables. There is a
template file for the .env file here, rename it to .env and
uncomment some variables that you want different values for.
Sometimes the local environment have another service running on port 80, so you might need to change this.
ALTINN3LOCAL_PORT=80If you want to see the storage files on disk (instead of reading them through the browser), change this to a local path on your computer (ensure that it exists)
ALTINN3LOCALSTORAGE_PATH=C:/AltinnPlatformLocal/If you want to use another domain than local.altinn.cloud for local testing you could do that this way:
TEST_DOMAIN=local.altinn.cloudThe setup described above (LocalTest running in Docker) currently only supports one app at a time. If you find yourself needing to run multiple apps at the same time, or if you need to debug or develop LocalTest, a local setup is preferred.
ℹ️ If you're already running LocalTest in Docker, be sure to stop the container with docker stop localtest
Configuration of LocalTest The LocalTest application acts as an emulator of the Altinn 3 platform services. It provides things like authentication, authorization and storage. Everything your apps will need to run locally.
Settings (under LocalPlatformSettings):
LocalAppMode- (defaultfile) If set tohttp, LocalTest will find the active app configuration and policy.xml using apis exposed onLocalAppUrl. (note that this is a new setting needs to be added manually underLocalPlatformSettings, it might also require updates to altinn dependencies for your apps in order to support this functionality)LocalAppUrl- IfLocalAppMode=="http", this URL will be used instead ofAppRepositoryBasePathto find apps and their files. Typically the value will be"http://localhost:5005"LocalTestingStorageBasePath- The folder to which LocalTest will store instances and data being created during testing.AppRepositoryBasePath- The folder where LocalTest will look for apps and their files ifLocalAppMode=="file". This is typically the parent directory where you checkout all your apps.LocalTestingStaticTestDataPath- Test user data like profile, register and roles. (<path to altinn-studio repo>/testdata/)
The recommended way of changing settings for LocalTest is through
user-secrets.
User secrets is a set of developer specific settings that will overwrite values from the appsettings.json file when
the application is started in developer "mode". The alternative is to edit the appsettings.json file directly. Just be
careful not to commit developer specific changes back to the repository.
- Define a user secret with the following command: (make sure you are in the LocalTest folder)
Run the command for each setting you want to change.
dotnet user-secrets set "LocalPlatformSettings:AppRepositoryBasePath" "C:\Repos"
- Alternatively edit the appsettings.json file directly:
- Open
appsettings.jsonin theLocalTestfolder in an editor, for example in Visual Studio Code - Change the setting
"AppRepsitoryBasePath"to the full path to your app on the disk. - Change other settings as needed.
- Save the file.
- Open
Finally, start the local platform services (make sure you are in the /src folder)
cd /src
dotnet runIn some cases your application might differ from the default setup and require custom changes to the test data available. This section contains the most common changes.
This would be required if your app requires a role which none of the test users have.
- Identify the role list you need to modify by noting the userId of the user representing an entity, and the partyId of the entity you want to represent
- Find the correct
roles.jsonfile intestdata/authorization/rolesby navigating toUser_{userID}\party_{partyId}\roles.json - Add a new entry in the list for the role you require
{
"Type": "altinn",
"value": "[Insert role code here]"
}
- Save and close the file
- Restart LocalTest
In the k6 folder there is a sample loadtest that can be adapted to run automated tests against a local app It was created to simulate workloads and test monitoring and instrumentation.
cp k6/loadtest.sample.js k6/loadtest.js
# Now make edits to k6/loadtest.js to fit your application
# To run, either
./run.cmd k6
# or
docker run --rm -i --net=host grafana/k6:master-with-browser run - <k6/loadtest.jsFor a decent editing experience, run npm install and use a editor with JS support.
If localtest and you app is running, but localtest reports that the app is not running, it might be that the port is not open in the firewall.
You can verify if the app is running by opening http://localhost:5005/<app-org-name>/<app-name>/swagger/index.html (remember to replace <app-org-name> and <app-name> with the correct values).
If this is the case you can open a Windows Powershell as administrator and run the script OpenAppPortInHyperVFirewall.ps1 located in the scripts folder.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent