Skip to main content

​
Prerequisites

Before you start, make sure you have the following installed:
  • Java 17+ — the service targets Java 17
  • Maven 3.8+ — or use the included ./mvnw wrapper
  • Docker — required to run LocalStack
  • AWS CLI — used to inspect LocalStack resources and retrieve the KMS key ARN

​
Local services used

pn-paper-channel depends on the following AWS services, all emulated by LocalStack:
ServicePurpose
DynamoDBAll application tables (requests, addresses, tenders, costs, etc.)
SQSInternal and external queues
KMSSymmetric AES-256-GCM key for address encryption
EventBridgePublishing PaperChannelOutcomeEvent to the core event bus

​
Running locally

1

Clone the repository

git clone https://github.com/pagopa/pn-paper-channel.git
cd pn-paper-channel
2

Start LocalStack via Docker

Start LocalStack with the services the application needs:
docker run \
  --rm -d \
  -p 4566:4566 \
  -e SERVICES=dynamodb,sqs,kms,events \
  --name localstack \
  localstack/localstack
Wait until LocalStack is healthy:
curl http://localhost:4566/_localstack/health
3

Retrieve the KMS key ARN from LocalStack logs

When LocalStack starts, it creates a default KMS key. Retrieve the ARN from the container logs:
docker logs localstack 2>&1 | grep -i "kms"
Alternatively, create a key explicitly and capture the ARN:
aws --endpoint-url=http://localhost:4566 \
  --region us-east-1 \
  kms create-key \
  --description "pn-paper-channel local key" \
  --query 'KeyMetadata.Arn' \
  --output text
Copy the returned ARN — you need it in the next step.
4

Set the KMS key ARN in the local config

Open config/application.properties and set the aws.kms.keyId property to the ARN you copied:
aws.kms.keyId=arn:aws:kms:us-east-1:000000000000:key/<your-key-id>
The rest of the config file already points to LocalStack at http://localhost:4566 and defines all DynamoDB table names and SQS queue names for local use.
5

Run the application with Maven

Use the Spring Boot Maven plugin with the local profile (which loads config/application.properties):
./mvnw spring-boot:run
The service starts on port 8088 (set by server.port=8088 in config/application.properties).You can verify it is running:
curl http://localhost:8088/status
6

Run the test suite

./mvnw test
Tests run against a mock server bound to port 1050 (configured in config/application-test.properties via mockserver.bean.port=1050). The test profile sets pn.env.runtime=TEST and uses aws.endpoint-url=http://localhost:4566 for DynamoDB.
pn-paper-channel uses Testcontainers for integration tests. Docker must be running when you execute ./mvnw test so that Testcontainers can spin up any required containers automatically.

​
Local environment variables quick reference

The file config/application.properties contains all defaults for local development. Key values: 
server.port=8088
pn.env.runtime=DEVELOPMENT
aws.endpoint-url=http://localhost:4566
aws.region-code=us-east-1
aws.kms.keyId=arn:aws:kms:us-east-1:000000000000:key/<your-key-id>
pn.paper-channel.client-safe-storage-basepath=http://localhost:8120
pn.paper-channel.client-national-registries-basepath=http://localhost:1080
pn.paper-channel.client-external-channel-basepath=http://localhost:1080
If you run dependent services (Safe Storage, National Registries, Data Vault, Address Manager) locally, update the *-basepath properties accordingly.

Build docs developers (and LLMs) love

Get started for freeTalk to us