Ver Fonte

Updated documentation

As title
TC pushbot 5 há 5 anos atrás
pai
commit
2015d47b84

+ 2 - 2
docs/README.md

@@ -1,4 +1,4 @@
-# ArOZ Online Documentation Rendering Interface
+# ArozOS Documentation Rendering Interface
 This is the documentation rendering script for ArOZ Online Documentation System.
 The json files follow the following structure
 
@@ -14,4 +14,4 @@ For example:
 More lines here
 ```
 
-The reader.php will then render the JSON content into css + HTML. All image should be placed inside /img directory under the /docs documentation root folder.
+The reader.html will then render the JSON content into css + HTML. All image should be placed inside /img directory under the /docs documentation root folder.

+ 1 - 1
docs/lang/started/0.md → docs/chapter/started/0.md

@@ -1,5 +1,5 @@
 ["Welcome to arozos"]
-<img class="ts fluid image" src="img/started/0/0.png"></img>
+<img class="ts fluid image" src="../../img/started/0/0.png"></img>
 
 # arozos
 arozos is a general purpose cross platform **Web Desktop Operating System** that is designed to be user-friendly, intuitive and with high expandability using either

+ 14 - 0
docs/chapter/started/1.md

@@ -0,0 +1,14 @@
+["Remarks"]
+
+# Remarks
+## Legacy Version of ArOZ 
+The previous release of the arozos is named &quot;ArOZ Online System&quot; or &quot;ArOZ Online Beta&quot; (AOB). For information and documentation for the beta version of this system, please read the &quot;ArOZ Online Distributed Cloud System Documentation&quot; instead.
+
+You can classify the difference between these two systems by identifying the programming language of the system.
+
+| Version | Programming Language | File Extension |
+| --- | --- | --- |
+| ArOZ Online Beta | PHP5 / PHP7 | .php |
+| ArOZ OS (ArOZ Online 1.0) | Go | .go |
+
+ArOZ OS is written as &quot;arozos&quot; in the current documentation for simplicity and easy to read purposes.

+ 58 - 0
docs/chapter/started/2.md

@@ -0,0 +1,58 @@
+["Introduction"]
+
+## Introduction
+
+### Aim and Objective of the project
+
+Many off-the-shelf cloud services and infrastructure are only designed for commercial or business purposes. When it comes to non-profiting oriented or general purposes cloud platforms, there are only limited choices for easy plug &amp; play development.
+
+The beta phrase of this project aims to provide a low cost, personal and private cloud architecture in both software and hardware aspects that is distributed with high scalability and reliability for deploying critical systems.
+
+In the 1.0 version of this system, the system architecture is being redesigned to fit more general purpose cloud computing, including quick system deployment, service binding and allowing general users to engage in cloud computing technology through a user friendly, web desktop interface.
+
+### Naming Scheme
+
+#### Stage Naming
+
+ArOZ Online System (Originally named Automated Remote Operating Zigzagger, which Zigzagger implies stitching things together in a good way) was a platform that is designed to store multimedia files with an external hard disk on Raspberry Pi Model B, providing &quot;media center&quot; like experience to users and allows for media consumption in local area network environment. Later, more and more cloud related functions are added into the system for better enhancing the usability of the system including but not limited to web desktop environment, cluster setups and communication pipelines, distributed file systems and in system programmable modules. These modules and subsystems add more functionality to the cloud platform.
+
+The Beta system (ArOZ Online Beta) is a system that provides all of the functions mentioned above and delivers a web-desktop-like environment by bridging to the underlying Linux file system. Providing a powerful cloud desktop environment for users to be used with any mobile or desktop devices without the constraints of a designated terminal device(s) like personal smartphones or laptops.
+
+The 1.0 version (arozos) is a system that is completely rewritten based on the Beta phrase requirement discovery process. Most of the well known functions on the beta are being rewritten into a more efficiency algorithm with Go instead of PHP. Providing much more performance boost out of linux SBCs like the Raspberry Pis without the need for upgrading the hardware.
+
+#### Version Naming
+
+The version system of the ArOZ Series software is as follows.
+
+| Version Name | Development Date | Systems (Language) |
+| --- | --- | --- |
+| ArOZ (Alpha) | Early 2014 | Windows 7 (VB.net) |
+| ArOZ Beta | Late 2014 | Windows 7 (VB.net) |
+| ArOZ Omega | Early 2015 | Windows 7(VB.net) |
+| ArOZ Online Alpha | Late 2015 - Early 2016 | Windows 7 (WAMP + PHP 5) |
+| ArOZ Online Beta | 2016 - 2020 | Windows / Linux (Apache + PHP 7) |
+| ArOZ OS | 2020 - Now | Windows / Linux / Mac OS (Go 1.14+) |
+
+### System Usage
+
+ArOZ Online System can be run on a portable device, miniature NAS system or server grade computers. Hence, the system will suit the needs for many different usages, including portable workstation, media conversion or consumption, data backups and restore etc.
+
+The arozos provides even more general purpose for business sector, including fully featured authentication system, user permission and grouping systems, internal reverse proxy services and storage pool management. Allowing the system to be used in deploying web platforms that requires user management as well as user permission management.
+
+Modular WebApp system design also strengthened the permission system and allowed more secure cloud computing process and web services.
+
+## Terminology
+
+In this documentation, the following terminology will be used to describe the content and functions provided in this system.
+
+| Term | Explanation |
+| --- | --- |
+| Arozos / ArOZ OS | The cloud system that is being discussed in this document. |
+| WebApps | Web application that is installed on the arozos as a folder in the /web directory. |
+| Subservice | Web application that is installed on the arozos as a separated binary located in its folder under /subservice directory. |
+| Web Desktop Interface / VDI mode | Virtual Desktop Interface (Mode). The mode where the user is interacting with the arozos through its web based desktop user interface. |
+| List Menu | The application startup menu that used to start an application on both VDI and mobile interface |
+| FloatWindow (fw) | Window-like iframe that is located on the web based desktop interface that the user can drag, resize and hide. |
+| Functio(nal) Bar | The bottom bar of the web desktop interface that used to display the web app opened by the user OR The sidebar of the mobile desktop mode where the webapp opened by the user will be shown. |
+| Status Bar | The top bar on the web desktop interface that is used to show the hostname, current date time and a content button for showing shortcuts. |
+| Arozfs / aroz virtual file system | The virtualized file system that is emulated by arozos. |

+ 43 - 0
docs/chapter/started/3.md

@@ -0,0 +1,43 @@
+["System Requirement"]
+
+## System Requirement
+
+### Hardware
+
+Minimal
+
+1Ghz CPU (ARMv6/7, ARM64 or AMD64), 512MB RAM, 8GB Storage
+
+Recommended
+
+2+Ghz CPU (ARM7, ARM64 or AMD64), 2GB RAM, 32GB Storage
+
+System Tested on:
+
+- Raspberry Pi 3B+ w/ Raspberry Pi OS
+- Raspberry Pi Zero W w/ Raspberry Pi OS
+- Raspberry Pi 4B+ (1GB / 2GB / 4GB version) w/ Raspberry Pi OS
+- Orange Pi Zero Plug (H5 CPU edition) w/ Armbian Buster
+- AMD64 ThinClient w/ Debian Buster
+- Ryzen 5 w/ Windows 10
+- Intel Pentium w/ Windows 7
+
+### Software
+
+Operating System:
+
+Raspberry Pi OS / Debian Buster, (Limited functionality on Windows 7+ and macOS Catalina +)
+
+Package (Required):
+
+Wpa_supplicant or nmcli, net-tools (ifconfig), FFmpeg
+
+### Clients / Browsers
+
+Any modern browsers (Latest version of Chrome / Firefox / Safari (Not Tested) / Edge) on macOS High Sierra or above / Windows 7 or above
+
+### Network
+
+Network Environment:
+
+Network speed of Minimum 10Mbps (100Mbps+ Recommended), WiFi 2.4 / 5 Ghz or Ethernet

+ 41 - 0
docs/chapter/started/4.md

@@ -0,0 +1,41 @@
+["Installation Guide"]
+
+## Installation
+### For Raspberry Pi (For Raspberry Pi 4B+)
+
+If you are using Raspberry Pi as your host, you can download one of the images and flash the image into your SD card. You will find a new network device named "ArozOS (ARxxx)" pop up in your "Network Neighbourhood". 
+Double click the icon and you will be redirect to the system Web setup interface.
+
+You can find the links of the image in the README file of the Github repo.
+
+[https://github.com/tobychui/arozos](https://github.com/tobychui/arozos)
+
+
+
+To optain the .img file, you can unzip the compressed image using 7zip. If you don't have it, you can get it here
+
+### For other ARM SBC(e.g. Orange Pi / Banana Pi / Friendly ARM's Pis)
+
+Download the correct architecture binary from the "release" tab and upload the binary with the "web" and "system" folder in "/src". After upload, you should have the following file structure
+
+```
+$ ls
+aroz_online_linux_arm64  web  system
+```
+
+Start the binary by calling sudo ./aroz_online_linux_arm64 (or without sudo if you prefer no hardware management)
+
+### Windows
+
+If you are deploying on Windows, you need to add ffmpeg to %PATH% environment variable.
+
+This system can be built and run on Windows hosts with the following build instructions
+
+```
+# Download the whole repo as zip and cd into it
+cd .\arozos\src\
+go build
+arozos.exe
+```
+
+However, not all features are available for Windows.

+ 67 - 0
docs/chapter/started/5.md

@@ -0,0 +1,67 @@
+["System Overview"]
+
+## System Overview
+
+### Folder Structure
+
+Arozos consists of three major components in its folder structure. The folder structure is listed as follows.
+
+| Structure Name | Location                 | Purpose                                                      |
+| -------------- | ------------------------ | ------------------------------------------------------------ |
+| Web            | ./web                    | Directory for storing WebApp scripts (including System GUI elements) |
+| System         | ./system                 | Directory for storing system folders. Databases, templates and other important files are stored here. This should not be exposed via the storage pool handler. |
+| Subservice     | ./subservice             | Subservice that mount to arozos. Allowing arozos to perform reverse proxy access to these web services binaries. |
+| Arozos Binary  | ./arozos (or arozos.exe) | The executable of the main logic of arozos system            |
+
+### Application Structures
+
+As arozos move away from PHP, there is no way to dynamically add modules or plugins into a pre-compiled binary. Hence, there are two new methods to add plugins into the system. 
+
+1. WebApps - Basic WebApps where main logic is handled by JavaScript and RESTFUL
+2. Subservices - Advance WebApps where the application require complex access to the underlying operating system
+
+In the following sections, the structure of the methods will be introduced. For details about developing a plugin for arozos, please see the WebApp and Subservice sections.
+
+
+
+#### WebApp Structure
+
+Arozos Web Applications (or WebApps) are stored under the ./web folder. Each folder contain a list of html, JavaScript and CSS files that can be served via the arozos internal web server. A generic folder structure of a WebApp should consist of the following files.
+
+| Filename           | Purpose                                    | Mandatory |
+| ------------------ | ------------------------------------------ | --------- |
+| init.agi           | Define the WebApp startup properties       | Yes       |
+| index.html         | Index of WebApp to serve                   | Yes       |
+| */icon.png         | The icon for this module                   | Yes       |
+| */desktop_icon.png | The icon for showing as a desktop shortcut | No        |
+| embedded.html      | The embedded mode UI                       | Depends   |
+| floatWindow.html   | The float window mode UI                   | Depends   |
+| manifest.json      | The required manifest for supporting PWA   | Recommend |
+
+Notes that the init.agi is mandatory and it must be placed under your WebApp roots (i.e. ```./web/{webapp_name}/init.agi```). Or otherwise, your WebApp will not be scanned by the arozos startup process.
+
+#### Subservice Structures
+
+Subservice are web server binaries that are stored under ./subservice folder and provide services that require much higher levels of complexity. A basic subservices contain the following file structures.
+
+
+
+| Filename                                    | Purpose                                                      | Mandatory |
+| ------------------------------------------- | ------------------------------------------------------------ | --------- |
+| {subservice_name}_{platform}_{architecture} | The binary of the subservice                                 | Yes       |
+| .disabled                                   | Flags to disable this subservice on startup                  | No        |
+| .startscript                                | Flags to load start script for registration instead of the binary itself | No        |
+| moduleInfo.json                             | The module information JSON                                  | Depends   |
+| start.sh (or start.bat)                     | The startup script that replace the -info flag in subservice startup parameter | Depends   |
+
+
+
+Depending on your platform and subservice name the binary name may differ according. 
+
+For example, here is a subservice named “demo” with support linux (arm, arm64 and amd64), MacOS(darwin) and Windows. Its binary files will look like this under Windows’ File Explorer.
+
+![2020-12-06_16-23-58](../../img/5/2020-12-06_16-23-58.png)
+
+
+
+In some cases where gluing scripts are used, there might be a few more bash files or extra binaries. In this case, you will need to assign suitable permission to these files before starting arozos core. Permission denied of executing files inside subservice will lead to failure of starting of arozos system. 

+ 21 - 0
docs/chapter/started/6.md

@@ -0,0 +1,21 @@
+["System Abstraction Structure"]
+
+## System Abstraction Structure
+
+The arozos system consists of many layers of complex abstraction for emulating an operating system on any cloud platform or host devices. The following diagram provides an abstract view of the system abstraction structure. 
+
+![Overall structure diagram](../../img/6/Overall%20structure%20diagram.png)
+
+In simple words, the arozos structure is mainly consists of the following modules
+
+1. Authentication System
+2. Permission Router
+3. Reverse Proxy Server
+4. ArOZ Gateway Interface (AGI) JavaScript Interpreter
+5. Network Services (SSDP / MDNS / UPNP)
+6. Permission Group System
+7. Storage Quota Management System
+8. Storage Pool Management System (Including Path Virtualization)
+
+
+

+ 64 - 0
docs/chapter/started/7.md

@@ -0,0 +1,64 @@
+["User Interface"]
+
+## User Interface Structure
+
+In arozos, the original “Grid Interface” introduced in Beta has been removed due to most users will just directly launch into their Desktop interface. For that, a new interface is introduced to replace the grid interface as the default interface module for mobile devices. In the arozos UI implementation, the system default supports three kinds of UI.
+
+1. Web Desktop Interface
+2. Mobile Desktop Interface
+3. Interface Module Interface
+
+For beta version of aroz, the interface includes
+
+1. Grid Menu Interface
+2. Web Desktop Interface
+3. Multi System Booting Interface (MSBI)
+
+### Web Desktop Interface
+
+The arozos Web Desktop Interface is a complete rewritten of the original desktop interface and provides better user experience compared to the Beta Desktop. 
+
+![image9](../../img/7/image9.png)
+
+Arozos Web Desktop Interface preview, captured on v1.106
+
+![image12](../../img/7/image12.png)
+
+ArOZ Online Beta Web Desktop Interface, capture on Beta LTS
+
+For basic usage, the Web Desktop supports creating new folders, uploading Files by drag drop, double click opening files, folder or application shortcuts etc. See Desktop for more information.
+
+In arozos 1.0, a top menu is added to show time, volume info and Ubuntu 20.04, also provide a notification bar as well as a quick dropdown function menu for access to quick functions including full screen toggle, system settings and user logout.
+
+
+
+### Mobile Desktop Interface
+
+Mobile Desktop Interface was first introduce in arozos 1.105 for supporting vertical screens (Mostly mobile devices). In this mode, the floatWindow is still supported with limited functions. The list menu and toolbar are also replaced with a sidebar instead. However, this interface did allow multi-processing just like the standard Desktop interface. 
+
+
+
+| List Menu                           | Tool Sidebar                      | Opening Applications                |
+| ----------------------------------- | --------------------------------- | ----------------------------------- |
+| ![image19](../../img/7/image19.jpg) | ![image8](../../img/7/image8.jpg) | ![image16](../../img/7/image16.jpg) |
+
+
+
+### Grid Menu Interface
+
+The Grid Menu interface is a deprecated interface designed for ArOZ Online Beta (AOB) users for using the system on mobile devices. It is also the first interface of the ArOZ Online System that provides access to all system modules within one interface.
+
+![image22](../../img/7/image22-1607244087682.png)
+
+This interface is deprecated and no longer available on the arozos 1.0. This function has been replaced by the List Men on the mobile desktop interface, and there is no method to enable this feature in arozos 1.0.
+
+### IMUS Multi System Booting Interface (MSBI / IMSB)
+
+MSBI is the original method for binding service together using a bootloader like system for aroz online beta. It provides a very basic portal for redirecting users to different network services within the same host environment. 
+
+![image5](../../img/7/image5-1607244139602.png)
+
+For example, multiple of ArOZ Online Beta can be installed on the same machine using the MSBI tool as the main router.
+
+This interface has been deprecated and replaced by the subservice module (functional wise) and permission group interface module settings (Selection wise). For more detail, see the “Interface Module” section.
+

BIN
docs/img/5/2020-12-06_16-23-58.png


BIN
docs/img/6/Overall structure diagram.png


BIN
docs/img/7/image12.png


BIN
docs/img/7/image16.jpg


BIN
docs/img/7/image19.jpg


BIN
docs/img/7/image22-1607244087682.png


BIN
docs/img/7/image5-1607244139602.png


BIN
docs/img/7/image8.jpg


BIN
docs/img/7/image9.png


+ 1 - 1
docs/index.html

@@ -36,7 +36,7 @@
       <div class="one-half column" style="margin-top: 25%">
         <h4>arozos</h4>
         <p>General purpose Web Desktop Operating System for Raspberry Pis and low power SBCs.<br>Read more over <a href="https://github.com/tobychui/arozos">Github</a></p>
-		<a class="button button-primary" href="reader.html#started">Getting Started</a>
+		<a class="button button-primary" href="reader/standard/reader.html#%7B%22chapter%22%3A%22started%22%2C%22page%22%3A0%7D">Getting Started</a>
 	  </div>
 	  <div class="one-half column" style="margin-top: 15%">
 		<img src="img/ok.png">

+ 59 - 21
docs/reader.html → docs/reader/standard/reader.html

@@ -12,7 +12,7 @@
 <script src="https://cdnjs.cloudflare.com/ajax/libs/tocas-ui/2.3.3/tocas.js"></script>
 <link href="//fonts.googleapis.com/css?family=Raleway:400,300,600" rel="stylesheet" type="text/css">
 
-<script src="showdown.min.js"></script>
+<script src="../../showdown.min.js"></script>
 <style>
 
 p,div,span,h1,h2,h3,h4,h5{
@@ -51,7 +51,7 @@ pre{
 <body>
 <div class="ts demo left sidebar" style="width:400px !important;">
     <div class="ts header">
-        ArOZ Online System Documentation
+        ArozOS Documentation
 		<div id="lang" class="sub header" href="index.html"></div>
     </div>
     <div class="ts top attached tabbed menu">
@@ -62,7 +62,7 @@ pre{
 		
 	</div>
 	<div style="width:100%;" align="right">
-		<a href="index.html">Exit <i class="log out icon"></i></a>
+		<a href="../../index.html">Exit <i class="log out icon"></i></a>
 	</div>
 	
 </div>
@@ -84,7 +84,7 @@ pre{
 </div>
 <div class="ts divider"></div>
 <div class="ts basic segment">
-ArOZ Documentation Reader v1.1
+ArOZ Documentation Reader v1.2
 </div>
 <br><br><br><br>
 </div>
@@ -92,19 +92,42 @@ ArOZ Documentation Reader v1.1
 <script>
 var currentRenderPage = 0;
 var searchingPage = 0; 
-var lang = window.location.hash.replace("#",""); //get lang id
+var state; //get lang id
 var docs = []; //All documents will be loaded into memory as the reader loads, but not rendered yet
 var docsTitles = [];
-var baseFolder = "lang/" + lang + "/";
+var rootFolder = "../../chapter/";
+var baseFolder = rootFolder + "default/";
 var sidebarMode = "index"; //Either index or stars
 var staredPages = [];
-initLoad();
-$("#lang").text("Language: " + lang);
-//Check if there are stared pages. If yes, load them
-if (localStorage.getItem(lang) !== null) {
-	staredPages = JSON.parse(localStorage.getItem(lang));
+
+//Parse the system state from hash
+if (window.location.hash.length > 1){
+	try{
+		state = JSON.parse(decodeURIComponent(window.location.hash.substr(1)));
+		baseFolder = rootFolder + state.chapter + "/";
+		let targetPageNumber = state.page;
+		initLoad(function(){
+			//Callback after all document loaded.
+			if (targetPageNumber != undefined){
+				currentRenderPage = state.page;
+				readDoc();
+			}
+		});
+		
+		$("#lang").text("Chapter: " + state.chapter);
+		//Check if there are stared pages. If yes, load them
+		if (localStorage.getItem(state.chapter) !== null) {
+			staredPages = JSON.parse(localStorage.getItem(state.chapter));
+		}
+
+	}catch(ex){
+		alert("Failed to parse chapter information")
+	}
+	
 }
 
+
+
 function starThisPage(){
 	for (var i =0; i < staredPages.length; i++){
 		if (staredPages[i][0] == currentRenderPage){
@@ -178,7 +201,7 @@ function toggleList(){
 
 function redirectDoc(indexID){
 	currentRenderPage = indexID;
-	readDoc();
+	readDoc(true);
 	toggleList();
 }
 
@@ -196,7 +219,7 @@ function reloadAllDocs(){
 	docsTitles=[];
 }
 
-function loadAllDocs(){
+function loadAllDocs(callback=undefined){
 	$.ajax({
 		type: 'get',
 		timeout: 5000,
@@ -206,7 +229,7 @@ function loadAllDocs(){
 			docs.push(data.split("\n"));
 			//console.log(data.split("\n"));
 			searchingPage++;
-			loadAllDocs();
+			loadAllDocs(callback);
 		},
 		error:function (xhr, ajaxOptions, thrownError){
 			//End of documentation
@@ -214,7 +237,10 @@ function loadAllDocs(){
 			readDoc(); //Start rendering
 			parseDocList(); //Update the doc list
 			renderDocsList(); //Render the documentation list
-		}
+			if (callback != undefined){
+				callback();
+			}
+		}	
 	});
 }
 
@@ -225,7 +251,7 @@ function nextPage(){
 		currentRenderPage = currentRenderPage - 1;
 		return;
 	}
-	readDoc();
+	readDoc(true);
 }
 
 
@@ -236,10 +262,10 @@ function lastPage(){
 		currentRenderPage = currentRenderPage + 1;
 		return;
 	}
-	readDoc();
+	readDoc(true);
 }
 
-function readDoc(){
+function readDoc(rememberState=false){
 	let pageInfo = Array.from(docs[currentRenderPage]);
 	var metaTag = JSON.parse(pageInfo.shift());
 	document.title = metaTag[0];
@@ -248,6 +274,16 @@ function readDoc(){
 	pageInfo = pageInfo.join("\n");
 	$("#docLoader").append(md2html(pageInfo));
 	updateStartedIcon();
+
+	if (rememberState){
+		updateWindowHash();
+	}
+}
+
+function updateWindowHash(){
+	state["page"] = currentRenderPage;
+	window.location.hash = encodeURIComponent(JSON.stringify(state))
+
 }
 
 function parseDocList(){
@@ -259,12 +295,14 @@ function parseDocList(){
 }
 
 function md2html(input){
-	var converter = new showdown.Converter();
+	var converter = new showdown.Converter({
+		tables: true,
+	});
 	return converter.makeHtml(input);
 }
 
 //Initiate the loading interface
-function initLoad(){
+function initLoad(callback){
 	$("#docLoader").html('<div align="center" style="width:100%;">\
 		<br><br>\
 		<i class="big spinner loading icon stillLoading"></i><br>\
@@ -272,7 +310,7 @@ function initLoad(){
 		<br><br>\
 	</div>');
 	setTimeout(chkLoadFail,15000);
-	loadAllDocs();
+	loadAllDocs(callback);
 }
 
 //Check if the load failed using setTimeout