Git-Mirrors
/
veilid
mirror of https://gitlab.com/veilid/veilid.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Cleaned up .md files syntax 

Used the VScode markdownlint utility to make the syntax and
formatting of multuple .md files so that they are more correct.
This commit is contained in:
TC Johnson 2023-09-12 08:43:09 -05:00
parent 8800960af6
commit 84e3303cec
No known key found for this signature in database
5 changed files with 116 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
DEVELOPMENT.md
View File

@ -1,8 +1,9 @@
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md)
# Veilid Development
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md)
## Introduction
This guide covers setting up environments for core, Flutter/Dart, and Python development. See the relevent sections.
## Obtaining the source code
@ -20,14 +21,15 @@ itself, Ubuntu or Mint. Pull requests to support other distributions would be
welcome!
Running the setup script requires:
* Android SDK and NDK
* Rust
You may decide to use Android Studio [here](https://developer.android.com/studio)
to maintain your Android dependencies. If so, use the dependency manager
You may decide to use Android Studio [here](https://developer.android.com/studio)
to maintain your Android dependencies. If so, use the dependency manager
within your IDE. If you plan on using Flutter for Veilid development, the Android Studio
method is highly recommended as you may run into path problems with the 'flutter'
command line without it. If you do so, you may skip to
method is highly recommended as you may run into path problems with the 'flutter'
command line without it. If you do so, you may skip to
[Run Veilid setup script](#Run Veilid setup script).
* build-tools;33.0.1
@ -38,7 +40,6 @@ command line without it. If you do so, you may skip to
#### Setup Dependencies using the CLI
You can automatically install the prerequisites using this script:
```shell
@ -88,20 +89,21 @@ cd veilid-flutter
./setup_flutter.sh
```
### macOS
Development of Veilid on MacOS is possible on both Intel and ARM hardware.
Development requires:
* Android Studio
* Android Studio
* Xcode, preferably latest version
* Homebrew [here](https://brew.sh)
* Android SDK and NDK
* Rust
You will need to use Android Studio [here](https://developer.android.com/studio)
You will need to use Android Studio [here](https://developer.android.com/studio)
to maintain your Android dependencies. Use the SDK Manager in the IDE to install the following packages (use package details view to select version):
* Android SDK Build Tools (33.0.1)
* NDK (Side-by-side) (25.1.8937393)
* Cmake (3.22.1)
@ -121,7 +123,7 @@ export PATH=\$PATH:$HOME/Library/Android/sdk/platform-tools
EOF
```
#### Run Veilid setup script
#### Run Veilid setup script (macOS)
Now you may run the MacOS setup script to check your development environment and
pull the remaining Rust dependencies:
@ -130,7 +132,7 @@ pull the remaining Rust dependencies:
./dev-setup/setup_macos.sh
```
#### Run the veilid-flutter setup script (optional)
#### Run the veilid-flutter setup script (optional) (macOS)
If you are developing Flutter applications or the flutter-veilid portion, you should
install Android Studio, and run the flutter setup script:
@ -144,13 +146,13 @@ cd veilid-flutter
For a simple installation allowing Rust development, follow these steps:
Install Git from https://git-scm.com/download/win
Install Git from <https://git-scm.com/download/win>
Install Rust from https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe
Install Rust from <https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe>
Ensure that protoc.exe is in a directory in your path. For example, it can be obtained from https://github.com/protocolbuffers/protobuf/releases/download/v24.2/protoc-24.2-win64.zip
Ensure that protoc.exe is in a directory in your path. For example, it can be obtained from <https://github.com/protocolbuffers/protobuf/releases/download/v24.2/protoc-24.2-win64.zip>
Ensure that capnp.exe is in a directory in your path. For example, it can be obtained from https://capnproto.org/capnproto-c++-win32-0.10.4.zip
Ensure that capnp.exe is in a directory in your path. For example, it can be obtained from <https://capnproto.org/capnproto-c++-win32-0.10.4.zip>
Start a Command Prompt window.

32
INSTALL.md
View File

@ -1,61 +1,71 @@
# Install a Veilid Node
## Server Grade Headless Nodes
These network support nodes are heavier than the node a user would establish on their phone in the form of a chat or social media application. A cloud based virtual private server (VPS), such as Digital Ocean Droplets or AWS EC2, with high bandwidth, processing resources, and uptime availability is crucial for building the fast, secure, and private routing that Veilid is built to provide.
### Add the repo to a Debian based system and install a Veilid node
This is a multi-step process.
**Step 1**: Add the GPG keys to your operating systems keyring.<br />
**Step 1**: Add the GPG keys to your operating systems keyring.
*Explanation*: The `wget` command downloads the public key, and the `sudo gpg` command adds the public key to the keyring.
```shell
wget -O- https://packages.veilid.net/gpg/veilid-packages-key.public | sudo gpg --dearmor -o /usr/share/keyrings/veilid-packages-keyring.gpg
```
**Step 2**: Identify your architecture<br />
**Step 2**: Identify your architecture
*Explanation*: The following command will tell you what type of CPU your system is running
```shell
dpkg --print-architecture
```
**Step 3**: Add Veilid to your list of available software.<br />
**Step 3**: Add Veilid to your list of available software.
*Explanation*: Using the command in **Step 2** you will need to run **one** of the following:
- For **AMD64** based systems run this command:
```shell
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/veilid-packages-keyring.gpg] https://packages.veilid.net/apt stable main" | sudo tee /etc/apt/sources.list.d/veilid.list 1>/dev/null
```
- For **ARM64** based systems run this command:
```shell
echo "deb [arch=arm64 signed-by=/usr/share/keyrings/veilid-packages-keyring.gpg] https://packages.veilid.net/apt stable main" | sudo tee /etc/apt/sources.list.d/veilid.list 1>/dev/null
```
*Explanation*:
Each of the above commands will create a new file called `veilid.list` in the `/etc/apt/sources.list.d/`. This file contains instructions that tell the operating system where to download Veilid.
**Step 4**: Refresh the package manager.<br />
**Step 4**: Refresh the package manager.
*Explanation*: This tells the `apt` package manager to rebuild the list of available software using the files in `/etc/apt/sources.list.d/` directory. This is invoked with "sudo" to grant superuser permission to make the changes.
```shell
sudo apt update
```
**Step 5**: Install Veilid.<br />
**Step 5**: Install Veilid.
*Explanation*: With the package manager updated, it is now possible to install Veilid! This is invoked with "sudo" to grant superuser permission to make the changes.
```shell
sudo apt install veilid-server veilid-cli
```
### Add the repo to a Fedora based system and install a Veilid node
**Step 1**: Add Veilid to your list of available software.<br />
**Step 1**: Add Veilid to your list of available software.
*Explanation*: With the package manager updated, it is now possible to install Veilid!
```shell
yum-config-manager --add-repo https://packages.veilid.net/rpm/veilid-rpm-repo.repo
```
**Step 2**: Install Veilid.<br />
**Step 2**: Install Veilid.
*Explanation*: With the package manager updated, it is now possible to install Veilid!
```shell
dnf install veilid-server veilid-cli
```

22
README-DE.md
View File

@ -1,8 +1,8 @@
# Willkommen bei Veilid
- [Aus der Umlaufbahn](#aus-der-umlaufbahn)
- [Betreibe einen Node](#betreibe-einen-node)
- [Entwicklung](#entwicklung)
- [Aus der Umlaufbahn](#aus-der-umlaufbahn)
- [Betreibe einen Node](#betreibe-einen-node)
- [Entwicklung](#entwicklung)
## Aus der Umlaufbahn
@ -13,17 +13,19 @@ Veilid wurde mit der Idee im Hinterkopf entworfen, dass jeder Benutzer seine eig
Der primäre Zweck des Veilid Netzwerks ist es eine Infrastruktur für eine besondere Art von geteilten Daten zur Verfügung zu stellen: Soziale Medien in verschiedensten Arten. Dies umfasst sowohl leichtgewichtige Inhalte wie Twitters/Xs Tweets oder Mastodons Toots, mittleschwere Inhalte wie Bilder oder Musik aber auch schwergewichtige Inhalte wie Videos. Es ist eben so beabsichtigt Meta-Inhalte (wie persönliche Feeds, Antworten, private Nachrichten und so weiter) auf Basis von Veilid laufen zu lassen.
## Betreibe einen Node
Der einfachste Weg dem Veilid Netzwerk beim Wachsen zu helfen ist einen eigenen Node zu betreiben. Jeder Benutzer von Veilid ist automatisch ein Node, aber einige Nodes helfen dem Netzwerk mehr als Andere. Diese Nodes, die das Netzwerk unterstützen sind schwergewichtiger als Nodes, die Nutzer auf einem Smartphone in Form eine Chats oder eine Social Media Applikation starten würde.Droplets oder AWS EC2 mit hoher Bandbreite, Verarbeitungsressourcen und Verfügbarkeit sind wesentlich um das schnellere, sichere und private Routing zu bauen, das Veilid zur Verfügung stellen soll.
Um einen solchen Node zu betreiben, setze einen Debian- oder Fedora-basierten Server auf und installiere den veilid-server Service. Um dies besonders einfach zu machen, stellen wir Paketmanager Repositories als .deb und .rpm Pakete bereit. Für weitergehendene Information schaue in den [Installation](./INSTALL.md) Leitfaden.
## Entwicklung
Falls Du Lust hast, dich an der Entwicklung von Code oder auch auf andere Weise zu beteiligen, schau bitte in den [Mitmachen](./CONTRIBUTING.md) Leitfaden. Wir sind bestrebt dieses Projekt offen zu entwickeln und zwar von Menschen für Menschen. Spezifische Bereiche in denen wir nach Hilfe suchen sind:
* Rust
* Flutter/Dart
* Python
* Gitlab DevOps und CI/CD
* Dokumentation
* Sicherheitsprüfungen
* Linux Pakete
- Rust
- Flutter/Dart
- Python
- Gitlab DevOps und CI/CD
- Dokumentation
- Sicherheitsprüfungen
- Linux Pakete

22
README.md
View File

@ -1,8 +1,8 @@
# Welcome to Veilid
- [From Orbit](#from-orbit)
- [Run a Node](#run-a-node)
- [Development](#development)
- [From Orbit](#from-orbit)
- [Run a Node](#run-a-node)
- [Development](#development)
## From Orbit
@ -13,17 +13,19 @@ Veilid is designed with a social dimension in mind, so that each user can have t
The primary purpose of the Veilid network is to provide the infrastructure for a specific kind of shared data: social media in various forms. That includes light-weight content such as Twitter's tweets or Mastodon's toots, medium-weight content like images and songs, and heavy-weight content like videos. Meta-content such as personal feeds, replies, private messages, and so forth are also intended to run atop Veilid.
## Run a Node
The easiest way to help grow the Veilid network is to run your own node. Every user of Veilid is a node, but some nodes help the network more than others. These network support nodes are heavier than the node a user would establish on their phone in the form of a chat or social media application. A cloud based virtual private server (VPS), such as Digital Ocean Droplets or AWS EC2, with high bandwidth, processing resources, and up time availability is crucial for building the fast, secure, and private routing that Veilid is built to provide.
To run such a node, establish a Debian or Fedora based VPS and install the veilid-server service. To make this process simple we are hosting package manager repositories for .deb and .rpm packages. See the [installing](./INSTALL.md) guide for more information.
## Development
If you're inclined to get involved in code and non-code development, please check out the [contributing](./CONTRIBUTING.md) guide. We're striving for this project to be developed in the open and by people for people. Specific areas in which we are looking for help include:
* Rust
* Flutter/Dart
* Python
* Gitlab DevOps and CI/CD
* Documentation
* Security reviews
* Linux packaging
- Rust
- Flutter/Dart
- Python
- Gitlab DevOps and CI/CD
- Documentation
- Security reviews
- Linux packaging

92
RELEASING.md
View File

@ -9,19 +9,19 @@ This guide outlines the process for releasing a new version of Veilid. The end r
Releases happen via a CI/CD pipeline. The release process flows as follows:
1. Complete outstanding merge requests (MR):
1.1 Evaluate the MR's adherence to the published requirements and if automatic tests passed.
1.2 (Optional) Perform the merge in a local dev environment if testing is required beyond the standard Earthly tests.
1.3 If everything checks out, MR meets the published requirements, and tests passed, execute the merge functions in the Gitlab UI.
2. Maintainer performs version bump:
2.1 Update your local copy of `main` to mirror the newly merged upstream `main`
2.2 Ensure the (CHANGELOG)[./CHANGELOG.md] is updated
2.2 Ensure the [CHANGELOG](./CHANGELOG.md) is updated
2.3 Activate your bumpversion Python venv (see bumpversion setup section for details)
2.4 Execute version_bump.sh with the appropriate parameter (patch, minor, or major). This results in all version entries being updated and a matching git tag created locally.
@ -31,11 +31,11 @@ Releases happen via a CI/CD pipeline. The release process flows as follows:
2.6 Git commit the changes with the following message: `Version update: v{current_version} → v{new_version}`
2.7 Create the Git tag `git tag v{new_version}`
2.8 Push your local 'main' to the upstream origin 'main' `git push`
2.9 Push the new tag to the upstream origin `git push origin {tag name made in step 2.7}` i.e. `git push origin v0.1.5`
2.10 Ensure the package/release/distribute pipeline autostarted in the Gitlab UI
Git tags serve as a historical record of what repo versions were successfully released at which version numbers.
@ -53,14 +53,15 @@ Occasionally a release will happen that needs to be reverted. This is done manua
## Released Artifacts
### Rust Crates:
- [x] __veilid-tools__ [**Tag**: `veilid-tools-v0.0.0`]
### Rust Crates
- [x] __veilid-tools__ [__Tag__: `veilid-tools-v0.0.0`]
> An assortment of useful components used by the other Veilid crates.
> Released to crates.io when its version number is changed in `Cargo.toml`
- [x] __veilid-core__ [**Tag**: `veilid-core-v0.0.0`]
- [x] __veilid-core__ [__Tag__: `veilid-core-v0.0.0`]
> The base rust crate for Veilid's logic
> Released to crates.io when its version number is changed in `Cargo.toml`
- [ ] __veilid-server__
- [ ] __veilid-server__
> The Veilid headless node end-user application
> Not released to crates.io as it is an application binary that is either built by hand or installed using a package manager.
> This application does not currently support `cargo install`
@ -69,51 +70,63 @@ Occasionally a release will happen that needs to be reverted. This is done manua
> This application does not currently support `cargo install`
- [ ] __veilid-wasm__
> Not released to crates.io as it is not a library that can be linked by other Rust applications
- [ ] __veilid-flutter__
- [ ] __veilid-flutter__
> The Dart-FFI native interface to the Veilid API
> This is currently built by the Flutter plugin `veilid-flutter` and not released.
### Python Packages:
- [x] __veilid-python__ [**Tag**: `veilid-python-v0.0.0`]
### Python Packages
- [x] __veilid-python__ [__Tag__: `veilid-python-v0.0.0`]
> The Veilid API bindings for Python
> Released to PyPi when the version number is changed in `pyproject.toml`
### Flutter Plugins:
- [ ] __veilid-flutter__
### Flutter Plugins
- [ ] __veilid-flutter__
> The Flutter plugin for the Veilid API.
> Because this requires a build of a native Rust crate, this is not yet released via https://pub.dev
> TODO: Eventually the rust crate should be bound to
> Because this requires a build of a native Rust crate, this is not yet released via <https://pub.dev>
> TODO: Eventually the rust crate should be bound to
### Operating System Packages:
- [x] __veilid-server__ DEB package [**Tag**: `veilid-server-deb-v0.0.0`]
### Operating System Packages
- [x] __veilid-server__ DEB package [__Tag__: `veilid-server-deb-v0.0.0`]
> The Veilid headless node binary in the following formats:
> * Standalone Debian/Ubuntu DEB file as a 'release file' on the `veilid` GitLab repository
> * Pushed to APT repository at https://packages.veilid.net
- [x] __veilid-server__ RPM package [**Tag**: `veilid-server-rpm-v0.0.0`]
>
> - Standalone Debian/Ubuntu DEB file as a 'release file' on the `veilid` GitLab repository
> - Pushed to APT repository at <https://packages.veilid.net>
>
- [x] __veilid-server__ RPM package [__Tag__: `veilid-server-rpm-v0.0.0`]
> The Veilid headless node binary in the following formats:
> * Standalone RedHat/CentOS RPM file as a 'release file' on the `veilid` GitLab repository
> * Pushed to Yum repository at https://packages.veilid.net
- [x] __veilid-cli__ DEB package [**Tag**: `veilid-cli-deb-v0.0.0`]
>
> - Standalone RedHat/CentOS RPM file as a 'release file' on the `veilid` GitLab repository
> - Pushed to Yum repository at <https://packages.veilid.net>
>
- [x] __veilid-cli__ DEB package [__Tag__: `veilid-cli-deb-v0.0.0`]
> The Veilid headless node administrator control binary in the following formats:
> * Standalone Debian/Ubuntu DEB file as a 'release file' on the `veilid` GitLab repository
> * Pushed to APT repository at https://packages.veilid.net
- [x] __veilid-cli__ RPM package [**Tag**: `veilid-cli-rpm-v0.0.0`]
>
> - Standalone Debian/Ubuntu DEB file as a 'release file' on the `veilid` GitLab repository
> - Pushed to APT repository at <https://packages.veilid.net>
>
- [x] __veilid-cli__ RPM package [__Tag__: `veilid-cli-rpm-v0.0.0`]
> The Veilid headless node administrator control binary in the following formats:
> * Standalone RedHat/CentOS RPM file as a 'release file' on the `veilid` GitLab repository
> * Pushed to Yum repository at https://packages.veilid.net
>
> - Standalone RedHat/CentOS RPM file as a 'release file' on the `veilid` GitLab repository
> - Pushed to Yum repository at <https://packages.veilid.net>
### Version Numbering:
### Version Numbering
All versions of Veilid Rust crates as well as `veilid-python` and `veilid-flutter` packages are versioned using Semver. Versions can differ per crate and package, and it is important for the Semver rules to be followed (https://semver.org/):
All versions of Veilid Rust crates as well as `veilid-python` and `veilid-flutter` packages are versioned using Semver. Versions can differ per crate and package, and it is important for the Semver rules to be followed (<https://semver.org/>):
* MAJOR version when you make incompatible API changes
* MINOR version when you add functionality in a backward compatible manner
* PATCH version when you make backward compatible bug fixes
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backward compatible manner
- PATCH version when you make backward compatible bug fixes
The `version_bump.sh` script should be run on every release to stable. All of the Rust crates are versioned together and should have the same version, as well as the `veilid-python` Python package and `veilid-flutter` Flutter plugin.
## Bumpversion Setup and Usage
### Install Bumpversion
1. Create a Python venv for bumpversion.py. Mine is in my home dir so it persists when I update my local Veilid `main`.
`python3 -m venv ~/bumpversion-venv`
@ -121,5 +134,6 @@ The `version_bump.sh` script should be run on every release to stable. All of th
3. Install bumpversion. `pip3 install bumpversion`
### Activate venv for version bumping step of the release process
1. Activate the venv. `source ~/bumpversion-venv/bin/activate`
2. Return to step 2.4 of _Create a Gitlab Release_
2. Return to step 2.4 of _Create a Gitlab Release_