{"id":30617501,"url":"https://github.com/qaware/study-project-url-shortener","last_synced_at":"2025-08-30T10:48:23.266Z","repository":{"id":279424766,"uuid":"928260921","full_name":"qaware/study-project-url-shortener","owner":"qaware","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-25T13:23:47.000Z","size":460,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-19T23:29:05.499Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qaware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-06T10:41:25.000Z","updated_at":"2025-02-25T08:33:11.000Z","dependencies_parsed_at":"2025-02-25T14:36:32.705Z","dependency_job_id":"3edfa072-4458-45a8-894d-8c7b8549c017","html_url":"https://github.com/qaware/study-project-url-shortener","commit_stats":null,"previous_names":["qaware/study-project-url-shortener"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/qaware/study-project-url-shortener","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fstudy-project-url-shortener","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fstudy-project-url-shortener/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fstudy-project-url-shortener/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fstudy-project-url-shortener/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qaware","download_url":"https://codeload.github.com/qaware/study-project-url-shortener/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qaware%2Fstudy-project-url-shortener/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272839679,"owners_count":25001862,"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","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-08-30T10:48:22.327Z","updated_at":"2025-08-30T10:48:23.251Z","avatar_url":"https://github.com/qaware.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# UrlShortener\n\nThis project demonstrates a URL shortener application built with Angular and Python. The project is intended for educational and demonstrative purposes, providing a hands-on example of how to work with Angular, Python, Docker and some further tools (Taskfile, ...).\n\n## Requirements\n\nTo use this project locally, the following dependencies have to be installed:\n\n- Node.js version 22 including npm\n- Python version 3.13\n- Taskfile version 3.40\n- Docker\n\n## Tasks\n\nThe task for you is split into two categories:\n\n1. Developing the application itself\n2. Deploying it\n\nBut BEFORE you change and commit any code, create a new Git branch with a name in the format `student/your-name` by executing command:\n\n```bash\ngit checkout -b \u003cyour-branch-name\u003e\n```\n\nFor more information about Git, visit section [Git](#git).\n\n### 1. Application Development\n\nThe application which is to be completed is an URL shortener. A URL shortener is a tool that converts a long URL into a shorter, more manageable link. When entered, the shortened URL redirects users to the original destination, often while tracking click analytics.\n\nIn our scenario, a user can enter a long URL into an input field, which is then converted into a shorter URL. That shorter URL consists of the base-URL of your website, where the UI can be viewed (e.g. \"localhost\"), and a path appendix.\n\nA short example:\n\n```bash\nhttp://base-url/appendix\n```\n\nStore the appendix key on the backend. This key serves as a shorthand for a full URL. When a user enters `http://base-url/appendix` in their browser, they will be redirected to the associated full URL. For example, the full URL might be “www.youtube.com”.\n\n#### Primary Task\n\nThe backend of the application is not complete yet. The required endpoints which are called by the frontend are not implemented (take a look at file `src/backend/main.py`).\n\nThe following two Python-endpoints (in file `src/backend/main.py`) have to be implemented for this task:\n\n- `shorten_url`\n- `get_long_url`\n  \nYou can test the functionality of those endpoints locally by utilizing the Taskfile task `execute-shorten-local` to shorten an URL and task `execute-get-long-url-local` to retrieve the original long version of a short URL.\n\nAlso, there already are working test-endpoints within `main.py` with corresponding test-tasks (enter `task` in the terminal to list all tasks) which you can use to get a better understanding of how the unimplemented endpoints could be implemented.\n\n#### Optional QR Code Implementation\n\nOptionally, the QR-Code endpoint `get_qr_code` can be implemented. It should take a URL parameter, generate a QR code from it, encode that QR code as a base64 string, and then return the result.\n\n### 2. Platform Engineering\n\nWe want to deploy our application to the cloud somewhere, preferably somewhere more permanent than a temporary Cloud IDE instance. \n\nFor the purposes of our workshop, we'll be deploying containers as Google Cloud Run services.\n\nFirst, we should verify that our application is running as expected locally using Docker (ctrl+f \"docker build\" and \"docker run\" below, and that we can access the application on localhost:80 (or is it localhost:8080?)).\n\nNext, we'll push our image to our Google \"Artifact Registry\" (GAR), which is a home for container images. The address of our GAR is stored in the environment variable GAR.\n\n```bash\ndocker build $GAR/my-unique-image-name .\ndocker push $GAR/my-unique-image-name\n```\n\nThen, we'll create a Google Cloud Run service based on our image.\n\n```bash\ngcloud run deploy --image $GAR/my-unique-image-name --allow-unauthenticated --port 8080\n```\n\nExtra credit: Can you figure out \n1. What images have been pushed to the registry? (see https://cloud.google.com/sdk/gcloud/reference/artifacts)\n1. What Cloud Run Services are running in our project? Are any of them broken?\n\nFinally, let's create a short URL for our service:\n```bash\ngcloud beta run domain-mappings create --service my-service-name --domain=my-fancy-domain.0qa.pw\n```\n(Warning: This takes at least 15 minutes).\n\n## Usage\n\nThis section contains basic information about how the project shall be used.\n\nYou can list predefined tasks by running `task` in the terminal. This lists all defined Taskfile tasks.\n\n### Git\n\nGit is a distributed version control system that allows you to track changes in your code, collaborate with others, and maintain a complete history of your project. This allows, for example, to come back to a previous code version late ron. It is an essential tool for modern software development. Here are some basic commands and best practices to get you started:\n\n#### Create a Branch\n\nAlways create a new branch for your work to keep changes isolated:\n\n```bash\ngit checkout -b some-branch-name/comes-also-with-slashes\n```\n\n#### Make Changes and Commit\n\nAfter editing files, stage and commit your changes with a meaningful message:\n\n```bash\ngit add .\ngit commit -m \"Describe your changes here\"\n```\n\n#### Push Your Branch\n\nShare your branch with others or just back up your changes by pushing it to the remote repository:\n\n```bash\ngit push origin your-branch-name\n```\n\n#### Update branch\n\nGet the newest version of your branch:\n\n```bash\ngit pull origin main\n```\n\n#### List Commits\n\nYou might want to list commits to apply actions based on previous commits (like resetting to a specific commit):\n\n```bash\ngit log\n```\n\n#### Resetting a Branch to a Commit\n\nIf you might have implemented some trash and want to reset to an earlier state:\n\n```bash\ngit reset \u003ccommit-hash\u003e\n```\n\nThe `commit-hash` can be taken from listed commits. See [List Commits](#list-commits).\n\n### Build \u0026 Run the Application\n\nDuring application development, multiple environments are typically established — one or more for testing and development, and another for production. The “production” environment refers to the configuration in which the final end user interacts with the application.\nAlso, the production build of the application includes optimizations and security steps which make sure that the application runs smoothly. The development-build on the other hand, is less performant but offers advantages such as easier debugging.\n\nDistinct workflows are defined for each stage — development and production — to build and run the application:\n\n#### Development\n\nFor development, the application runs in your local environment. Also, the build step of the application is skipped, as it automatically re-builds every time a change in the code space is recognized.\n\nBoth the frontend and backend have to be running if you want to test your application in a whole. Execute the following commands to start both:\n\n- `task run-frontend-dev` to start the frontend\n- `task run-backend-dev` to start the backend\n\nExecute the commands in separate terminals since the daemons are not attached by default.\n(Opening a new terminal in VS Code or Github Codespaces is possible by pressing `Cmd + Shift + P` and then selecting \"Terminal: Create new Terminal\")\n\nAfter the application is running, the UI can be viewed via the browser by visiting `http://localhost:80` and the backend can be reached via `http://localhost:8000`.\n  \n#### Production\n\nFor production, the application-image will be running within a Docker container on the machine of your choice.\n\n##### Docker Images and Container\n\nA Docker image is like a recipe or blueprint. It contains everything needed to run an application: the code, libraries, environment variables, and configuration files. However, the image itself is just a static file. It doesn’t run or do anything on its own.\n\nA Docker container, on the other hand, is what you get when you “bake” the image into a running instance. Think of the image as a recipe for a cake, and the container as the actual cake you bake. You can use the same recipe (image) to bake many cakes (containers), and each one can run independently. Containers are the live, running environments where your application is executed, and they can have temporary storage and runtime state.\n\n#### Using Docker\n\n##### Building Images\n\nTo build the Docker image, execute the following command:\n\n```bash\ndocker build -t url-shortener .\n```\n\nThis command utilizes the `./Dockerfile` to create an image and tag it (`-t`) with the name \"url-shortener\".\n\n##### Run Container\n\nThat image can then be used to start a docker container using the command\n\n```bash\ndocker run -d -p 8080:8080 -p 8000:8000 --name url-shortener url-shortener\n```\n\nBelow is a brief explanation of each part of the command.\n\n- `-d`: Runs the container in detached mode, meaning that the terminal remains available\n- `-p \u003csome-port\u003e:\u003csome-(different-)port\u003e`: Maps a specific port on your host machine to a different port inside the Docker container, allowing you to access the containerized service from outside the container. Essentially, any traffic sent to the host’s `\u003chost-port\u003e` will be forwarded to the container’s `\u003ccontainer-port\u003e`.\n- `--name url-shortener`: Applies the name \"url-shortener\" to the container. That allows us to easily reference the container later on when we want to apply actions to it, like stopping the container or viewing its logs.\n\n##### Stop Container\n\nTo stop a container, execute the following command:\n\n```bash\ndocker stop \u003ccontainer-name\u003e\n```\n\nThe container-name references to the name we previously assigned when starting a docker container.\nKeep in mind that only ONE container with the same name can exist at the same time. To re-start your application, you first have to stop AND delete the container.\n\n##### Delete Container\n\nTo delete a container, execute the following command:\n\n```bash\ndocker rm \u003ccontainer-name\u003e\n```\n\n##### Restart stopped Container\n\nIf you might want to restart a previously stopped container, you can do that by executing command:\n\n```bash\ndocker start \u003ccontainer-name\u003e\n```\n\n##### Get information about Container\n\nThere are multiple ways to get information about running container.\nYou can access logs of a container by executing command\n\n```bash\ndocker logs \u003ccontainer-name\u003e\n```\n\nYou can also attach to the command line of a running container by executing command\n\n```bash\ndocker exec -it \u003ccontainer-name\u003e sh\n```\n\nHere, `sh` defines the kind of terminal you want to use. In that case \"shell\".\n\nTo depict the overall stats of all running containers, regarding usage of memory and cpu computing power, execute command\n\n```bash\ndocker stats -a\n```\n\n### Testing the Backend\n\nThe following Taskfile tasks have been designed to test the endpoints for shortening URLs and retrieving the corresponding long version of a previously shortened URL:\n    - `task execute-shorten-local`: Shortens an URL. To shortened you presonal URL, update the corresponding task within file `Request.yml` by replacing the string `\u003cyour-long-url\u003e` with your URL.\n    - `task execute-get-long-url-local`: Change the task within file `Request.yml` to use a previously shortened URL. For that, simply replace the string `\u003cshortened-url\u003e` with the shortened code.\n\n### Github Codespace\n\nA working environment for Github Codespaces is defined within `./.devcontainer`. It includes all listed requirements in section [Requirements](#requirements)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqaware%2Fstudy-project-url-shortener","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqaware%2Fstudy-project-url-shortener","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqaware%2Fstudy-project-url-shortener/lists"}