.'.'
      .'-'.
  .  (  o O)
   \_ `  _,   _
-.___'.) ( ,-'
     '-.O.'-..-..       octopus git web frontend
 ./\/\/ | \_.-._
        ;
     ._/


A git web frontend that wants to hug your code.


Why?
----

This is a very good first question, and one that I think is important
to answer before getting more into the project.  Whenever I brought up
this project during the creation of it, most people would react with
"have you tried...", followed by some git web software, such as
gitlab, gittea, and many many more.  But there is a reason why I stuck
with octopus and the design ideas I had for it.

Fundamentally it's about decentralisation.  The internet is a pretty
big place (allegedly), but a lot of the services that people use are
very centralised by a single company or even server.  If this company
or server goes away, so does valuable knowledge.  There are many ways
to create more decentralised systems, and one aspect of this for me,
is code repos.

Git is by it's nature decentralised, meaning that it doesn't require
an "upstream" or canonical server to function.  Theoretically you
could use git to exchange code patches with people without the
internet.  Yet, a lot of people's perception of git is one that is
dictated by the workflows on github and gitlab: centralised into a
single service.  Many git web frontends mirror this workflow, because
after all, it is what people want and love.

However, it has some flaws (which would take too long to elaborate
here), and for octopus I had something else in mind.  Instead of
replicating the same mistakes, I took much more inspiration from cgit,
which is used and loved by many today.  octopus is a re-imagining of
cgit, trying to improve the UX and maintainability where possible,
adding new features, but mostly staying true to it's core: a simple
git web service, that doesn't lock you into a vendor, or server.


Configuration
-------------

octopus is easy to configure and run, even on systems that don't give
you priviledged system access.  The main server binary is configured
primarily with a few environment variables, and an app config.

+ OCTOPUS_CONFIG should contain the path of the main configuration

+ OCTOPUS_SSL_KEY can optionally be set to the path of a certificate key

+ OCTOPUS_SSL_CERT can optionally be set to the path of a certificate


The main configuration file is written in yaml, and outlines things
like the application domain, repo paths, and added modules.  Because
octopus is vory modular, you can only depend on certain features.


---
app_path: git.octopus.example
port: 8080
handle_ssl: false
cache_path: /var/cache/octopus
repo_path: /var/lib/octopus/repos
repo_discovery: false  # Disables automatic config loading from repo_path
                       # and instead let's you set a static set of repos
                       # in the section below
repos:
  - octopus:
      description: "🐙 It's a water animal"
      category: "/"
  - libkookie:
      description: "My personal nix expressions"
      category: "/nix"