Skip to content

docs: update deployment guide #299

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sroulon-ippon merged 8 commits into from
Dec 9, 2025
Merged

docs: update deployment guide #299

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
763ecaa
docs: add some first missing details in the guide.md
alexis-renard Sep 10, 2025
3bfdd41
docs: add some first missing details in the guide.md
alexis-renard Sep 10, 2025
5fe45db
Merge remote-tracking branch 'refs/remotes/origin/docs/update-deploym…
sroulon-ippon Oct 14, 2025
f205ba8
chore: update deployment guide
sroulon-ippon Oct 20, 2025
ac5f929
docs: update with additionnal info
sroulon-ippon Nov 12, 2025
1d9d7d5
Merge branch 'main' into docs/update-deployment-guide
sroulon-ippon Dec 9, 2025
b5a4e8f
chore: update guide.md
sroulon-ippon Dec 9, 2025
b30a5fd
fix: resolve order
sroulon-ippon Dec 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 82 additions & 35 deletions docs/deployment/guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,19 @@ This is the primary, streamlined path to deploy the solution. It contains only w

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.

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.
IroCO2 is currently designed to be deployed on AWS with Terraform.
The typical deployment is described in the following document.

In the future, we want to allow additionnal platforms and self-hosting.

## Prerequisites

- An AWS account
- Terraform
- An AWS account with an S3 bucket available to store the terraform tfstate.
- (optionnal) For *client-side-scanner* module, a symetrical KMS key, available within you AWS account
- Terraform installed (either on a CI or locally)
- A domain name within Route53 (or a delegation to Route53)
- Records will need to be created, and certificates to be validated through DNS.
- Go development tools on your local machine

**_Note: root access to AWS account is not required_**

Expand All @@ -25,14 +31,16 @@ But today, we want to allow self-hosting of the solution. The Terraform and depl
- Containers/runtime (selecting image tags, health checks): basic

## Estimated deployment time

Summary (elapsed):
- Quick: 1.5–3h
- Typical first-time: 4-6h
- Configuration: 30m
- Deployment infra: 1h (DNS propagation/validation may take longer in some cases.)
- Deployment code: 1h
- Validation tests: 30m

Steps (human + AWS wait):
1) AWS prereqs/account: 15–60m
2) Terraform layers (3–5): 1.5–3h total
1) AWS prereqs/account: 30m
2) Terraform layers (3–5): 30m
3) Backend (`iroco2-backend`): 30–60m
4) Frontend (S3/CloudFront): 25–60m (incl. propagation)
5) Lambdas: 25–45m
Expand All @@ -44,24 +52,50 @@ Notes: Faster with org-ready IAM/Route53 and reusable `tfvars`. Slower with miss

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`.

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).

## Deployment

### Pre-requisites
1. Go language must me installed on your local machine.
→ ie. `apt install golang`
2. Create S3 bucket
- AWS CLI method
`aws s3 mb s3://<your-bucket-name>`
- AWS GUI method
***{TODO}***

3. Create a Route53 entry
- Create a type A record (simple routing)
4. (optionnal) Create KMS key for *client-side-scanner*.
- See [documentation](https://ippontech.github.io/iroco2/#/docs/guide_scanner)


### Deployment steps

1. Clone the [terraform repository](https://github.com/ippontech/iroco2-terraform-modules)
2. Each directory in the `layers` folder is a terraform project. For each :
1. Add you backend configuration in the `backend-configs` directory as well as environment configuration in the `env-configs` directory
2. Initialize the terraform project with `terraform init -backend-config=../backend-configs/<backend>.tfvars -var-file=../env-configs/<env>.tfvars`
3. Provide all the needed variables in a tfvars file in the `tfvars` directory
4. Apply the terraform project with `terraform apply -var-file=../tfvars/<env>.tfvars`
3. Clone the [frontend repository](https://github.com/ippontech/iroco2-frontend)
2. Add your backend configuration in the `backend-configs` directory
3. Add your environment variables in the `env-configs` directory
4. Prepare authorizer lambda bootstrap:
1. Move to authorizer src directory
`cd ./layers/iroco2-authorizer/src`
3. Execute build script
`../scripts/build.sh`
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**:
1. Initialize the terraform project with your variables files:
` terraform init --backend-config=../../backend-configs/<yourfile>.tfvars --var-file=../../env-configs/<yourfile>.tfvars`
1. Provide all the needed variables in a tfvars file in the `tfvars` directory. You can copy the *tfvars.example* files.
2. Apply the terraform project with `terraform [plan,apply] -var-file=../../env-configs/<yourfile>.tfvars -var-file=./tfvars/<yourfile>.tfvars`
6. Clone the [frontend repository](https://github.com/ippontech/iroco2-frontend)
1. Retrieve the Cloudfront distribution ID and S3 bucket name from the terraform output of the previous repository (`layer/service`)
2. Follow the README of the frontend repository to deploy the frontend to your cloudfront distribution
4. Clone the [backend repository](https://github.com/ippontech/iroco2-backend)
7. Clone the [backend repository](https://github.com/ippontech/iroco2-backend)
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))
2. Initialize the terraform project with `terraform init -backend-config=../backend-configs/<backend>.tfvars`
3. Provide all the needed variables in a tfvars file in the `tfvars` directory
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
4. Apply the terraform project with `terraform apply -var-file=../tfvars/<env>.tfvars`
5. Clone the lambda repository [iroco2-lambda](https://github.com/ippontech/iroco2-lambdas)
8. Clone the lambda repository [iroco2-lambda](https://github.com/ippontech/iroco2-lambdas)


## Backup & Restore
Expand Down Expand Up @@ -94,31 +128,44 @@ There is no licence cost, the software is free to use.

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.

| AWS Service | Purpose | Mandatory/Optional | Notes |
| --- | --- | --- | --- |
| Amazon VPC | Network isolation | Mandatory | One VPC with public/private subnets. |
| 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. |
| Elastic Load Balancing (ALB) | Ingress for backend API | Mandatory | If API is public or behind CloudFront. Internal NLB/ALB possible for private-only use. |
| Amazon ECS on Fargate | Run backend containers | Mandatory | Minimum one service for API. |
| Amazon ECR | Container image registry | Optional | You may pull from Docker Hub ippontech/iroco2-backend; using ECR improves reliability and IAM control. |
| Amazon RDS (PostgreSQL) | Application database | Mandatory | Sized per workload; automatic backups recommended. |
| AWS Lambda | Scanner/ETL functions | Optional (per feature) | Mandatory only if you enable the Scanner and/or CUR ingestion functions. |
| Amazon SQS | Asynchronous messaging/decoupling | Optional (per feature) | Used for background processing and decoupling when enabled; costs per requests and polling. |
| Amazon S3 | Frontend hosting, assets, CUR storage | Mandatory | Always required for static frontend hosting; additionally used for CUR if the feature is enabled. |
| Amazon CloudFront | Global CDN for frontend | Mandatory | Serves the UI with TLS and caching. |
| AWS Certificate Manager (ACM) | TLS certificates | Mandatory | Required for CloudFront/ALB HTTPS. |
| Amazon Route 53 | DNS | Mandatory | Public hosted zone or delegated subdomain for your domain. |
| AWS Secrets Manager | Store DB creds and app secrets | Mandatory | Rotation recommended; can also use SSM Parameter Store. |
| 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. |
| Amazon CloudWatch (Logs/Metrics/Alarms) | Observability | Mandatory | Container logs, Lambda logs, dashboards/alarms. |
| AWS Backup | Centralized backups | Optional | RDS snapshots are sufficient for many; AWS Backup adds policy-based mgmt. |
| 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. |
| AWS Service | Purpose | Mandatory/Optional | Notes |
|-----------------------------------------|---------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| Amazon VPC | Network isolation | Mandatory | One VPC with public/private subnets. |
| 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. |
| Elastic Load Balancing (ALB) | Ingress for backend API | Mandatory | If API is public or behind CloudFront. Internal NLB/ALB possible for private-only use. |
| Amazon ECS on Fargate | Run backend containers | Mandatory | Minimum one service for API. |
| Amazon ECR | Container image registry | Optional | You may pull from Docker Hub ippontech/iroco2-backend; using ECR improves reliability and IAM control. |
| Amazon RDS (PostgreSQL) | Application database | Mandatory | Sized per workload; automatic backups recommended. |
| AWS Lambda | Scanner/ETL functions | Optional (per feature) | Mandatory only if you enable the Scanner and/or CUR ingestion functions. |
| Amazon SQS | Asynchronous messaging/decoupling | Optional (per feature) | Used for background processing and decoupling when enabled; costs per requests and polling. |
| Amazon S3 | Frontend hosting, assets, CUR storage | Mandatory | Always required for static frontend hosting; additionally used for CUR if the feature is enabled. |
| Amazon CloudFront | Global CDN for frontend | Mandatory | Serves the UI with TLS and caching. |
| AWS Certificate Manager (ACM) | TLS certificates | Mandatory | Required for CloudFront/ALB HTTPS. |
| Amazon Route 53 | DNS | Mandatory | Public hosted zone or delegated subdomain for your domain. |
| AWS Secrets Manager | Store DB creds and app secrets | Mandatory | Rotation recommended; can also use SSM Parameter Store. |
| 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. |
| Amazon CloudWatch (Logs/Metrics/Alarms) | Observability | Mandatory | Container logs, Lambda logs, dashboards/alarms. |
| AWS Backup | Centralized backups | Optional | RDS snapshots are sufficient for many; AWS Backup adds policy-based mgmt. |
| 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. |

Evidence Bookmark: Billable Services List
- Link: docs/deployment/guide.md
- Section: Costs > Billable AWS services (Mandatory vs Optional)
- Paragraph: Table above


## Deletion


/!\ WIP

1. Disable deletion protection on RDS DB
2. In reverse order:
- `terraform destroy -var-file=../../env-configs/<yourfile>.tfvars -var-file=./tfvars/<yourfile>.tfvars`
3. Network has dependencies failures
4. Delete remaining resources, s3 buckets (alb logs, cloudfront sources, etc...)


## Architecture diagram

Please find below the architecture diagram of the solution.
Expand Down