{"id":28544860,"url":"https://github.com/neoteroi/venezia","last_synced_at":"2025-07-01T03:05:57.304Z","repository":{"id":107986049,"uuid":"367843241","full_name":"Neoteroi/Venezia","owner":"Neoteroi","description":"Community API project implemented with BlackSheep.","archived":false,"fork":false,"pushed_at":"2023-12-12T05:50:13.000Z","size":11,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-01T03:05:19.510Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Neoteroi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-05-16T10:02:55.000Z","updated_at":"2023-12-13T10:27:39.000Z","dependencies_parsed_at":"2023-12-09T21:23:51.347Z","dependency_job_id":"724ccb51-9785-4d26-af07-1e35b9bd9806","html_url":"https://github.com/Neoteroi/Venezia","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Neoteroi/Venezia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2FVenezia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2FVenezia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2FVenezia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2FVenezia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Neoteroi","download_url":"https://codeload.github.com/Neoteroi/Venezia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2FVenezia/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262887186,"owners_count":23379767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-09T22:38:03.433Z","updated_at":"2025-07-01T03:05:57.278Z","avatar_url":"https://github.com/Neoteroi.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Venezia, service to handle localized topics and comments\n\nDemo project for a BlackSheep web service deployed to Azure App Service, using\na PostgreSQL database, GitHub Workflows, and ARM templates.\n\nThis is an advanced project template, featuring:\n\n* A `Python` web service using a **PostgreSQL** database\n* Example of _onion architecture_ leveraging dependency injection to organize\n  the code and efficiently reduce code repetition\n* **GitHub Workflows** to automate the deployment of Azure services and the\n  application server\n* **ARM templates** to provision the necessary Azure services\n* **Database migrations** implemented using `Alembic`, automatically deployed as\n  part of the Continuous Delivery workflow\n* Integration with **Azure Application Insights** to collect telemetries for\n  performance, web requests, exceptions, failed requests, including tracking of\n  PostgreSQL dependencies\n* Workflows and ARM templates prepared to support multiple environments:\n  _DEV, TEST, PROD_\n* A `BlackSheep` API, including `OpenAPI Documentation`\n* Instructions describing how to get started and configure GitHub Workflows and\n  create environments in Azure\n\n## Requirements\n\n* A GitHub account\n* An Azure subscription\n* [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)\n\nFor development:\n\n* Python 3.7 or newer\n\n## Overview: how to use this project template\n\n1. Create a new repository starting from this template (using GitHub features),\n   or fork the project\n2. Choose a project name for your new deployment\n3. Configure GitHub secrets\n4. Run the `infrastructure` GitHub Workflow: this creates necessary services in\n   Azure, in different environments\n5. Run the `server` build GitHub Workflow: this builds the application and\n   deploys it to the various environments\n\n## Disclaimer\nThe instructions provided here illustrate the concepts using `Bash` scripts.\nThe following instructions describe how to create a DEV environment in Azure:\nthe same concepts apply to any kind of environment.\n\n### Choosing a project name\n\nThe default project name for this demo is `Venezia`, to honour the Italian city.\nTo create a new deployment of this service, it is necessary to choose a\ndifferent name.\n\nSince Azure provides default domains for the services, the project name must be\nglobally unique. Note that the project name is concatenated to the environment\nname, so for example a project name `example` will result in the creation of an\napp service at the URL: `https://dev-example.azurewebsites.net`, if this name\nis available.\n\nThe name should be set in `./infrastructure/template.json`, editing the\nparameter named `projectName` under `parameters`.\n\n```json\n    \"projectName\": {\n      \"type\": \"string\",\n      \"minLength\": 2,\n      \"defaultValue\": \"venezia\"\n    },\n```\n\n### Configuring GitHub Secrets\n\nBefore starting the first deployment, it is necessary to configure secrets in\nGitHub, in detail:\n\n* deployment credentials that are used by GitHub Actions to interact with the\n  resource group in your subscription\n* a database admin password\n\nThis guide illustrates how to use repository's secrets, which are avaiable also\nfor free private repositories. Another option would be to configure [GitHub\nenvironments](https://docs.github.com/en/actions/reference/environments), but\nthis approach is not described here (the core concepts don't vary).\n\n### List of secrets used by GitHub Workflows, for one environment\n\nThe following table lists the secrets that are required for a single `DEV`\nenvironment:\n\n| Secret name            | Description                                                                 |\n| ---------------------- | --------------------------------------------------------------------------- |\n| DEV_AZURE_SUBSCRIPTION | Azure subscription ID for the DEV environment.                              |\n| DEV_AZURE_CREDENTIALS  | Deployment credentials scoped for the DEV resource group.                   |\n| DEV_DB_MIGCONNSTRING   | Connection string used for database migrations.                             |\n| DEV_DBSA_PASSWORD      | DBA password used to create services in Azure (used in the ARM deployment). |\n\n#### Generating deployment credentials\n\nFollow the instructions described here to generate deployment credentials and\nconfigure them in GitHub secrets:\n* [Deploy ARM templates by using GitHub Actions](https://docs.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-github-actions)\n\n**In summary:**\n\nTo generate deployment credentials, use the Azure CLI after signing-in to your\nAzure account and selecting the desired subscription.\n\nIf the chosen project name is `example`, it is recommended to use a resource\ngroup name such as `dev-example-rg` for the DEV environment.\n\n```bash\n# login\naz login\n\n# select the desired subscription\naz account set --subscription \"NAME\"\n\nSUBSCRIPTION_ID=\"your-subscription-id\"\n\n# generate deployment credentials\naz ad sp create-for-rbac \\\n   --name \"example-dev-agent\" \\\n   --role contributor \\\n   --scopes /subscriptions/$SUBSCRIPTION_ID/resourceGroups/dev-example-rg \\\n   --sdk-auth\n```\n\nThe output of the command looks like the following:\n\n```bash\n{\n  \"clientId\": \"*******************************\",\n  \"clientSecret\": \"*******************************\",\n  \"subscriptionId\": \"*******************************\",\n  \"tenantId\": \"*******************************\",\n  \"activeDirectoryEndpointUrl\": \"https://login.microsoftonline.com\",\n  \"resourceManagerEndpointUrl\": \"https://management.azure.com/\",\n  \"activeDirectoryGraphResourceId\": \"https://graph.windows.net/\",\n  \"sqlManagementEndpointUrl\": \"https://management.core.windows.net:8443/\",\n  \"galleryEndpointUrl\": \"https://gallery.azure.com/\",\n  \"managementEndpointUrl\": \"https://management.core.windows.net/\"\n}\n```\n\nThe whole JSON fragment must be copied and configured as GitHub secret, to\nenable automated deployments in GitHub Workflows.\n\nNote that since the credentials are scoped on the subscription, it is necessary\nto define a secret for each environment. For the DEV environment, create a\nsecret such as:\n\n* _DEV_AZURE_CREDENTIALS_ --\u003e the name must match what is used in `.github/workflows/infrastructure.yml`\n\n#### Define a database password\n\nChoose, or generate, a database password for the DEV environment.\n\n**Tip:** use Python to generate passwords, instead of make them up.\nThe following script can be used to generate passwords of 60 characters:\n\n``` python\nimport string\nimport secrets\n\n\ndef generate_temp_password(length):\n    alphabet = string.ascii_letters + string.digits\n    return \"\".join(secrets.choice(alphabet) for i in range(length))\n\n\nif __name__ == \"__main__\":\n    print(generate_temp_password(60))\n```\n\nExample:\n\n```bash\n$ python3 genpass.py\nSIqtKXqB8Pu61fuobHHBD1USt1m7dRXYR43EUJQvsX7oa79c4G4OSeuo4FPa\n```\n\nThe database password configured in GitHub secrets will be used in\ntwo ways:\n\n* to configure the DB password when deploying the services in Azure\n* to run database migrations\n\n\u003e Note: a possible improvement is to configure different credentials:\n\u003e the dba to run migrations, and credentials with lower privileges for\n\u003e the application server.\n\nDuring development, it is convenient to have access to the database password of\nthe DEVELOPMENT environment, to work on the database structure using migrations\n(described later).\n\n---\n\n#### Configure database secrets\n\n```\npostgres+psycopg2://pgsqladmin@dev-examplepg:DATABASE_PASSWORD_HERE@dev-examplepg.postgres.database.azure.com:5432/example\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneoteroi%2Fvenezia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneoteroi%2Fvenezia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneoteroi%2Fvenezia/lists"}