¶ CasaOS development
Hi! We are really excited that you are interested in contributing to CasaOS. Before submitting your contribution, please make sure to take a moment and read through the following guidelines.
¶ Prerequisites
- You should be familiar with Golang and shell scripting for backend development, or Vue.js for frontend development.
- You should be familiar with Git and whole pull request (PR) process on GitHub.
¶ Pull Request Guidelines
- The main branch is just a snapshot of the latest stable release. All development should be done in dedicated branches. Do not submit PRs against the main branch.
- Checkout a topic branch from the relevant branch, e.g. dev, and merge back against that branch.
- It's OK to have multiple small commits as you work on the PR - GitHub will automatically squash it before merging.
- If adding a new feature:
- Provide a convincing reason to add this feature. Ideally, you should open a suggestion issue first and have it approved before working on it.
- If fixing bug:
- If you are resolving a special issue, add
(fix #xxxx[,#xxxx])(#xxxxis the issue id) in your PR title for a better release log, e.g.update entities encoding/decoding (fix #3899). - Provide a detailed description of the bug in the PR. Live demo preferred.
- If you are resolving a special issue, add
¶ API
- Gateway API (not ready yet)
- UserService API (only limited APIs available)
- LocalStorage API
- AppManagement API
- MessageBus API
¶ Architecture
¶ Dev Environment Setup
The setup below is not the only way to get started on CasaOS development. Feel free to apply any experience and practices you are more comfortable with.
¶ Go
-
Download from https://go.dev/dl/
-
Extract
godirectory and move to$HOME/.local/go(or any directory you like) -
Ensure
~/.profilecontains following line at the bottom（or place with the directory you selected in previous step）PATH="$HOME/.local/go/bin:$HOME/go/bin:$PATH"The two paths differ as follow
$HOME/.local/go- Go root path, contains core, docs and libaries of Go$HOME/go- Go tool path, contains tools and dependencies
-
Make sure
go versionreturns
¶ Other build tools
-
Install
goreleaser- (one time)go install github.com/goreleaser/goreleaser@latest -
Install compilers - (one time)
sudo apt-get --no-install-recommends install upx \ gcc libc6-dev-amd64-cross \ gcc-aarch64-linux-gnu libc6-dev-arm64-cross \ gcc-arm-linux-gnueabihf libc6-dev-armhf-cross
¶ VSCode
-
Install https://code.visualstudio.com/
-
Install extensions
- https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck
- https://marketplace.visualstudio.com/items?itemName=golang.Go
- https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi
- https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh
-(If accessing from a Windows / Mac platform via SSH, install this extension)
-
Make sure following setting is in the VSCode
settings.json{ "go.goroot": "~/.local/go", "go.gopath": "~/go" }The two paths differ as follow
go.goroot- Go root path, contains core, docs and libaries of Gogo.gopath- Go tool path, contains tools and dependencies
-
Additional recommended settings (but not required)
{ "git.autofetch": "all", "go.delveConfig": { "showGlobalVariables": true, }, "go.diagnostic.vulncheck": "Imports", "go.inlayHints.assignVariableTypes": true, "go.inlayHints.compositeLiteralFields": true, "go.inlayHints.compositeLiteralTypes": true, "go.inlayHints.constantValues": true, "go.inlayHints.functionTypeParameters": true, "go.inlayHints.parameterNames": true, "go.inlayHints.rangeVariableTypes": true, "go.lintFlags": [ "-D", "staticcheck", "-E", "gocyclo,gosec,makezero,prealloc,revive,usestdlibvars" ], "go.lintTool": "golangci-lint", "go.lintOnSave": "workspace", "go.toolsManagement.autoUpdate": true, "gopls": { "formatting.gofumpt": true, "ui.diagnostic.analyses": { "fieldalignment": true, "nilness": true, "shadow": true, "unusedparams": true, "unusedvariable": true, "unusedwrite": true, "useany": true, }, "ui.semanticTokens": true, "ui.diagnostic.staticcheck": true, }, }These settings can greatly help productivity of Golang coding.
- See https://code.visualstudio.com/docs/languages/go for details about Go extension.
- See https://golangci-lint.run/usage/linters/ for linters enabled in the settings.
- See https://github.com/mvdan/gofumpt for better formatting than the default
gofmt.
¶ Git - (one time)
-
Install
gitsudo apt-get --no-install-recommends install git -
Clone following repositories
git clone git@github.com:IceWhaleTech/CasaOS-Common.git git clone git@github.com:IceWhaleTech/CasaOS-CLI.git git clone git@github.com:IceWhaleTech/CasaOS-Gateway.git git clone git@github.com:IceWhaleTech/CasaOS-MessageBus.git git clone git@github.com:IceWhaleTech/CasaOS-UserService.git git clone git@github.com:IceWhaleTech/CasaOS-LocalStorage.git git clone git@github.com:IceWhaleTech/CasaOS-AppManagement.git git clone git@github.com:IceWhaleTech/CasaOS.git -
Create a VSCode Workspace of all repositories
You can either manually add each repository one by one in the VSCode UI, or create a
.code-workspacefile at the common path like below.$ cat CasaOS.code-workspace { "folders": [ { "path": "CasaOS-Common" }, { "path": "CasaOS-CLI" }, { "path": "CasaOS-Gateway" }, { "path": "CasaOS-MessageBus" }, { "path": "CasaOS-UserService" }, { "path": "CasaOS-LocalStorage" }, { "path": "CasaOS-AppManagement" }, { "path": "CasaOS" }, { "path": "get" } ], "settings": {} } -
Open any
main.goand installGorelated tools when prompted
¶ Build
-
Try to build a binary
Taking CasaOS-LocalStorage for example here.
Run under path
./CasaOS-LocalStoragegoreleaser build --clean --snapshot -f .goreleaser.debug.yaml --id casaos-local-storage-amd64Verify it is built fine
$ dist/casaos-local-storage-amd64_linux_amd64_v1/build/sysroot/usr/bin/casaos-local-storage -v v0.3.7 -
Try to build packages for all architectures
goreleaser release --clean --snapshot
¶ Setup and Debug
-
Install official CasaOS as base setup - (one time)
curl -fsSL get.casaos.io | sudo bashVisit http://localhost to verify
-
Stop corresponding service of whose code you would like to work on - because you will run it manually as part of debugging.
-
Start debugger adapter
You could debug the code directly like in any other regular Golang coding.
However because CasaOS requires root permission for certain features, like controlling systemd daemons, formatting harddrives, etc., we use this approach to place a wrapper under
sudoso we can run our code under root permission later.sudo $HOME/go/bin/dlv dap --listen=:2345 --only-same-user=false -
Make your changes to the code and build the binary
goreleaser build --clean --snapshot -f .goreleaser.debug.yaml --id casaos-local-storage-amd64 -
Create
launch.jsonfor each module - (one time)Taking CasaOS-LocalStorage for example here.
It launches the built binary from previous step under the debugger adapter, the wrapper, we setup earlier due to potential need of root permission.
{ "version": "0.2.0", "configurations": [ { "name": "LocalStorage (localhost)", "type": "go", "debugAdapter": "dlv-dap", "request": "launch", "port": 2345, "host": "127.0.0.1", "mode": "exec", "program": "${workspaceFolder}/dist/casaos-local-storage-amd64_linux_amd64_v1/build/sysroot/usr/bin/casaos-local-storage" } ] } -
Start debugging in VSCode
Hit Ctrl-Shift-D, then select LocalStorage (localhost) and hit F5
To verify the debug is running fine, set breakpoint at any place then trigger the corresponding logic and see if it is hit.
¶ Testing
¶ Installation
- Ubuntu (amd64 virtual machine)
- DietPi (amd64 physical)
- Armbian (arm64 physical)
- Raspbian (Raspberry Pi physical)
¶ Upgrade and Update
- Update v0.3.6 to the latest version from the settings interface (non-clean update)
- Update from the previous version to the latest version from the settings interface (non-clean update)
¶ Uninstall
- Complete uninstallation
- Uninstall while retaining files
¶ Store
- Application display (All, by category)
- Application details
- Installation of all recommended applications
- Display and open installed applications (if not running, start first)
- Import external docker-compose.yml for installation
- Install two apps simultaneously (occupying the same port) (pihole/ADGuard)
- Multi-language support
¶ AppStore Management (Command-line only)
- Add, delete, and display third-party stores
- Confirm third-party store applications are displayed and installable
¶ App Lifecycle
- Uninstall
- Configuration validity (including configuration restoration)
- Add personal tips
- Multi-language support
- Restart
- Start
- Application access to /DATA
- Shutdown
- Export Compose YAML and import
- Add external links
¶ Application Updates
- Storage mapping remains intact after upgrading
- Environment variables remain intact after upgrading
- Other configurations remain intact after upgrading
- Responsive prompts during update process (in red)
- Relevant prompts even when no update is required (in green)
¶ Listing of New and Old Applications
- On CasaOS upgraded from an older version, old applications appear in the application list with icons and can be started, stopped, and uninstalled
- Run pure container applications through docker run, which should appear in the application list with default icons and can be started, stopped, and uninstalled
¶ USB Drive
- Automatic mounting (displayed in the widget)
- Browse files after mounting
- Unmount
¶ Storage Space (MergerFS Not Enabled)
- Format storage
- Remove storage
- Create storage space
- UI area displays newly added hard disk
- Plug and unplug SATA disk
¶ Merging Space
- Enable MergeFS in the UI
- Verify file presence in Files after adding space
- Verify file presence in Files after reducing space
- App needs to be restarted after adding merge
- Prompt users about the possibility of data loss when reducing merge
- Disk dropout reminder
¶ Local
- Upload/download
- Create TXT file, save input content, and modify file name
- Create and modify folder names
- Normal playback of video/photos (preview, set as wallpaper)/music
- File multi-selection: copy, paste, cut, download, delete
¶ Local Area Network (LAN)
- Samba server - Mount any disk and path
- Samba server - Write and read files from Windows and macOS
- Samba client - Connect to Samba server from Windows, macOS, and Linux
¶ Online
- DropBox - Bind, download, upload files
- GoogleDrive - Bind, download, upload files
¶ FileDrop
- One-to-one file transfer - Verify normal functionality for sender and receiver
- One-to-many file transfer - Verify normal functionality for sender and receivers
- Verify proper display when navigating away from FlashSend page
- Check if memory is released upon exiting the web page
¶ BT/Magnet Link Download
- Download BT/magnet links to merged disk and play through internal Files and external Samba
- Download BT/magnet links to external