Skip to content

00_Setting up new Projects

Jump to bottom
David Wyss edited this page Apr 20, 2023 · 22 revisions

Introduction

When creating a new project, a separate GitHub repository must be created. As github did not suppot creating projects fork until very recently, forking flox involved a complex workflow in which a pseudo-fork was created, while automations synchronized the state of the main flox repository to all of its forks. This hack is no longer required. To create a new project based on flox, just click on "fork" or navigate here.

GitHub & Code-level

Follow these steps to get a development-ready repository setup:

  1. Create a Fork of Flox here.
  2. Enter the name of the repository you want to create, following the schema "customer-project". Add a short description, then click on "Create Fork". Wait until your fork is created. All the following steps take place in the forked project repository.
  3. Within GitHub's repository settings, set up Branch protection rules on the new repository for the master, dev and stage-* branches. See the branch protection rules within this repository for reference.
  4. Within GitHub's repository settings, set up Tag protection rules for v* tags.
  5. Within the Flox Repository, extend the auto-fork action to include the newly created repository. This will keep the flox branch on the new repository in sync with the Flox repository.
  6. Within SonarCloud, log in with GitHub, and click "Analyze new Project". Choose the new repository, this will create a corresponding SonarCloud key.
  7. At the Quality Gate setup (under "Main Branch"), set the new code definition to "Previous Version". This will allow SonarCloud to run the Quality Gate upon the next scan.
  8. Within GitHub's repository settings, enter the created token as a GitHub Action Secret with the name SONAR_TOKEN.
  9. In README.md, update the SonarCloud project key (e.g. polygon-software_flox) and token (e.g. abcd12345def) according to those given in the "Information" tab within SonarCloud.
  10. Within Terraform Cloud, create a new organisation with the customer's name. This is important because, in case of termination of contract with the customer, the entire organisation can be transferred to the customer.
  11. Within Terraform Cloud, at the user level, create a new API token. Name the token <project name> TF_API_TOKEN, e.g. Flox TF_API_TOKEN. Add it as a GitHub actions secret named TF_API_TOKEN.
  12. within backend/flox.config.json, change the organisation parameter to the name of the previously created Terraform organisation, and the project parameter to the project's name in lowercase. Also change any other parameters (such as the live domain) you may want to change.
  13. In backend/.env, change the parameters PROJECT_NAME to the project's name (failure to do so may result in conflicting Docker container states).
  14. (optional) Set up LogRocket by creating a new organisation and application (e.g. polygonsoftware/flox). Take note of the given project key under "Project Setup" -> "Web". Enter the key in the LogRocket setup block in frontend/App.vue. If you want to locally test LogRocket connection, you must also set the VUE_APP_PRODUCTION parameter in frontend/.env to true. Make sure to set this value back to false after testing, as LogRocket will otherwise use up many sessions during development.
  15. (alternatively) If you don't need LogRocket, remove it from frontend/App.vue entirely, as well as from frontend/package.json.
  16. Locally test the application by running docker:dev from backend/package.json, as well as dev from frontend/package.json. This should result in a fully running application with frontend, backend and database. The frontend should be reachable at localhost:8080, while the backend's GraphQL playground should be reachable at localhost:3000/graphql.
  17. Ensure SonarCloud's analysis runs successfully upon pushing to the master branch, and the GitHub page's README.md is popuplated correctly. You may need to rerun any failed SonarCloud Scan actions within the repo's "Actions" tab for this to succeed.

AWS (Amazon Web Services)

Organization Structure

Flox uses AWS (Amazon Web Services) as its primary / standard infrastructure provider. Thus, creating a new Flox project usually comes with the need to set new infrastructure on AWS. In order to make this as streamlined, separated and secure as possible, we use a separate AWS organization for each customer.

PolygonSoftware's organizational structure within AWS is as follows:

PolygonSoftware (root)
│
├── Customers
│   ├── DataVis
│   ├── BigABig
│   ├── PolygonSoftware    // our own resources are hosted here
│   └── ...
│
├── Backup
│   ├── DataVis-Backup
│   └── ...
│
└── PolygonSoftware AWS (Management Account)

Note that for each Customer Organization, we also have a Backup Organization. This backup is a completely separate account, and thus cannot be affected by e.g. attacks or accidental resource deletion on a customer account. (NOTE/TODO: This needs to be set up here first!) Thus, when creating a new customer project, we first create a new organization within AWS Organizations. Note that this cannot be done if logged in to the PolygonSoftware organization via SSO, but must be done from a root account (either through direct root login as [email protected] or an authorized administrator within the parent organization).

Also note that, by default, some infrastructure will be set up on <something>.polyon-project.ch subdomains (more on that later in the chapters about the Flox workflow). Since that domain is owned by the PolygonSoftware sub-account, a Route53 record is provided to each customer account in order to access subdomains of the polygon-project.ch domain.

The steps for this complete AWS setup are as follows:

  1. Within AWS Organizations on the [email protected] root account, set up a new customer account. As the e-mail address, use <project name>@polygon-software.ch. This can be changed later, in case the account must be passed on to the customer.
  2. Choose "Actions" -> "Move" and move the newly created account to the "Customers" subgroup.
  3. Within AWS IAM Identity Center (Previously AWS SSO), go to "AWS Accounts" -> your newly created customer account -> "Assign users or groups" and add the "Developers" group to the account, using the AdministratorAccess policy. This will allow all developers to access the new AWS account through SSO/IAM Identity Manager.
  4. Using a developer account, sign in to the new customer account using SSO.
  5. In AWS IAM, go to "Users" -> "Create User".
  6. Create a user named terraform-admin. Choose "Access key - Programmatic access". Choose "Attach existing policies directly", and pick AdministratorAccess. This is essential for granting Terraform access to all AWS resources.
  7. After creating the user, note the access key ID and secret access key.
  8. Within your Terraform Cloud organisation, go to "Settings" -> "Variable Sets". Click "Create Variable Set".
  9. Enter AWS Access as the variable set name. Choose "Apply to all workspaces in this organization".
  10. Enter the access key ID you previously noted as a non-sensitive Terraform variable named aws_access_key.
  11. Enter the secret access key you previously noted as a sensitive Terraform variable named aws_secret_access_key.
  12. Go to Bitwarden and find the "AWS Domain Manager Key" login information; you will need it in the next two steps. (These credentials are for the polygon-project-domain-manager within the PolygonSoftware AWS Organisation.
  13. Enter the access key ID (e.g. AKIA....) as a non-sensitive Terraform variable named domain_manager_aws_access_key. This key allows creating resources within the polygon-project domain.
  14. Enter the secret access key as a sensitive Terraform variable named domain_manager_aws_secret_access_key.
  15. That's it! 🎉 You should now be able to use the manual GitHub actions to launch a dev/test/live system.
Clone this wiki locally