diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml new file mode 100644 index 0000000..696221c --- /dev/null +++ b/.github/workflows/pipeline.yml @@ -0,0 +1,22 @@ +name: Build and Deploy +on: [push] +permissions: + contents: write +jobs: + build-and-deploy: + concurrency: ci-${{ github.ref }} # Recommended if you intend to make multiple deployments in quick succession. + runs-on: ubuntu-latest + steps: + - name: Checkout 🛎️ + uses: actions/checkout@v3 + + - name: Install and Build + run: | + sudo apt install graphviz + yarn install + yarn build + + - name: Deploy 🚀 + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: upload/sa/model # The folder the action should deploy. \ No newline at end of file diff --git a/src/sa/model/decisions/0007-canary-release.madr b/src/sa/model/decisions/0007-canary-release.madr new file mode 100644 index 0000000..4b2185b --- /dev/null +++ b/src/sa/model/decisions/0007-canary-release.madr @@ -0,0 +1,51 @@ +## ADR #0007: The Canary release deployment strategy should be used for SmartHut + +1. **What did you decide?** + + The Canary release deployment strategy shall be the deployment strategy used + to release the SmartHut system to users and hobbyists. + +2. **What was the context for your decision?** + + The chosen deployment strategy shall be effective at maximizing user satisfaction + with the SmartHut project, while exploiting the open-source and open-contribution + nature of the project, which will make a "move fast - break things" approach desirable + to power users and contributors for the sake of new features and improvements. + + This environment is thus ripe of users which are willing to trade some instability for + getting to be at the bleeding edge, or simply act as volunteering user acceptance / + quality asssurance testers. The deployment strategy shall exploit this fact as an + economical way to give the _green light_ to widespread adoption of each release. + +3. **What is the problem you are trying to solve?** + + Which is the most suitable and cost-effective deployment strategy for an hobbyist-oriented project? + +4. **Which alternative options did you consider?** + + - Big Bang + - Blue/Green + - Shadow + - Pilot + - Gradual Phase-in + - Canary + - A/B testing + +5. **Which one did you choose?** + + - Canary + +6. **What is the main reason for that?** + + Given the presence of users who are willing to play the role of quality assurance, Gradual phase-in + releases with very few initial users who do not mind dealing with failures seem appropriate as these + users are willing to tolerate failures. + + Pros: + - Integrates well with a cost-effective UAT strategy + - Appropriate for an open-contribution environment + - Allows to "move fast and break things". + + Cons: + - A degreee of instability is to be expected in new releases + - The quality of widespread releases depends on the quality of the quality assurance performed by volunteers. \ No newline at end of file diff --git a/src/sa/model/index.md b/src/sa/model/index.md index 73c6743..7484068 100644 --- a/src/sa/model/index.md +++ b/src/sa/model/index.md @@ -1610,6 +1610,145 @@ Exceed: 1 physical view, 1 deployment view, 1 ADR (b.) + 1 demo (c.) } +### Container View + +```puml +@startuml +!include + +Person(user, "User") + +System_Boundary(system, "SmartHut") { + ContainerDb(udb, "Users and Devices DB", "PostgreSQL") + ContainerDb(tdb, "Triggers and Automations DB", "PostgreSQL") + ContainerDb(sdb, "Scenes DB", "PostgreSQL") + + Container(ui, "User Interface", "React Javascript + static HTTP server") + Container(uw, "Users and Devices Engine", "Spring Java") + Container(tw, "Triggers and Automations Engine", "Spring Java") + Container(sw, "Scenes Engine", "Spring Java") +} + +System_Ext(msd, "Smart Device", "MQTT compatible") +System_Ext(mss, "Smart Sensor", "MQTT compatible") +System_Ext(hsd, "Smart Device", "Homekit compatible") +System_Ext(hss, "Smart Sensor", "Homekit compatible") + +Rel(uw, hsd, "Connects to", "Homekit protocol") +Rel(uw, hss, "Connects to", "Homekit protocol") +Rel(uw, msd, "Connects to", "MQTT protocol") +Rel(uw, mss, "Connects to", "MQTT protocol") + +Rel(user, ui, "Interact with") + +Rel(uw, udb, "Reads/Writes", "JDBC") +Rel(tw, tdb, "Reads/Writes", "JDBC") +Rel(sw, sdb, "Reads/Writes", "JDBC") + +Rel(uw, tw, "Uses", "HTTP requests") +Rel(tw, sw, "Uses", "HTTP requests") +Rel(sw, uw, "Uses", "HTTP requests") +Rel(ui, tw, "Uses", "HTTP requests") +Rel(ui, sw, "Uses", "HTTP requests") +Rel(ui, uw, "Uses", "HTTP requests") +@enduml +``` + +### Deployment View + +```puml +@startuml +title SmartHut Deployment View + +database "Users and Devices" { + [Engine] as UW + [DB] as UDB + UW - UDB +} + +database "Triggers and Automations" { + [Engine] as TW + [DB] as TDB + TW - TDB +} + +database "Scenes" { + [Engine] as SW + [DB] as SDB + SW - SDB +} + +UW -- TW: HTTPS +TW -- SW: HTTPS +UW -- SW: HTTPS + +node "Device" { + [Web Based User Interface] as UI +} + +cloud "User owned smart devices" { + [Homekit Smart Device] as HD + [Homekit Smart Sensor] as HS + [MQTT Smart Device] as MD + [MQTT Smart Sensor] as MS +} + +cloud "User Interface CDN" { + [User Interface Web Server] as CDN +} + +UW -- HD: Homekit protocol +UW -- HS: Homekit protocol +UW -- MD: MQTT +UW -- MS: MQTT + +UI -- CDN: HTTPS +UI -- UW: HTTPS +UI -- TW: HTTPS +UI -- SW: HTTPS + +skinparam monochrome true +skinparam shadowing false +skinparam defaultFontName Courier +@enduml +``` + +![Architectural Decision Record](./decisions/0007-canary-release.madr) + + +## CI/CD pipeline + +A proof-of-concept CI/CD pipeline was implemented using this very documentation repository and this [GitHub Actions tutorial](https://github.com/marketplace/actions/deploy-to-github-pages). + +The YAML Github Actions pipeline configurations is the following: + +```yml +name: Build and Deploy +on: [push] +permissions: + contents: write +jobs: + build-and-deploy: + concurrency: ci-${{ github.ref }} # Recommended if you intend to make multiple deployments in quick succession. + runs-on: ubuntu-latest + steps: + - name: Checkout 🛎️ + uses: actions/checkout@v3 + + - name: Install and Build + run: | + sudo apt install graphviz + yarn install + yarn build + + - name: Deploy 🚀 + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: upload/sa/model # The folder the action should deploy. +``` + +Therefore, this documentation website is also available in [Github Pages](https://usi-msde-sa-2023.github.io/sa--maggicl/). + # Ex - Availability and Services {.instructions