Skip to content

README.md

Latest commit

 

History

History
152 lines (111 loc) · 7.68 KB

README.md

File metadata and controls

152 lines (111 loc) · 7.68 KB

OpenGraph Catalog

This is a Phoenix application that provides a catalog of OpenGraph metadata for various URLs. Specifically, it fetches and displays the OpenGraph image tag from the provided URL using the OpenGraph library.

Main components:

  • LiveViews: The OgCatalogWeb.OpenGraphObjectLive.Index module handles the user interface and interactions. It allows users to input a URL and displays the corresponding OpenGraph image with real-time updates.
  • Oban: Oban is a robust background job framework which can use PostgreSQL for storage. The OgCatalog.Workers.ProcessPageUrl module is responsible for processing page URLs and fetching the OpenGraph metadata in the background. It uses Oban to manage background jobs and delegates the actual fetching/parsing to OgCatalog.Services.OpenGraphService, ensuring that the fetching process does not block the main application.
  • Phoenix PubSub: Phoenix PubSub is used to broadcast updates to the LiveView when new OpenGraph images are fetched, allowing for real-time updates without requiring a page refresh.
  • Ecto: Ecto is used for database interactions. The OgCatalog.OpenGraphObjects context manages the OpenGraph objects stored in the database, allowing for efficient querying and data manipulation.
  • OpenGraph Library: The OpenGraph library is utilized to fetch and parse OpenGraph metadata from the provided URLs. It simplifies the process of extracting the necessary information, such as the image tag, from the web pages.
  • Error Handling: The application includes error handling mechanisms to manage cases where the provided URL is invalid or when the OpenGraph metadata cannot be fetched. This ensures a smooth user experience and prevents crashes.
  • Database: PostgreSQL is used as the database for storing OpenGraph objects. The application includes migrations to set up the necessary tables and schemas.

Basic flow:

  1. The user enters a URL in the LiveView interface.
  2. The application validates the URL while the user types.
  3. The user submits the URL.
  4. The application creates a new OpenGraphObject in the database and enqueues an Oban job to process the URL and fetch the OpenGraph image.
  5. The Oban worker pulls the job, fetches the page from the provided URL using the OpenGraph library. If the URL is valid and the metadata is successfully fetched, it extracts the og:image URL.
  6. Once the og:image URL is fetched, the Oban worker updates the OpenGraphObject in the database and broadcasts the update to the LiveView.
  7. The LiveView receives the update and displays the OpenGraph Image to the user.
  8. If the URL is invalid or the OpenGraph metadata cannot be fetched, appropriate error messages are displayed to the user.

Missing features and future improvements

  1. User Authentication: Add user authentication to allow users to save and manage their OpenGraphObjects.
  2. Pagination: Implement pagination for the list of OpenGraphObjects to improve performance and user experience.
  3. Search Functionality: Add search functionality to allow users to find specific OpenGraphObjects, in their history, based on URL.
  4. URL Shortening: Integrate a URL shortening service to handle long URLs more effectively.
  5. Enhanced Error Handling: Improve error handling to provide more detailed feedback to users when fetching OpenGraph metadata fails.

Prerequisites

  • Elixir ~> 1.19
  • Erlang/OTP ~> 28.3
  • PostgreSQL v14 or higher
  • Docker (optional, for running tests and the app in a container). You can find the instructions at the end of this README

Install Elixir and Erlang via ASDF

You can use any version manager. ASDF simplifies the process since it can be used to manage multiple runtimes versions. If you don't have Elixir and Erlang installed, you can follow these steps to set them up using ASDF:

Install ASDF:

The fastest way to install ASDF in macOS is with Homebrew.

Follow the instructions provided by Homebrew at the end of the installation to set up your shell.

brew install asdf

Add the Elixir and Erlang plugins:

asdf plugin add erlang
asdf plugin add elixir

Install PostgreSQL v14 via HomeBrew

Follow the instructions provided by Homebrew to start the PostgreSQL service.

brew install postgresql@14

Create the DB users for test and development

psql -c "CREATE ROLE og_catalog_test WITH LOGIN SUPERUSER CREATEDB PASSWORD 'og_catalog_test';"
psql -c "CREATE ROLE og_catalog_dev WITH LOGIN SUPERUSER CREATEDB PASSWORD 'og_catalog_dev';"

Create the databases for the test and dev environments

createdb -O og_catalog_test og_catalog_test
createdb -O og_catalog_dev og_catalog_dev

Set up the project locally

  1. Clone the repository:
git clone git@github.com:venriq/og_catalog.git
  1. Switch to the project directory and install the required Elixir and Erlang versions using ASDF:
cd og_catalog
asdf install

asdf install will read the .tool-versions file and install the specified versions of Elixir and Erlang.

  1. Install the project dependencies and run the migrations to set up the database:
mix deps.get
mix ecto.migrate
  1. Run the tests to ensure everything is set up correctly:
mix test

Run the application in development mode with live reloading:

mix phx.server

This will enable live reloading, allowing you to see changes in real-time as you develop the application. Once the server is running, you can access the application by navigating to OpenGraphObjects in your web browser.

Using Docker

The project includes a Dockerfile and a Makefile to facilitate running the application (dev) and tests in a Docker container. This allows for a consistent environment across different machines and simplifies the setup process. You can use any Docker-compatible environment to build and run the application and tests. The Makefile provides convenient targets for both development and testing purposes. If you choose to use Docker, make sure you have Docker installed and running on your machine before executing the commands provided in the sections below. There are multiple tools to install Docker, one I recommend is OrbStack for macOS, which provides a seamless Docker experience with native performance.

Running the tests in a docker container

You can run the tests in a docker container to ensure a consistent environment. The Makefile includes a test target to run the tests inside a Docker container. To run the tests in a Docker container, execute the following command from the project root:

make test

This command will build the Docker image and run the tests inside the container, providing a clean and isolated environment for testing. Make sure you have Docker installed and running on your machine before executing the command. This setup ensures that the tests are executed in a consistent environment, regardless of the host machine's configuration.

Running the app in a docker container

You can also run the application locally in a Docker container for development purposes. The Makefile includes a dev target to run the application inside a Docker container. To run the application in a Docker container, execute the following command from the project root:

make dev

This command will build the Docker image and start the application inside the container, allowing you to develop and test the application in a consistent environment. Make sure you have Docker installed and running on your machine before executing the command. Once the container is running, you can access the application by navigating to OpenGraphObjects in your web browser.
⚡