Skip to content

Commit cfc2634

Browse files
author
jose
committed
doc: create centralized documentation for developers
Developers can easily access documentation on Puter project development concerns, and learn from it in order to contribute to ensure greater usefulness of their work. For the use of it, there are two options: Either the developer runs the mkdocs server locally, or the puter repository can provide a public deployment to access. If you decide that the second case is useful please let me know and I could create a github actions pipeline to deploy this in a separate branch as a static site. Thx for read.
1 parent fe5f7cb commit cfc2634

File tree

16 files changed

+1464
-0
lines changed

16 files changed

+1464
-0
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,6 @@ dist/
3030
# Local Netlify folder
3131
.netlify
3232
src/emulator/release/
33+
34+
# Dinamic dev documentation files
35+
doc/dev_doc/site

‎doc/dev_doc/docs/arch.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# System Architecture
2+
3+
## General
4+
5+
Puter's system goals is to provide an internet operating system, providing (as brief):
6+
7+
1. **User management:** (User) Account and session CrUD, Permissions...
8+
2. **Desktop environment use:** (User) Use apps in interactive mode through GUIs, CrUD symbolic links and icons...
9+
3. **System deployment:** (Developers) build a web app, or web service, on puter.
10+
11+
and ensuring:
12+
13+
1. **Extensibility:** you should be able to create your own Kernel Modules, user-oriented applications, and so.
14+
2. **Debuggability:** given this is opensource-driven, you'll find loggers and monitoring tools aiming to make development easier.
15+
3. **Deployability:** you, and other users, should be able to deploy this system at least both self host and public hosting.
16+
4. **Securability:** you, and other users, should be able to trust on puter as a personal cloud, a remote desktop for servers and workstations, and as a software development platform.
17+
18+
In order to achieve those requirements, Puter is following (tl;dr):
19+
20+
1. **A client-server style Architecture:** Allow user to interact with system GUI through a Web Browser (as an external system).
21+
2. **Micro-kernel pattern:** Allow backend (in which heavy processing occurs) to extend system's functionality, keeping the core of the system and the other additions decoupled each other.
22+
23+
In in a nutshell:
24+
```
25+
Puter is Puter, whatever you think it might be useful for
26+
you can use it for. You can think of it as a high-level
27+
operating system where the "hardware" is external services or
28+
resources provided by the host OS; if you develop apps on
29+
this platform you have higher-level primitives, like how
30+
using AI services is considered a "driver", or how Puter's
31+
filesystem can use a database to store the directory tree and
32+
file metadata.
33+
```
34+
35+
## Deployment
36+
37+
### Local dev
38+
39+
Get the [monorepo](https://github.com/HeyPuter/puter/), and then run `install` and `start` [npm scripts](https://github.com/HeyPuter/puter/blob/main/package.json)
40+
41+
```
42+
git clone https://github.com/HeyPuter/puter
43+
cd puter
44+
npm install
45+
npm start
46+
```
47+
48+
You get in error? then you can [check our first run issues checklist.](./deployment/first-run-issues.md)
49+
50+
Also, if you get "Cannot write to path" error, it usually happens when /var/puter isn\'t chown\'d to the right UID. You can check the [issue number 645.](https://github.com/HeyPuter/puter/issues/645)
51+
### Docker
52+
53+
On linux/macOS run:
54+
55+
```
56+
mkdir puter && cd puter && mkdir -p puter/config puter/data && sudo chown -R 1000:1000 puter && docker run --rm -p 4100:4100 -v `pwd`/puter/config:/etc/puter -v `pwd`/puter/data:/var/puter ghcr.io/heyputer/puter
57+
```
58+
59+
On Windows run:
60+
61+
```
62+
mkdir -p puter
63+
cd puter
64+
New-Item -Path "puter\config" -ItemType Directory -Force
65+
New-Item -Path "puter\data" -ItemType Directory -Force
66+
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/HeyPuter/puter/main/docker-compose.yml" -OutFile "docker-compose.yml"
67+
docker compose up
68+
```
69+
70+
## Main modules traits
71+
72+
### service
73+
74+
- **Concern:** to extend core functionality.
75+
- **Class:** BaseService (extends concepts.Service)
76+
- **Public interface:**
77+
78+
```
79+
/**
80+
* Creates the service's data structures and initial values.
81+
* This method sets up logging and error handling, and calls a custom `_construct` method if defined.
82+
*
83+
* @returns {Promise<void>} A promise that resolves when construction is complete.
84+
*/
85+
async construct () => void
86+
```
87+
88+
```
89+
/**
90+
* Constructs service class using Service Resources list
91+
* Service Resources properties: services, config, my_config, name, args, context.
92+
*/
93+
constructor (service_resources, ...a)
94+
```
95+
96+
97+
```
98+
/**
99+
* Performs service lifecycle's initialization phase
100+
*/
101+
async init () => void
102+
```
103+
104+
### Kernel
105+
106+
107+
- **Concern:** To orchestrate core modules for system to load up, following [**Backend Boot Sequence**.](./deployment/backend_boot_sequence.md)
108+
- **Class:** Kernel (extends AdvancedBase)
109+
- **Public interface:**
110+
111+
```
112+
/**
113+
* Construct kernel module configuring its useapi and entry path
114+
*/
115+
constructor (entry_path) =>
116+
```
117+
118+
119+
```
120+
/**
121+
* Adds a module into kernel's modules list
122+
*/
123+
add_module (module) => void
124+
```
125+
126+
```
127+
/**
128+
* Boots backend
129+
*/
130+
boot () => void
131+
```
132+
133+
## System entry points
134+
135+
### Testing
136+
Mocha is being used for this.
137+
There are 2 main **test directories:**
138+
1. src/phoenix/test -> testing phoenix emulator.
139+
2. src/backend/tools/test -> a set of tools for backend testing. [Read more about backend tools.](./testing/backend_tools.md)
140+
141+
### Use cases
142+
For **self hosting** deployment, there is a _tool_ called "run-selfhosted.js" which you can run with ```npm run start``` command. That tool is going to:
143+
144+
1. Get all required _kernel modules_ from the **@heyputer/backend npm package**
145+
2. Configure kernel's entry path as the directory path of the current file (so, the run-selfhosted tool's directory).
146+
3. Add all required _kernel modules_ to kernel's modules list.
147+
4. Start kernel by its ```boots()``` public method.
148+
149+
**Monitoring:** The ```SelfHostedModule``` is responsible for load 3 project's module watching tools (for GUI, TERMINAL, EMULATOR, GIT, PHOENIX, and PUTER-JS)
150+
151+
---
152+
153+
If you find any bug or error in this documentation, do not hesitate to send your complaint to **[email protected]**, or **colaborate** with the documentation yourself.

‎doc/dev_doc/docs/deployment/backend_boot_sequence.md

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Puter Backend Boot Sequence
2+
3+
This document describes the boot sequence of Puter's backend.
4+
5+
**Runtime Environment**
6+
- Configuration directory is determined
7+
- Runtime directory is determined
8+
- Mod directory is determined
9+
- Services are instantiated
10+
11+
**Construction**
12+
- Data structures are created
13+
14+
**Initialization**
15+
- Registries are populated
16+
- Services prepare for next phase
17+
18+
**Consolidation**
19+
- Service event bus receives first event (`boot.consolidation`)
20+
- Services perform coordinated setup behaviors
21+
- Services prepare for next phase
22+
23+
**Activation**
24+
- Blocking listeners of `boot.consolidation` have resolved
25+
- HTTP servers start listening
26+
27+
**Ready**
28+
- Services are informed that Puter is providing service
29+
30+
## Boot Phases
31+
32+
### Construction
33+
34+
Services implement a method called `construct` which initializes members
35+
of an instance. Services do not override the class constructor of
36+
**BaseService**. This makes it possible to use the `new` operator without
37+
invoking a service's constructor behavior during debugging.
38+
39+
The first phase of the boot sequence, "construction", is simply a loop to
40+
call `construct` on all registered services.
41+
42+
The `_construct` override should not:
43+
- call other services
44+
- emit events
45+
46+
### Initialization
47+
48+
At initialization, the `init()` method is called on all services.
49+
The `_init` override can be used to:
50+
- register information with other services, when services don't
51+
need to register this information in a specific sequence.
52+
An example of this is registering commands with CommandService.
53+
- perform setup that is required before the consolidation phase starts.
54+
55+
### Consolidation
56+
57+
Consolidation is a phase where services should emit events that
58+
are related to bringing up the system. For example, WebServerService
59+
('web-server') emits an event telling services to install middlewares,
60+
and later emits an event telling services to install routes.
61+
62+
Consolidation starts when Kernel emits `boot.consolidation` to the
63+
services event bus, which happens after `init()` resolves for all
64+
services.
65+
66+
### Activation
67+
68+
Activation is a phase where services begin listening on external
69+
interfaces. For example, this is when the web server starts listening.
70+
71+
Activation starts when Kernel emits `boot.activation`.
72+
73+
### Ready
74+
75+
Ready is a phase where services are informed that everything is up.
76+
77+
Ready starts when Kernel emits `boot.ready`.
78+
79+
## Events and Asynchronous Execution
80+
81+
The services event bus is implemented so you can `await` a call to `.emit()`.
82+
Event listeners can choose to have blocking behavior by returning a promise.
83+
84+
During emission of a particular event, listeners of this event will not
85+
block each other, but all listeners must resolve before the call to
86+
`.emit()` is resolved. (i.e. `emit` uses `Promise.all`)
87+
88+
## Legacy Services
89+
90+
Some services were implemented before the `BaseService` class - which
91+
implements the `init` method - was created. These services are called
92+
"legacy services" and they are instantiated _after_ initialization but
93+
_before_ consolidation.
94+
95+
---
96+
97+
If you find any bug or error in this documentation, do not hesitate to send your complaint to **[email protected]**, or **colaborate** with the documentation yourself.

‎doc/dev_doc/docs/deployment/first-run-issues.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# First Run Issues
2+
3+
## "Cannot find package '@heyputer/backend'"
4+
5+
Scenario: You see the following output:
6+
7+
```
8+
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
9+
┃ Cannot find package '@heyputer/backend' ┃
10+
┃ 📝 this usually happens if you forget `npm install` ┃
11+
┃ Suggestions: ┃
12+
┃ - try running `npm install` ┃
13+
┃ Technical Notes: ┃
14+
┃ - @heyputer/backend is in an npm workspace ┃
15+
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
16+
```
17+
18+
1. Ensure you have run `npm install`.
19+
2. [Install build essentials for your distro](#installing-build-essentials),
20+
then run `npm install` again.
21+
22+
## Installing Build Essentials
23+
24+
### Debian-based distros
25+
26+
```
27+
sudo apt update
28+
sudo apt install build-essential
29+
```
30+
31+
### RHEL-family distros (Fedora, Rocky, etc)
32+
33+
```
34+
sudo dnf groupinstall "Development Tools"
35+
```
36+
37+
### "I use Arch btw"
38+
39+
```
40+
sudo pacman -S base-devel
41+
```
42+
43+
### Alpine
44+
45+
If you're running in Puter's Alpine image then this is already installed.
46+
47+
```
48+
sudo apk add build-base
49+
```
50+
51+
### Gentoo
52+
53+
You know what you're doing; you just wanted to see if we mentioned Gentoo.
54+
55+
---
56+
57+
If you find any bug or error in this documentation, do not hesitate to send your complaint to **[email protected]**, or **colaborate** with the documentation yourself.

0 commit comments

Comments
 (0)