From 211f74e833f26628dad514edc55448f03e33ef09 Mon Sep 17 00:00:00 2001 From: Aravinth Manivannan Date: Sun, 1 Oct 2023 23:33:14 +0530 Subject: [PATCH] chore: rearrage content; bring services to forefront --- .../interface.md => Interface/_index.md} | 14 +++--- .../northstar.md => Northstar/_index.md} | 5 ++- content/getting-started/_index.md | 5 --- content/getting-started/events.md | 22 ---------- content/getting-started/how.md | 43 ------------------- content/getting-started/services.md | 35 --------------- content/services/_index.md | 4 -- content/updates/_index.md | 2 +- content/updates/december2020.md | 2 +- content/updates/november2020.md | 2 +- 10 files changed, 15 insertions(+), 119 deletions(-) rename content/{services/interface.md => Interface/_index.md} (94%) rename content/{services/northstar.md => Northstar/_index.md} (83%) delete mode 100644 content/getting-started/_index.md delete mode 100644 content/getting-started/events.md delete mode 100644 content/getting-started/how.md delete mode 100644 content/getting-started/services.md delete mode 100644 content/services/_index.md diff --git a/content/services/interface.md b/content/Interface/_index.md similarity index 94% rename from content/services/interface.md rename to content/Interface/_index.md index 77f0ae0..d190d2f 100644 --- a/content/services/interface.md +++ b/content/Interface/_index.md @@ -9,7 +9,7 @@ Interface is a service that acts as a connecting end of the bridge, listening in for Notifications from a particular forge repository. These notifications, which may be in the form of a Comment, Issue, or Pull Request, -are then further defined into [Events](@/getting-started/events.md) to create +are then further defined into Events to create a workable unit set, that the interface can use to translate operations from one forge to another forge. @@ -22,10 +22,11 @@ The procedure of the Notification-Event Translation System, works as follows, ## Setting up the Development Environment In order to test out and utilise the Northstar lookup service, we will need to set -up an interface to be run on the local machine. There are a few configuration +up an interface to be run on the local machine. There are a few configuration changes that must be made for the interface to be recognized by the lookup service. Changes to the `config/settings.toml`, + ```toml [default.system] northstar = "http://computer.domain.com:port" @@ -35,8 +36,9 @@ url = "http://computer.domain.com:port" ``` Note that the port assigned to the interface and northstar must not already be in -use by another application/service, and that you can find out the hostname for +use by another application/service, and that you can find out the hostname for your system through the following command, + ```sh hostname --fqdn ``` @@ -57,12 +59,14 @@ username = "fluxer101" password = "flux101" ``` -Note that the API key in Gitea is known as an access token, one which can be +Note that the API key in Gitea is known as an access token, one which can be generated [here](https://gitea.com/user/settings/applications). ## FAQ + ### Why does an integrity error show up? -As ForgeFlux's Interface is an actively developing project, there are a few + +As ForgeFlux's Interface is an actively developing project, there are a few errors that are caused by an upgrade to the database, in which case integrity errors are bound to pop up. In this case, remove the `instance/` directory where the database for the service would be stored, to rebuild it the next time the application is run. diff --git a/content/services/northstar.md b/content/Northstar/_index.md similarity index 83% rename from content/services/northstar.md rename to content/Northstar/_index.md index 49ab55a..62cd02a 100644 --- a/content/services/northstar.md +++ b/content/Northstar/_index.md @@ -1,6 +1,7 @@ +++ title = "Northstar" -weight = 40 +insert_anchor_links = "right" +weight = 50 +++ # Northstar @@ -8,7 +9,7 @@ weight = 40 Northstar is a lookup service, which acts as a source of information for interfaces which hold particular forge information. -An [Interface](@/services/interface.md) connects and looks +An [Interface](@/Interface/_index.md) connects and looks through an instance of Northstar, to find the appropriate the forge information that it seeks. diff --git a/content/getting-started/_index.md b/content/getting-started/_index.md deleted file mode 100644 index 0acd709..0000000 --- a/content/getting-started/_index.md +++ /dev/null @@ -1,5 +0,0 @@ -+++ -title = "Getting Started" -weight = 1 -sort_by = "weight" -+++ diff --git a/content/getting-started/events.md b/content/getting-started/events.md deleted file mode 100644 index 297b32b..0000000 --- a/content/getting-started/events.md +++ /dev/null @@ -1,22 +0,0 @@ -+++ -title = "Events" -weight = 40 -+++ - -# Events - -Events are those operations that are performed on the Forge side, -such as Pull Requests, and Issues. - -These events are operations of their own, and are handled within Interface -through Notifications. - -The flow of processing an operation in the forge is done as follows, - -1. We poll for Notifications through the [Job Runner](https://github.com/forgeflux-org/interface/blob/master/interface/runner/runner.py). -2. Proceed to send over this Notification to the Events Endpoint, where the Notification is parsed, and processed. -3. After identification, it is converted into a event, PR or Issue. - -## References - -- Events Endpoint :: [Info](https://github.com/forgeflux-org/interface/blob/master/interface/runner/events.py) diff --git a/content/getting-started/how.md b/content/getting-started/how.md deleted file mode 100644 index 00acad4..0000000 --- a/content/getting-started/how.md +++ /dev/null @@ -1,43 +0,0 @@ -+++ -title = "How does it work?" -weight = 40 -+++ - -# How does it work? - -Bridges connect people, and so does ForgeFlux! - -## Interface - -The bridging component in ForgeFlux is called Interface. - -[Interfaces](@/services/interface.md) are programs that run on either -side of the bridge, i.e, a bridge requires the participation of two -interfaces. Currently, Interfaces bridge the following operations: - -- Pull Requests -- Issues -- Comments - -An Interface implementation for a software forge is able to -talk to the forge's API and speak [ActivityPub -protocol](https://activitypub.rocks/) for server-to-server -communications. This architecture makes it possible to implement an -Interface for any forge setup. - -## Northstar - -Since Interfaces run external to the forges, a method to find Interfaces -that service forges was required. - -[Northstar](@/services/northstar.md) is a discovery service that maps an -Interface and the forge that it services. It acts very similar to DNS, -except instead of querying host names with intent to find corresponding -IP address, Northstar is queried with the forge's host name to discover -the Interfaces that service it. - -## Resources - -- - [ecosystem-architecture](https://github.com/forgeflux-org/spec/blob/master/rfc/1-ecosystem-architecture/1-ecosystem-architecture.md): - describes basic architecture and terminology used in ForgeFlux diff --git a/content/getting-started/services.md b/content/getting-started/services.md deleted file mode 100644 index 82a54ab..0000000 --- a/content/getting-started/services.md +++ /dev/null @@ -1,35 +0,0 @@ -+++ -title = "Services" -weight = 15 -+++ - -# Services -The services that are currently in active development are Northstar, and Interface. -However, here's a few more details about them. - -## Northstar -- Repository :: [Source Code](https://github.com/forgeflux-org/northstar) -- OpenAPI :: [OpenAPI Specification](https://northstar.forgeflux.org/docs/openapi/) - -ForgeFlux allows for multiple interfaces to be run against a single software forge. -Also, the protocol is flexible enough to support multiple types of software forges(GitLab, GitHub, etc). -The protocol's decentralised nature makes it impossible to create a constant record of which interfaces service forges. - -So we created a discovery service which stores records of interfaces and the forges they service. -This is very similar to the way DNS works. -In DNS, hostname is resolved to IP address. - -Here, software forge URL is resolved to URLs of [interfaces](https://github.com/forgeflux-org/interface) that service the queried forge. - -For an extensive view on Northstar, please check [Northstar::Detailed](@/services/northstar.md) - -## Interface -- Repository :: [Source Code](https://github.com/forgeflux-org/interface) -- OpenAPI :: [OpenAPI Specification](https://github.com/forgeflux-org/interface/tree/master/docs/openapi) - -Developing Free Software is about liberating users and giving them total control over how the programs they run should work. -It's only fair that developers of such software enjoy the same levels of liberty. - -ForgeFlux is an attempt to enable federation for major software forges (GitLab, GitHub, Gitea, Source Hut, etc) entirely in API-space. -We believe our API-space implementation will allow for more organic growth as it will not require any involvement from the forge developers. - diff --git a/content/services/_index.md b/content/services/_index.md deleted file mode 100644 index ab670fd..0000000 --- a/content/services/_index.md +++ /dev/null @@ -1,4 +0,0 @@ -+++ -title = "Services" -insert_anchor_links = "right" -+++ diff --git a/content/updates/_index.md b/content/updates/_index.md index ca1ebad..143e8ee 100644 --- a/content/updates/_index.md +++ b/content/updates/_index.md @@ -1,5 +1,5 @@ +++ title = "Updates" -weight = 1 +weight = 90 sort_by = "weight" +++ diff --git a/content/updates/december2020.md b/content/updates/december2020.md index ba1f3ea..d125fb3 100644 --- a/content/updates/december2020.md +++ b/content/updates/december2020.md @@ -6,7 +6,7 @@ weight = 40 # December 2020 ## Northstar -As the development on [Northstar](@/services/northstar.md) nears the completion phase, +As the development on [Northstar](@/Northstar/_index.md) nears the completion phase, updates on it have slowed down, and the only updates that were made during this stage mostly comprises of configuration updates. These updates were mostly related to bootstrapping [DynaConf](https://www.dynaconf.com/), diff --git a/content/updates/november2020.md b/content/updates/november2020.md index 32c000d..7f2e8f0 100644 --- a/content/updates/november2020.md +++ b/content/updates/november2020.md @@ -16,7 +16,7 @@ A Notification-Event Translation Mechanism was set up. 1. Northstar functionality was integrated into Interface, and tests were set up to ensure that it could be contacted through Interface's methods. 2. A locking mechanism was set up for concurrent operations on Git utilizing [Sled](https://sled.rs/). 3. Implementations of a basic job runner was set up to mimic retrieving requests from Forges, through periodically retrieving notifications. -4. The endpoints for notifications was subsequently set up, and responses to these Notifications were termed as [events](@/getting-started/events.md). +4. The endpoints for notifications was subsequently set up, and responses to these Notifications were termed as events. 5. The endpoints for processing these events were then created. Shifted over the configuration management to [Dynaconf](https://www.dynaconf.com/).