diff --git a/simulation/Makefile b/simulation/Makefile index c0597002..d2e04ef5 100644 --- a/simulation/Makefile +++ b/simulation/Makefile @@ -32,4 +32,17 @@ push-to-ecr: ## build-client: Build Docker image only without pushing to ECR build-client: @echo "Building Docker image without pushing to ECR..." - ./script/build_and_push.sh -a $(AWS_ACCOUNT_ID) -r $(AWS_REGION) -e $(ECR_REPOSITORY_NAME) -i $(IMAGE_NAME) -d $(DOCKERFILE_PATH) -c $(BUILD_CONTEXT) --no-push \ No newline at end of file + ./script/build_and_push.sh -a $(AWS_ACCOUNT_ID) -r $(AWS_REGION) -e $(ECR_REPOSITORY_NAME) -i $(IMAGE_NAME) -d $(DOCKERFILE_PATH) -c $(BUILD_CONTEXT) --no-push + +## run-remote: Run simulation on remote server +run-remote: + @echo "Running simulation on remote server..." + @if [ -z "$(SUBNET_IDS)" ]; then \ + echo "Error: SUBNET_IDS is not set. You can find this in CloudFormation outputs."; \ + exit 1; \ + fi + @if [ -z "$(SECURITY_GROUP_IDS)" ]; then \ + echo "Error: SECURITY_GROUP_IDS is not set. You can find this in CloudFormation outputs."; \ + exit 1; \ + fi + go run ./remote/orchestrator/main.go \ No newline at end of file diff --git a/simulation/README.md b/simulation/README.md index f11a1e53..f3685c8b 100644 --- a/simulation/README.md +++ b/simulation/README.md @@ -1,26 +1,102 @@ -# Simulation Framework for Server Testing +# Simulation Framework for Ark Server Testing -This simulation framework is designed to test the **Ark Server** by simulating multiple clients performing -various actions over several rounds. It reads simulation configurations from YAML files, validates them against a predefined schema, -and executes the simulation accordingly. +This simulation framework tests the **Ark Server** by simulating multiple clients performing various actions over several rounds. It utilizes YAML configuration files and validates them against a predefined schema. + +## Architecture + +The simulation framework is structured as follows: + +1. **Configuration Files**: + - `schema.yaml`: Defines the structure and rules for configuration files used in simulations. + - `Simulation.yaml`: The main configuration file, following `schema.yaml`, specifies the parameters for each simulation. + +2. **Orchestrator**: + - Acts as the main controller, reading configurations from `schema.yaml` and `Simulation.yaml`. + - Start ASP and Ark Clients and orchestrates the interactions between them based on the defined simulation scenarios. + - Supports both single-process and multi-process simulations for flexible testing. + +3. **Ark Clients**: + - Represent individual Ark Client that interact with the **Ark Server** based on orchestrated instructions. + - Multiple Ark Clients can run in parallel, enabling the simulation of a network of users with varying behaviors. + +4. **External Dependencies**: + - **Nigiri**: Provides a local Bitcoin Regtest environment, necessary for simulating blockchain-related actions. + - **Ark Server**: The server under test, which receives requests from Ark Clients and processes them accordingly. + +

+ Architecture Diagram +

## Usage -### 1. Start Nigiri +The simulation can be run either locally or on AWS. + +### Local Deployment + +For smaller tests, local deployment allows for a quick setup: + +- **Single process**: The orchestrator and Ark Clients run in the same process. +- **Multi-process**: The orchestrator and clients run as separate processes, mimicking a more realistic client-server interaction. + +#### Prerequisites + +1. **Start Nigiri (Bitcoin Regtest environment)**: + ```bash + nigiri start + ``` + +2. **Configure Testing Scenario**: + - Create a simulation YAML file based on the `schema.yaml` format. + - Check out the example configuration for guidance. + +3. **Run Simulation**: + ```bash + # Single-process mode: + make run-single + + # Multi-process mode: + make run-multi + ``` + +### AWS Deployment +As more users join the round, VTXO tree grows and there will be more transactions to sign by each user. +Considering signing is expensive operation, it quickly becomes a bottleneck in the simulation, as it drains the CPU resources. +To overcome this and to provide a more realistic simulation, this framework supports running the simulation in AWS. + +#### Prerequisites -Ensure that Nigiri (a Bitcoin Regtest environment) is running: +1. **Create AWS SSH Keys**: + - Go to AWS EC2 Console > Key Pairs + - Create a new key pair and save the private key file (`.pem`) -```sh -nigiri start -``` +#### Setup Process -#### 2. Configure the Testing Scenario -Create a simulation YAML file based on the [schema.yaml](./schema.yaml). You can refer to the [this](./simulation1.yaml) example for guidance. +1. **Deploy CloudFormation Stack**: + - Upload the CloudFormation template file to AWS CloudFormation + - Fill in the mandatory parameters: + - Stack name + - SSH key pair (select the one created in prerequisites) + - Ark GitHub URL + - Branch name (defaults to master) -#### 3. Run simulation +2. **Get Infrastructure Details**: + - Once CloudFormation stack creation is complete, go to the Outputs tab + - Note down the following values: + - `SUBNET_IDS` + - `SECURITY_GROUP_IDS` -```sh -make run SIMULATION=your_simulation.yaml -``` +3. **Verify Installation**: + - SSH into the EC2 instance + - Check installation progress: + ```bash + less /var/log/cloud-init-output.log + ``` + - Verify that the Ark Client Docker image has been successfully pushed to ECR -Replace your_simulation.yaml with the path to your simulation configuration file. \ No newline at end of file +4. **Run Remote Simulation**: + ```bash + cd ./ark/simulation/remote/orchestrator + export SUBNET_IDS={SUBNET_IDS} + export SECURITY_GROUP_IDS={SECURITY_GROUP_IDS} + make run-remote + ``` \ No newline at end of file diff --git a/simulation/arch.png b/simulation/arch.png new file mode 100644 index 00000000..d53bb521 Binary files /dev/null and b/simulation/arch.png differ diff --git a/simulation/remote/infra/cloudformation.yaml b/simulation/remote/infra/cloudformation.yaml index 60ffc300..74a4b7df 100644 --- a/simulation/remote/infra/cloudformation.yaml +++ b/simulation/remote/infra/cloudformation.yaml @@ -327,8 +327,8 @@ Resources: NetworkMode: awsvpc RequiresCompatibilities: - FARGATE - Cpu: '512' - Memory: '1024' + Cpu: '1024' + Memory: '2048' ExecutionRoleArn: !GetAtt ECSTaskExecutionRole.Arn TaskRoleArn: !GetAtt ECSTaskExecutionRole.Arn ContainerDefinitions: