You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/deployment/guide.md
+82-35Lines changed: 82 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,13 +6,19 @@ This is the primary, streamlined path to deploy the solution. It contains only w
6
6
7
7
IroCO2 has been designed to be a SaaS at first and deployed in Ippon AWS account without possibility to self-host it. The Terraform currently present in the repositories is the one we used to maintain the SaaS deployment.
8
8
9
-
But today, we want to allow self-hosting of the solution. The Terraform and deployment approach currently present is not ideal for this purpose. But we plan to improve it in out next steps. If you want to self-host the solution, you can use the Terraform currently present in the repositories by reading this documentation.
9
+
IroCO2 is currently designed to be deployed on AWS with Terraform.
10
+
The typical deployment is described in the following document.
11
+
12
+
In the future, we want to allow additionnal platforms and self-hosting.
10
13
11
14
## Prerequisites
12
15
13
-
- An AWS account
14
-
- Terraform
16
+
- An AWS account with an S3 bucket available to store the terraform tfstate.
17
+
- (optionnal) For *client-side-scanner* module, a symetrical KMS key, available within you AWS account
18
+
- Terraform installed (either on a CI or locally)
15
19
- A domain name within Route53 (or a delegation to Route53)
20
+
- Records will need to be created, and certificates to be validated through DNS.
21
+
- Go development tools on your local machine
16
22
17
23
**_Note: root access to AWS account is not required_**
18
24
@@ -25,14 +31,16 @@ But today, we want to allow self-hosting of the solution. The Terraform and depl
25
31
- Containers/runtime (selecting image tags, health checks): basic
26
32
27
33
## Estimated deployment time
28
-
34
+
29
35
Summary (elapsed):
30
-
- Quick: 1.5–3h
31
-
- Typical first-time: 4-6h
36
+
- Configuration: 30m
37
+
- Deployment infra: 1h (DNS propagation/validation may take longer in some cases.)
@@ -44,24 +52,50 @@ Notes: Faster with org-ready IAM/Route53 and reusable `tfvars`. Slower with miss
44
52
45
53
You can deploy IroCO2 in any region supported by AWS. Exception: the client side scanner lambda need to be deployed in `eu-west-3` and the CUR Data Export in `us-east-1`.
46
54
55
+
One of recommended region for deploying is `eu-west-3`. Here's [why](https://app.electricitymaps.com/zone/FR/live/fifteen_minutes/2025-10-14T13:00:00.000Z).
56
+
47
57
## Deployment
48
58
59
+
### Pre-requisites
60
+
1. Go language must me installed on your local machine.
61
+
→ ie. `apt install golang`
62
+
2. Create S3 bucket
63
+
- AWS CLI method
64
+
`aws s3 mb s3://<your-bucket-name>`
65
+
- AWS GUI method
66
+
***{TODO}***
67
+
68
+
3. Create a Route53 entry
69
+
- Create a type A record (simple routing)
70
+
4. (optionnal) Create KMS key for *client-side-scanner*.
71
+
- See [documentation](https://ippontech.github.io/iroco2/#/docs/guide_scanner)
72
+
73
+
74
+
### Deployment steps
75
+
49
76
1. Clone the [terraform repository](https://github.com/ippontech/iroco2-terraform-modules)
50
-
2. Each directory in the `layers` folder is a terraform project. For each :
51
-
1. Add you backend configuration in the `backend-configs` directory as well as environment configuration in the `env-configs` directory
52
-
2. Initialize the terraform project with `terraform init -backend-config=../backend-configs/<backend>.tfvars -var-file=../env-configs/<env>.tfvars`
53
-
3. Provide all the needed variables in a tfvars file in the `tfvars` directory
54
-
4. Apply the terraform project with `terraform apply -var-file=../tfvars/<env>.tfvars`
55
-
3. Clone the [frontend repository](https://github.com/ippontech/iroco2-frontend)
77
+
2. Add your backend configuration in the `backend-configs` directory
78
+
3. Add your environment variables in the `env-configs` directory
79
+
4. Prepare authorizer lambda bootstrap:
80
+
1. Move to authorizer src directory
81
+
`cd ./layers/iroco2-authorizer/src`
82
+
3. Execute build script
83
+
`../scripts/build.sh`
84
+
5. Each directory in the `layers` folder is a terraform project. For each one, in the following order **network**, **data**, **services**, **lambdas** (in no particular order), **api-gateway**:
85
+
1. Initialize the terraform project with your variables files:
1. Provide all the needed variables in a tfvars file in the `tfvars` directory. You can copy the *tfvars.example* files.
88
+
2. Apply the terraform project with `terraform [plan,apply] -var-file=../../env-configs/<yourfile>.tfvars -var-file=./tfvars/<yourfile>.tfvars`
89
+
6. Clone the [frontend repository](https://github.com/ippontech/iroco2-frontend)
56
90
1. Retrieve the Cloudfront distribution ID and S3 bucket name from the terraform output of the previous repository (`layer/service`)
57
91
2. Follow the README of the frontend repository to deploy the frontend to your cloudfront distribution
58
-
4. Clone the [backend repository](https://github.com/ippontech/iroco2-backend)
92
+
7. Clone the [backend repository](https://github.com/ippontech/iroco2-backend)
59
93
1. Add your backend configuration in the `backend-configs` directory as well as environment configuration in the `tfvars` directory (you can choose the backend image version [here](https://github.com/orgs/ippontech/packages?repo_name=iroco2-backend))
60
94
2. Initialize the terraform project with `terraform init -backend-config=../backend-configs/<backend>.tfvars`
61
95
3. Provide all the needed variables in a tfvars file in the `tfvars` directory
62
96
1. You will get the latest version of the docker image of the backend API. You can find them on this page: https://hub.docker.com/r/ippontech/iroco2-backend
63
97
4. Apply the terraform project with `terraform apply -var-file=../tfvars/<env>.tfvars`
64
-
5. Clone the lambda repository [iroco2-lambda](https://github.com/ippontech/iroco2-lambdas)
98
+
8. Clone the lambda repository [iroco2-lambda](https://github.com/ippontech/iroco2-lambdas)
65
99
66
100
67
101
## Backup & Restore
@@ -94,31 +128,44 @@ There is no licence cost, the software is free to use.
94
128
95
129
Use this as a quick checklist to estimate costs. “Mandatory” means required for a typical production-like deployment of IroCO2; “Optional” indicates features you can disable if you don’t need them.
96
130
97
-
| AWS Service | Purpose | Mandatory/Optional | Notes |
98
-
|---|---|---|---|
99
-
| Amazon VPC | Network isolation | Mandatory | One VPC with public/private subnets. |
100
-
| NAT Gateway | Egress for private subnets | Optional | Use only if private subnets need general internet egress. You can avoid NAT by using VPC endpoints and limiting egress. |
101
-
| Elastic Load Balancing (ALB) | Ingress for backend API | Mandatory | If API is public or behind CloudFront. Internal NLB/ALB possible for private-only use. |
102
-
| Amazon ECS on Fargate | Run backend containers | Mandatory | Minimum one service for API. |
103
-
| Amazon ECR | Container image registry | Optional | You may pull from Docker Hub ippontech/iroco2-backend; using ECR improves reliability and IAM control. |
| AWS Lambda | Scanner/ETL functions | Optional (per feature) | Mandatory only if you enable the Scanner and/or CUR ingestion functions. |
106
-
| Amazon SQS | Asynchronous messaging/decoupling | Optional (per feature) | Used for background processing and decoupling when enabled; costs per requests and polling. |
107
-
| Amazon S3 | Frontend hosting, assets, CUR storage | Mandatory | Always required for static frontend hosting; additionally used for CUR if the feature is enabled. |
108
-
| Amazon CloudFront | Global CDN for frontend | Mandatory | Serves the UI with TLS and caching. |
| Amazon Route 53 | DNS | Mandatory | Public hosted zone or delegated subdomain for your domain. |
111
-
| AWS Secrets Manager | Store DB creds and app secrets | Mandatory | Rotation recommended; can also use SSM Parameter Store. |
112
-
| AWS Key Management Service (KMS) | Encryption keys | Mandatory | Required to encrypt RDS, S3, Secrets; you may start with AWS-managed keys or use customer-managed keys. |
| VPC Endpoints (Gateway/Interface) | Private access to AWS APIs | Mandatory when NAT disabled; otherwise Optional | Required if you disable NAT and keep workloads in private subnets to reach AWS APIs without internet egress. |
131
+
| AWS Service | Purpose | Mandatory/Optional | Notes|
| Amazon VPC | Network isolation | Mandatory | One VPC with public/private subnets.|
134
+
| NAT Gateway | Egress for private subnets | Optional| Use only if private subnets need general internet egress. You can avoid NAT by using VPC endpoints and limiting egress. |
135
+
| Elastic Load Balancing (ALB) | Ingress for backend API | Mandatory | If API is public or behind CloudFront. Internal NLB/ALB possible for private-only use.|
136
+
| Amazon ECS on Fargate | Run backend containers | Mandatory | Minimum one service for API.|
137
+
| Amazon ECR | Container image registry | Optional | You may pull from Docker Hub ippontech/iroco2-backend; using ECR improves reliability and IAM control.|
| AWS Lambda | Scanner/ETL functions | Optional (per feature) | Mandatory only if you enable the Scanner and/or CUR ingestion functions.|
140
+
| Amazon SQS | Asynchronous messaging/decoupling | Optional (per feature) | Used for background processing and decoupling when enabled; costs per requests and polling.|
141
+
| Amazon S3 | Frontend hosting, assets, CUR storage | Mandatory | Always required for static frontend hosting; additionally used for CUR if the feature is enabled.|
142
+
| Amazon CloudFront | Global CDN for frontend | Mandatory | Serves the UI with TLS and caching.|
| Amazon Route 53 | DNS | Mandatory | Public hosted zone or delegated subdomain for your domain.|
145
+
| AWS Secrets Manager | Store DB creds and app secrets | Mandatory | Rotation recommended; can also use SSM Parameter Store.|
146
+
| AWS Key Management Service (KMS) | Encryption keys | Mandatory | Required to encrypt RDS, S3, Secrets; you may start with AWS-managed keys or use customer-managed keys.|
| AWS Backup | Centralized backups | Optional | RDS snapshots are sufficient for many; AWS Backup adds policy-based mgmt.|
149
+
| VPC Endpoints (Gateway/Interface) | Private access to AWS APIs | Mandatory when NAT disabled; otherwise Optional | Required if you disable NAT and keep workloads in private subnets to reach AWS APIs without internet egress.|
116
150
117
151
Evidence Bookmark: Billable Services List
118
152
- Link: docs/deployment/guide.md
119
153
- Section: Costs > Billable AWS services (Mandatory vs Optional)
0 commit comments