Bxio 0d8ab90c4b

2025-06-23 14:08:32 +01:00

13 KiB

Raw Blame History

Country Block

# _Whyy_? 🤷

A fully functional demo app showing interaction between an
Elixir (Phoenix) App and Gitea server using the gitea package.
Step-by-step tutorial showing you how to do it yourself!

Why? 🤷

We love having detailed docs and examples that explain exactly how to get up-and-running. 😍
Comprehensive docs/tutorials are a gift to our future selves and teammates. 🎁
We constantly refer back to them and update them as required.
If you find them useful, please ⭐ the repo to let us know.

What? 💭

This project is a barebones demonstration of using gitea in a Phoenix App.
Our intention is to be beginner-friendly and focus on showcasing one thing.

It can be used as the basis for another app or you can borrow chunks of setup/code.

Who? 👥

The demo is made for people of all Elixir/Phoenix skill levels.
Following all the steps in this example should take around 10 minutes.

If you get stuck, please don't suffer in silence!
It's probably something we didn't cover well enough, it's not you!
Get help by opening an issue: gitea-demo/issues

How? 💻

0. Prerequisites 📝

Before you start, make sure you have the following:

Elixir: https://elixir-lang.org/install.html
New to Elixir? see: github.com/dwyl/learn-elixir
Phoenix: https://hexdocs.pm/phoenix/installation.html
New to Phoenix? see: github.com/dwyl/learn-phoenix-framework
Access to a Gitea Server e.g: https://github.com/dwyl/gitea-server

1. Create a New `Phoenix` App 🆕

For this example, we are creating a basic Phoenix App without the live dashboard or mailer (email) or Ecto (Postgres database) because we don't need those components in order to showcase the gitea package.

mix phx.new app --no-ecto --no-dashboard --no-mailer

When prompted to install dependencies:

Fetch and install dependencies? [Yn]

Type y and hit the [Enter] key to install.

You should see something like this:

* running mix deps.get
* running cd assets && npm install && node node_modules/webpack/bin/webpack.js
* running mix deps.compile

Checkpoint: Working `Phoenix` App 🏁

Change into the directory of your newly created Phoenix app

cd app

And start the app:

mix setup
mix phx.server

You should see output similar to the following:

Generated app app
[info] Running AppWeb.Endpoint with cowboy 2.9.0 at 127.0.0.1:4000 (http)
[info] Access AppWeb.Endpoint at http://localhost:4000
[debug] Downloading esbuild from https://registry.npmjs.org/esbuild-darwin-64/-/esbuild-darwin-64-0.14.29.tgz
[watch] build finished, watching for changes...

That confirms the app is working.

Open your web browser to the URL: http://localhost:4000

You should see the default Phoenix home page:

So far so good. 👌

1.1 Clear out `page` template

Before we continue, let's do a clear out of the page template: lib/app_web/templates/page/index.html.heex

Open the file and delete the contents so it's completely empty.

With the Phoenix server running (mix phx.server), the page should refresh and now look like this:

1.2 Fix the Failing Test

If you run the tests after the previous step:

mix test

You will see output similar to the following:

1) test GET / (AppWeb.PageControllerTest)
    test/app_web/controllers/page_controller_test.exs:4
    Assertion with =~ failed
    code:  assert html_response(conn, 200) =~ "Welcome to Phoenix!"
    left:  "<!DOCTYPE html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\">\n \n<meta content=\"Am45cWxzFjAKCBcxXQAYHRUmaQZ5RjUFoYS35KUzdLCk3YBN-IQU8rs3\" name=\"csrf-token\">\n<title data-suffix=\" · Phoenix Framework\">App · Phoenix Framework</title> etc."
    right: "Welcome to Phoenix!"
    stacktrace:
      test/app_web/controllers/page_controller_test.exs:6: (test)

Finished in 0.1 seconds (0.08s async, 0.07s sync)
3 tests, 1 failure

This is because we removed the block of text that the test expects to be on the page. Easy enough to fix by updating the assertion in the test.

Open the test/app_web/controllers/page_controller_test.exs file and replace the line:

assert html_response(conn, 200) =~ "Welcome to Phoenix!"

With the following:

assert html_response(conn, 200) =~ "Get Started"

Once you save the file and re-run the tests mix test, they should pass:

...

Finished in 0.1 seconds (0.08s async, 0.06s sync)
3 tests, 0 failures

With that out-of-the way, let's crack on with the actual demo!

2. Add `gitea` to `deps` ⬇️

Open the mix.exs file in the root of your app folder, locate the defp deps do section and add the following line:

{:gitea, "~> 1.1.0"},

Once you've saved your mix.exs file, e.g: mix.exs#L55-L56

run:

mix deps.get

With the dependency installed, we can now setup.

3. Setup: Environment Variables 📝

To get the gitea package working in your Phoenix App, you will need 2 environment variables. See: .env_sample for a sample.

GITEA_URL - the domain where your gitea Server is deployed, without the protocol,
e.g: gitea-server.fly.dev
GITEA_ACCESS_TOKEN - the REST API Access Token Instructions for getting your token: gitea-server#connect-via-rest-api-https

3.1 Create your `.env` File

Create a new file in root the app project called .env. Copy the contents of the .env_sample file and paste it in the .env file.

Update the values of the environment variables with the real ones. Run the following command in your terminal (in the root of your project):

source .env

This will export the environment variables into your terminal environment.

If you're new to Environment Variables Please see: github.com/dwyl/learn-environment-variables

Context: `gitea` Server on Fly.io

In our case our gitea Server instance is deployed to fly.io at: gitea-server.fly.dev
To understand how this was deployed, please see: github.com/dwyl/gitea-server

4. Create Function to Interact with the `gitea` Repo

As noted in the first step above, the homepage of our app is the default Phoenix homepage.

In this section we're going to change that!

Open the lib/app_web/controllers/page_controller.ex file. You should see the following:

defmodule AppWeb.PageController do
  use AppWeb, :controller

  def index(conn, _params) do
    render(conn, "index.html")
  end
end

Inside the file, replace the index/2 function with the following:

def index(conn, _params) do
  org_name = "demo-org"
  repo_name = "hello-world"
  file_name = "README.md"
  {:ok, %{body: raw_html}} =
    Gitea.remote_render_markdown_html(org_name, repo_name, file_name)
  render(conn, "index.html", html: raw_html)
end

This updated function specifies 3 variables:

org_name: the organisation/owner name for a repository on the gitea server.
repo_name: repository name on the gitea server
file_name: the Markdown file we want to render as HTML.

It invokes the Gitea.remote_render_markdown_html/3 function that renders the Markdown contained in the file_name as HTML which can be rendered on a page.

5. Update the Template to Display the Text

Open the file: lib/app_web/templates/page/index.html.heex

Insert the following line:

<%= raw(@html) %>

Now you will see the Markdown rendered in the template:

Recap!

At this point we have demonstrated rendering a Markdown (README.md) file hosted on a gitea server in a Phoenix app using the gitea package. This is already cool, but it doesn't even scratch the surface of what's possible!

Let's deploy the app to Fly.io so that we can show our progress to other people in our team!

6. Deploy to Fly.io 🚀

We have simplified the steps to deploy a Phoenix App to Fly.io for the sake of brevity. If you are totally new to Fly.io in general or deploying a Phoenix App specifically, Please see: https://fly.io/docs/speedrun/

The Dockerfile, fly.toml and config/runtime.exs files can be used to deploy to Fly.io, e.g: https://gitea-demo.fly.dev

The Dockerfile is inspired by: https://github.com/fly-apps/hello_elixir/blob/main/Dockerfile

Deployment Instructions:

mix release.init

Borrow the init from an app that we've deployed before. e.g: 9bb69a5736

Initialize the Fly.io config:

fly launch

Select the relevant options.

Setup the required environment variables on Fly using the CLI:

flyctl secrets set GITEA_URL=gitea-server.fly.dev
flyctl secrets set GITEA_ACCESS_TOKEN=your-token-here
flyctl secrets set SECRET_KEY_BASE=https://hexdocs.pm/phoenix/Mix.Tasks.Phx.Gen.Secret.html

Deploy:

flyctl deploy

You should see:

Release v1 created
Monitoring Deployment

1 desired, 1 placed, 1 healthy, 0 unhealthy [health checks: 1 total, 1 passing]

And when you visit the App URL in your browser: https://gitea-demo.fly.dev/

Conclusion!

That concludes our basic demo. What we covered:

Setup a new Phoenix App
Added the gitea dependency
Added the required environment variables
Created code to render a markdown file using the Gitea.remote_render_markdown_html/3 function.
Deployed the demo to Fly.io!

If you found this demo/tutorial useful, please ⭐ the repo to let us know.

Thank you!

But wait! There's more!! See: Part Two!

13 KiB Raw Blame History