chore: rearrage content; bring services to forefront
This commit is contained in:
parent
c2f004ef2a
commit
211f74e833
GPG key ID:
F8F50389936984FF
10 changed files with 15 additions and 119 deletions
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
+++
|
||||
title = "Getting Started"
|
||||
weight = 1
|
||||
sort_by = "weight"
|
||||
+++
|
||||
|
|
@ -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)
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
+++
|
||||
title = "Services"
|
||||
insert_anchor_links = "right"
|
||||
+++
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
+++
|
||||
title = "Updates"
|
||||
weight = 1
|
||||
weight = 90
|
||||
sort_by = "weight"
|
||||
+++
|
||||
|
|
|
|||
|
|
@ -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/),
|
||||
|
|
|
|||
|
|
@ -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/).
|
||||
|
|
|
|||
Loading…
Reference in a new issue