A fully functional demo app
showing interaction between an
Elixir (Phoenix) App
and Gogs server
using the
gogs package.
Step-by-step tutorial showing you how to do it yourself!
As software engineers we are
always learning new things.
When we learn,
we love having detailed docs and examples
that explain exactly how to get up-and-running.
@dwyl we write examples because we want them ourselves.
Comprehensive docs/tutorials
are a gift to our future selves and teammates. 🎁
They allow us to get up-to-speed
or remember what's going on
especially when returning to a project after a while.
We constantly refer back to them
and update them when required.
If you find them useful, please ⭐ the repo to let us know.
This project is a barebones demonstration
of using
gogs
in any Phoenix App.
It's intended 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.
This demo is intended 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!
Get help by opening an issue:
github.com/dwyl/gogs-demo/issues
Before you start, make sure you have the following installed:
Elixir: https://elixir-lang.org/install.html
New toElixir? see: github.com/dwyl/learn-elixirPhoenix: https://hexdocs.pm/phoenix/installation.html
New toPhoenix? see: github.com/dwyl/learn-phoenix-framework
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 gogs package.
mix phx.new app --no-ecto --no-dashboard --no-mailerWhen 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.compileChange into the directory of your newly created Phoenix app
cd appAnd start the app:
mix setup
mix phx.serverYou 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. 👌
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:
If you run the tests after the previous step:
mix testYou 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 failureThis 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 failuresWith that out-of-the way, let's crack on with the actual demo!
Open the
mix.exs
file,
locate the defp deps do section and add the following line:
{:gogs, "~> 1.0.1"},Once you've saved your mix.exs file,
e.g:
mix.exs#L55-L56
run:
mix deps.getWith the dependency installed, we can now setup.
To get the gogs package working in your Phoenix App,
you will need 4 environment variables.
See:
.env_sample
for a sample.
-
GOGS_URL- the domain where your Gogs Server is deployed, without the protocol,
e.g:gogs-server.fly.dev -
GOGS_ACCESS_TOKEN- the REST API Access Token See: gogs-server#connect-via-rest-api-https -
GOGS_SSH_PORT- The TCP port allocated to SSH on your Gogs Server, in our case it's:10022. -
GOGS_SSH_PRIVATE_KEY_PATH- absolute path to theid_rsafile on yourlocalhostorPhoenixserver instance.
If you're new to Environment Variables Please see: github.com/dwyl/learn-environment-variables
In our case our Gogs Server instance
is deployed to fly.io
at:
gogs-server.fly.dev
To understand how this was deployed,
please see:
github.com/dwyl/gogs-server
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
endInside 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}} =
Gogs.remote_render_markdown_html(org_name, repo_name, file_name)
render(conn, "index.html", html: raw_html)
endOpen 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:
At this point we have demonstrated
rendering a Markdown (README.md)
file hosted on a Gogs server
in a Phoenix app using the gogs package.
This is already cool,
but it doesn't even scratch the surface of what's possible!
At this point in the journey, you can either chose
The Dockerfile, fly.toml and config/runtime.exs files
can be used to deploy to Fly.io:
https://gogs-demo.fly.dev
