diff --git a/README.md b/README.md index 25117fc..e7a0444 100644 --- a/README.md +++ b/README.md @@ -21,3 +21,7 @@ ## 📖 Documentation All the documentation can be found [here](https://docs.solidangle.eu/terrabutler). + +## 📋 Project Template + +A project template can be found [here](https://github.com/lucascanero/terrabutler-aws-template). diff --git a/docs/create-project.md b/docs/create-project.md new file mode 100644 index 0000000..ad507c2 --- /dev/null +++ b/docs/create-project.md @@ -0,0 +1,149 @@ +# Create a new project + +Before proceeding make sure that you have followed the [Installation](installation.md). + +## Configure direnv + +For direnv to work properly it needs to be hooked into the shell. +Check direnv docs to know more: https://direnv.net/docs/hook.html + +Make sure that you have followed direnv documentation before proceeding. + + +## Configure Terrabutler + +### Create your project folder + +```shell +mkdir +``` + +### Download Template + +Start by downloading the Terrabutler Template Project from the repository source below: + +[![Version-shield]](https://github.com/lucascanero/terrabutler-template/archive/refs/heads/example-template.zip) + +Copy the files inside `./terrabutler-template/` to the root of your project folder. + +```shell +$ cp -a /terrabutler-template/. // +``` + +### Create a new workspace + +Before configuring terrabutler, inside `/site_inception` folder, you will need to create a Terraform Workspace: +For example, we are gonna call it "staging" + +```shell +$ cd site_inception +$ terraform workspace new staging +``` + +### Change Variables + +Run the script `.//config_template.sh`, with the following arguments, located inside the project folder root: + +```shell +$ ./config_template.sh -d -e -p + +USAGE: + ./config_template [FLAG] [STRING] + +FLAGS: + -o The name for your organization. + Example: -o example + + -d The domain of your organization. + Example: -d example.com + + -e The environment name of your organization. + Example: -e staging +``` + + +???+ danger + This script only works with the template folder! Don't use it in another project folders! + `./terrabutler-template/config_template.sh` + +## Terraform + +Start by installing Terraform with tfenv: + +```shell +$ tfenv install +``` + +### Initialize the Project + +Perform an Terraform Initialization inside site_inception: + +```shell +$ cd /site_inception/ +$ terraform init +``` +Perform an Terraform Apply with the `.tfvars` inside `/config/variables/`: + +`./configs/variables/global.tfvars`
+`./configs/variables/-.tfvars"`
+`./configs/variables/--inception.tfvars"`
+ +```shell +$ terraform apply -var-file="../configs/variables/global.tfvars" -var-file="../configs/variables/-.tfvars" -var-file="../configs/variables/--inception.tfvars" +``` + +### Change local to remote backend + +#### Uncomment the remote backend line +Remove the commented line as below, in the `terrabutler-template` in the path `./site-inception/terraform.tf` to change from local to remote. + +``` +backend "s3" {} +``` + +Perform an Terraform initialization with the backend config file,located in `/configs/backend/` to update the new changes: + +```shell +$ terraform init -backend-config= +``` + +???+ tip + Example: + $ terraform init -backend-config="./configs/backends/--inception.tfvars" + +#### Delete the local state + +Delete the local state in `/site_inception`, as it is not necessary: + +```shell +$ rm -rf terraform.tfstate.d/ terraform.tfstate terraform.tfstate.backup +``` + +### Terrabutler commands + +#### Terrabutler Plan + +Perform an Terrabutler Plan to ensure everything is ok, and plan any changes: + +```shell +$ terrabutler tf -site inception plan +``` +#### Terrabutler Apply + +Perform an Terrabutler Apply to apply the planned changes: + +```shell +$ terrabutler tf -site inception apply +``` +#### Terrabutler Destroy + +Perform an Terrabutler Destroy to delete or undo any changes made in the provider: + +```shell +$ terrabutler tf -site inception destroy +``` + + + [Version-shield]: https://img.shields.io/badge/terrabutler_Template-Download-%23121011.svg?style=for-the-badge&logo=github&colorA=273133&colorB=0093ee "Latest version" + + diff --git a/docs/new-site.md b/docs/new-site.md new file mode 100644 index 0000000..f5f4fec --- /dev/null +++ b/docs/new-site.md @@ -0,0 +1,89 @@ +# Add a new site + +## Create a new directory + +In the project folder root, create a new diretory called `site_`: + +```shell +$ mkdir site_ +``` +???+ tip + Replace `` with your new site name! + +## Configure the new site + + +### Add the new site to `site_inception` variables file + +Add `` to the following file, in `inception_projects = []` line: + +``` +./configs/variables/--inception.tfvars +``` + +### Add the new site to Terrabutler settings + +Add `` to the following file, in `sites: ordered: - ` line: + +``` +./configs/settings.yml +``` + +### Add a new variable file to the Variables Folder + +Create a new file called `--.tfvars` to the following directory: + +``` +./configs/variables/--.tfvars +``` + +### Perform an apply in `site_inception` + +Run the following command, to update the new configuration on `site_inception`: + +```shell +$ terrabutler tf -site inception apply +``` + +## Add files to the new site + +### Add terraform files + +Run the following commands to copy the following Terraform files to the site_``: + +```shell +$ cd site_ +``` + +```shell +$ cp ../site_inception/terraform.tf . +``` + +```shell +$ cp ../site_inception/provider.tf . +``` + +### Create Symbolic Links + +Run the following commands to create the Symbolic Links: + +```shell +$ cd site_ +``` + +```shell +$ ln -s ../globals/data.tf ./data_global.tf +``` +```shell +$ ln -s ../globals/locals.tf ./locals_globals.tf +``` +```shell +$ ln -s ../globals/variables.tf ./variables_globals.tf +``` +### Perform an init in the new site + +Run the following command: + +```shell +$ terrabutler tf -site data init +``` diff --git a/docs/requirements.md b/docs/requirements.md index 4f18965..6841af2 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -7,6 +7,9 @@ Before you start using you will need to have some tools installed. These tools are required to be installed for a **Terrabutler** to work properly. +???+ danger + This repository only works on Intel based Processors (x86/x64). Arm/Arm64 or another processor architectures are incompatible! + ## Installing requirements In the list below you have the install instruction for each tool: @@ -16,4 +19,4 @@ In the list below you have the install instruction for each tool: ## After checking requirements -You can now proceed to the [installation](installation.md) process of **Terrabutler**. \ No newline at end of file +You can now proceed to the [installation](installation.md) process of **Terrabutler**. diff --git a/mkdocs.yml b/mkdocs.yml index 2f1e8e0..f934346 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -56,3 +56,5 @@ nav: - Requirements: requirements.md - Installation: installation.md - Basic Usage: usage.md + - Create New Project: create-project.md + - Add New Site : new-site.md