-
Notifications
You must be signed in to change notification settings - Fork 67
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4093 from systeminit/keeb/tutorial-scaffold
(docs) TOC, Tutorial, and Reference Docs - Initial Commit
- Loading branch information
Showing
16 changed files
with
600 additions
and
116 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# Roadmap | ||
|
||
... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -4,51 +4,64 @@ keywords: | |
- docs | ||
--- | ||
|
||
# Welcome to System Initiative Documentation | ||
# System Initiative | ||
|
||
## Empowering Your Infrastructure Management | ||
System Initiative is a cloud application platform that makes it easier, safer, | ||
and faster to deploy applications, build infrastructure, and manage them over | ||
time. | ||
|
||
Welcome to the official documentation for System Initiative. Our platform is | ||
designed to revolutionize the way you manage and optimize your infrastructure, | ||
making it easier, more efficient, and more collaborative than ever before. | ||
<div class="tip custom-block" style="padding-top: 8px"> | ||
|
||
### What is System Initiative? | ||
Just want to try it out? Skip to the [Quickstart](./tutorials/orientation.md). | ||
|
||
System Initiative is a cutting-edge platform that combines infrastructure as | ||
code, collaboration tools, and intelligent automation to streamline your DevOps | ||
processes. Our solution empowers teams to work together seamlessly, manage | ||
complex systems with ease, and accelerate development cycles. | ||
</div> | ||
|
||
### Key Features | ||
## Key Features | ||
|
||
- **Infrastructure as Code**: Define and manage your infrastructure using | ||
familiar coding practices. | ||
- **Collaborative Workspace**: Work together in real-time with your team, | ||
regardless of location. | ||
- **Intelligent Automation**: Leverage AI-driven insights to optimize your | ||
infrastructure decisions. | ||
- **Version Control**: Keep track of changes and roll back when needed with | ||
built-in versioning. | ||
- **Compliance and Security**: Ensure your infrastructure meets industry | ||
standards and best practices. | ||
### Short Feedback Loops | ||
|
||
Every change is validated and qualified immediately. Reconciliation can happen | ||
individually or in batches, making application changes orders of magnitude | ||
faster. | ||
|
||
### High Intelligence | ||
|
||
Configuration can be inferred through the relationships between models. Changing | ||
a value at the source cascades throughout all the dependent models, making | ||
complex configuration easy to express. Code is automatically generated from the | ||
model. | ||
|
||
### Easy Collaboration | ||
|
||
Fully multiplayer coding and interactive diagrams make working together more | ||
like Figma and Notion, and less like GitHub. Everything is open source, with | ||
integrated open source module sharing. | ||
|
||
### Natural Context Windows | ||
|
||
The entire life cycle is built in to a single power tool. Customization happens | ||
in the application. New experiences are built around the data. | ||
|
||
### Getting Started | ||
|
||
New to System Initiative? Here are some resources to help you get up and | ||
running: | ||
|
||
1. [Quick Start Guide](./quick-start.md) | ||
2. [Core Concepts](./core-concepts.md) | ||
3. [Installation](./installation.md) | ||
4. [Your First Project](./first-project.md) | ||
1. [Quick Start Guide](./tutorials/orientation.md) | ||
2. [Core Concepts](./reference/core-concepts.md) | ||
|
||
### Need Help? | ||
|
||
If you have any questions or need assistance, our support team is here to help: | ||
|
||
- [FAQs](./faqs.md) | ||
[![Discord Server](https://img.shields.io/badge/discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.com/invite/system-init) | ||
|
||
- [FAQ](./reference/faq.md) | ||
- [Community Forum](https://community.systeminit.com) | ||
- [Contact Support](mailto:[email protected]) | ||
|
||
### Developing System Initaitive | ||
|
||
1. [Development Environment](./reference/dev/development-environment.md) | ||
|
||
Thank you for choosing System Initiative. Let's build amazing infrastructure | ||
together! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
# Asset Builder API | ||
|
||
Explanation of how the Asset Builder and associated API |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
# Core Concepts | ||
|
||
## Full Fidelity Model | ||
|
||
A full fidelity model of the resources in your system - such as: | ||
|
||
- AWS | ||
- Docker | ||
- Kubernetes | ||
|
||
## Qualify the Model | ||
|
||
We then qualify the model to give real time feedback on its suitability Use | ||
relationships between models to infer configuration | ||
|
||
## Automatically Generate the Necessary Code | ||
|
||
Automatically generate necessary code | ||
|
||
## Fully programmable | ||
|
||
Fully programmable and customizable from within the application | ||
|
||
## Bi-directional reconciliation | ||
|
||
Bi-directional reconciliation of the simulation with the real system (and in the | ||
future, automatic creation of the simulation) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,204 @@ | ||
# Development Environment | ||
|
||
Developing SI locally can be done in a variety of ways, but the officially | ||
supported method is to use the [`nix` flake](flake.nix) at the root of the | ||
repository. | ||
|
||
## Supported Platforms | ||
|
||
Using the flake requires using one of the below platforms. It is possible that | ||
the System Initiative software can be developed on even more platforms, but | ||
these platforms have been validated to work with `nix` and the corresponding | ||
flake. | ||
|
||
### macOS | ||
|
||
macOS (Darwin) is officially supported on both x86_64 (amd64) (also known as | ||
"Intel") and aarch64 (arm64) (also known as "Apple Silicon") architectures. We | ||
do not specify the minimum version of macOS that must be used, so we recommend | ||
looking at the "Dependencies" section for more information. | ||
|
||
For aarch64 (arm64) users, [Rosetta 2](https://support.apple.com/en-us/HT211861) | ||
must be installed. You can either install it via directions from the official | ||
support page or by running `softwareupdate --install-rosetta`. | ||
|
||
On macOS, you will likely hit the file descriptor limit, which requires user | ||
intervention. We have a section further down that describes how to intervene. | ||
|
||
### Linux | ||
|
||
Linux (GNU) is officially supported on both x86_64 (amd64) and aarch64 (arm64) | ||
architectures. [NixOS](https://nixos.org/) is not supported at this time, but | ||
may be desired in the future. Linux with MUSL instead of GNU is also not | ||
currently supported. | ||
|
||
In general, GNU-based distros that are roughly | ||
[FHS-compliant](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard) | ||
will work. Those include, but are not limited to the following: Ubuntu, Fedora, | ||
Debian, Arch Linux, and openSUSE. | ||
|
||
### Windows | ||
|
||
Using native Windows is not supported at this time, but may be desired in the | ||
future. However, [WSL2](https://learn.microsoft.com/en-us/windows/wsl/) on | ||
Windows 10 and Windows 11 is officially supported on both x86_64 (amd64) and | ||
aarch64 (arm64) architectures. In order to work with `nix`, `systemd` may need | ||
to be enabled in your WSL2 distro of choice. | ||
|
||
On WSL2, you will likely hit the file descriptor limit, which requires user | ||
intervention. We have a section further down that describes how to intervene. | ||
|
||
## Tuning the File Descriptor Limit | ||
|
||
On some systems, you may need to significantly increase the file descriptor | ||
limit for building and running our services with `buck2`. This is because | ||
`buck2` opens many more files than either `cargo` or `pnpm` do. Not only that, | ||
but when using Tilt to build and run concurrent services, even more files are | ||
opened than they would be for sequential builds. | ||
|
||
Increasing the file descriptor limit is possible via the `ulimit` command. To | ||
see all limits, execute the following command: | ||
|
||
```bash | ||
ulimit -a | ||
``` | ||
|
||
Here is an example of a significant limit increase, where the argument provided | ||
after the flag represents the new desired number of file descriptors: | ||
|
||
```bash | ||
ulimit -n <file-descriptor-count> | ||
``` | ||
|
||
To find an acceptable limit, run the health check command. | ||
|
||
```bash | ||
buck2 run dev:healthcheck | ||
``` | ||
|
||
## Dependencies | ||
|
||
For all supported platforms, there are two dependencies that must be installed, | ||
`nix` (preferably via the | ||
[Determinate Nix Installer](https://github.com/DeterminateSystems/nix-installer)) | ||
and `docker`. | ||
|
||
### Nix | ||
|
||
We use `nix` as our package manager for the repository. It ensures that our | ||
developers are all using the same versions of all packages and libraries for | ||
developing SI. | ||
|
||
Regardless of how `nix` is installed, it must have the | ||
[flakes](https://nixos.wiki/wiki/Flakes) feature enabled. We highly recommend | ||
using the | ||
[Determinate Nix Installer](https://github.com/DeterminateSystems/nix-installer) | ||
over the official installer; one reason being that the former will enable flakes | ||
by default. | ||
|
||
> [!TIP] You can use `direnv` (version >= 2.30) with our | ||
> [`nix` flake](flake.nix) for both ease of running commands and for editor | ||
> integration. | ||
> | ||
> For more information, see the **Direnv** section. | ||
### Docker | ||
|
||
We use `docker` to run our dependent services for the SI stack. It can either be | ||
installed via [Docker Desktop](https://www.docker.com/products/docker-desktop/) | ||
or directly via [Docker Engine](https://docs.docker.com/engine/). | ||
|
||
For Docker Desktop, the version corresponding to your native architecture should | ||
be used (e.g. install the aarch64 (arm64) version on a Apple-Silicon-equipped | ||
MacBook Pro). | ||
|
||
WSL2 users should be able to use either Docker Desktop for WSL2 or Docker Engine | ||
(i.e. installing and using `docker` within the distro and not interacting with | ||
the host). | ||
|
||
Regardless of platform, you may need to configure credentials in | ||
`~/.local/share`. | ||
|
||
#### Rancher Desktop | ||
|
||
Since [Rancher Desktop](https://rancherdesktop.io/) provides the ability to use | ||
[moby](https://github.com/moby/moby), you can use it to run and develop the | ||
System Initiative software. However, it is untested, and you may need to further | ||
configuration depending on your platform. | ||
|
||
### (Optional) Direnv | ||
|
||
[Direnv](https://direnv.net/) (version >= 2.30) with | ||
[nix-direnv](https://github.com/nix-community/nix-direnv) can automatically set | ||
up your shell, which means you don't need to enter a subshell with | ||
`nix develop`, or prefix all commands with `nix develop --command`. | ||
|
||
You can install it with | ||
[your package manager of choice](https://direnv.net/docs/installation.html), but | ||
if you're unsure which installation method to use or your package manager does | ||
not provide a compatible version, you can use `nix` itself (e.g. | ||
`nix profile install nixpkgs#direnv`). | ||
|
||
We recommend using | ||
[the upstream docs for hooking `direnv` into your shell](https://direnv.net/docs/hook.html), | ||
but here is an example on how to do it on a system where `zsh` is the default | ||
shell. In this example, the following is added to the end of `~/.zshrc`. | ||
|
||
```zsh | ||
if [ $(command -v direnv) ]; then | ||
eval "$(direnv hook zsh)" | ||
fi | ||
``` | ||
|
||
There are also plugins to integrate `direnv` with common editors. | ||
|
||
#### Editor Plugin Support | ||
|
||
- Emacs: [emacs-direnv](https://github.com/wbolster/emacs-direnv) | ||
- IntelliJ-based IDEs: | ||
[Direnv integration](https://plugins.jetbrains.com/plugin/15285-direnv-integration), | ||
[Better Direnv](https://plugins.jetbrains.com/plugin/19275-better-direnv) | ||
- Neovim and Vim: [direnv.vim](https://github.com/direnv/direnv.vim) | ||
- Visual Studio Code: | ||
[direnv](https://marketplace.visualstudio.com/items?itemName=mkhl.direnv) | ||
|
||
## How to Run Commands | ||
|
||
All commands need to be run from the `nix` environment. There are two primary | ||
options to do so: | ||
|
||
1. If `direnv` is installed _and_ hooked into your shell, you can `cd` into the | ||
repository and `nix` will boostrap the environment for you using the flake. | ||
2. Otherwise, you can execute `nix develop` to enter the environment, | ||
`nix develop --command <command>` to execute a command, or use the | ||
environment in whatever way your prefer. | ||
|
||
## How Will I Know That Each Component Is Ready? | ||
|
||
For backend services like `veritech` and `sdf`, there will usually be an | ||
`INFO`-level log indicating that the webserver has bound to a port and is ready | ||
to receive messages. This may be subject to change (e.g. underlying library is | ||
upgraded to a new major version and the startup sequence changes) and will vary | ||
from component to component. | ||
|
||
# Troubleshooting | ||
|
||
This section contains common troubleshooting scenarios when working on the | ||
System Initiative software. | ||
|
||
## Build Errors Related to Running Services Reliant on `node_modules` | ||
|
||
Since we switched to `buck2` for our build infrastructure in mid-2023, you may | ||
experience issues when running services reliant on `node_modules` within older | ||
cloned instances of the repostiory. To solve these build errors, run the | ||
following in the root of your repository: | ||
|
||
> [!WARNING] > _This command deletes files._ Ensure your current working | ||
> directory is the root of the repository and understand what the command does | ||
> before executing. Please reach out to us | ||
> [on our Discord server](https://discord.com/invite/system-init) if you have | ||
> any questions. | ||
```bash | ||
find app bin lib third-party/node -type d -name node_modules -exec rm -rf {} \;; rm -rf node_modules | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
# FAQ | ||
|
||
## Is it open source? | ||
|
||
## Isn't this just clickops? | ||
|
||
## Where is git? | ||
|
||
## Can I trigger this somehow? | ||
|
||
## How many clouds do you support? | ||
|
||
## Who do you compete with? | ||
|
||
## Replacing our automation will take forever | ||
|
||
## Can you deploy it on prem? | ||
|
||
## What's next? |
Oops, something went wrong.