Restructure and expand contribution documentation
Moved contribution-related docs to docs/contribution/, added new guides and templates for contributors, and updated references in docs/README.md to point to the new locations. This improves organization and provides clearer onboarding and standards for new contributors.
This commit is contained in:
CanbiZ
parent
1e5627ea19
commit
3860b7a9fa
@ -9,7 +9,7 @@ Complete guide to all ProxmoxVED documentation - quickly find what you need.
|
|||||||
### 👤 **I want to...**
|
### 👤 **I want to...**
|
||||||
|
|
||||||
**Contribute a new application**
|
**Contribute a new application**
|
||||||
→ Start with: [CONTRIBUTION_GUIDE.md](CONTRIBUTION_GUIDE.md)
|
→ Start with: [contribution/README.md](contribution/README.md)
|
||||||
→ Then: [ct/DETAILED_GUIDE.md](ct/DETAILED_GUIDE.md) + [install/DETAILED_GUIDE.md](install/DETAILED_GUIDE.md)
|
→ Then: [ct/DETAILED_GUIDE.md](ct/DETAILED_GUIDE.md) + [install/DETAILED_GUIDE.md](install/DETAILED_GUIDE.md)
|
||||||
|
|
||||||
**Understand the architecture**
|
**Understand the architecture**
|
||||||
@ -37,7 +37,7 @@ Complete guide to all ProxmoxVED documentation - quickly find what you need.
|
|||||||
### **I'm a...**
|
### **I'm a...**
|
||||||
|
|
||||||
**New Contributor**
|
**New Contributor**
|
||||||
→ Start: [CONTRIBUTION_GUIDE.md](CONTRIBUTION_GUIDE.md)
|
→ Start: [contribution/README.md](contribution/README.md)
|
||||||
→ Then: Choose your path below
|
→ Then: Choose your path below
|
||||||
|
|
||||||
**Container Creator**
|
**Container Creator**
|
||||||
@ -93,7 +93,7 @@ ProxmoxVED/
|
|||||||
|
|
||||||
| Document | Purpose | Audience |
|
| Document | Purpose | Audience |
|
||||||
|----------|---------|----------|
|
|----------|---------|----------|
|
||||||
| [CONTRIBUTION_GUIDE.md](CONTRIBUTION_GUIDE.md) | How to contribute | Contributors |
|
| [contribution/README.md](contribution/README.md) | How to contribute | Contributors |
|
||||||
| [ct/DETAILED_GUIDE.md](ct/DETAILED_GUIDE.md) | Create ct scripts | Container developers |
|
| [ct/DETAILED_GUIDE.md](ct/DETAILED_GUIDE.md) | Create ct scripts | Container developers |
|
||||||
| [install/DETAILED_GUIDE.md](install/DETAILED_GUIDE.md) | Create install scripts | Installation developers |
|
| [install/DETAILED_GUIDE.md](install/DETAILED_GUIDE.md) | Create install scripts | Installation developers |
|
||||||
| [TECHNICAL_REFERENCE.md](TECHNICAL_REFERENCE.md) | Architecture deep-dive | Architects, advanced users |
|
| [TECHNICAL_REFERENCE.md](TECHNICAL_REFERENCE.md) | Architecture deep-dive | Architects, advanced users |
|
||||||
@ -171,7 +171,7 @@ Documentation for `/misc` - 9 core function libraries with complete references.
|
|||||||
|
|
||||||
### Path 1: First-Time Contributor (2-3 hours)
|
### Path 1: First-Time Contributor (2-3 hours)
|
||||||
|
|
||||||
1. [CONTRIBUTION_GUIDE.md](CONTRIBUTION_GUIDE.md) - Quick Start
|
1. [contribution/README.md](contribution/README.md) - Quick Start
|
||||||
2. Pick your area:
|
2. Pick your area:
|
||||||
- Containers → [ct/README.md](ct/README.md) + [ct/DETAILED_GUIDE.md](ct/DETAILED_GUIDE.md)
|
- Containers → [ct/README.md](ct/README.md) + [ct/DETAILED_GUIDE.md](ct/DETAILED_GUIDE.md)
|
||||||
- Installation → [install/README.md](install/README.md) + [install/DETAILED_GUIDE.md](install/DETAILED_GUIDE.md)
|
- Installation → [install/README.md](install/README.md) + [install/DETAILED_GUIDE.md](install/DETAILED_GUIDE.md)
|
||||||
@ -238,7 +238,7 @@ Documentation for `/misc` - 9 core function libraries with complete references.
|
|||||||
- **Package error?** → [misc/tools.func/](misc/tools.func/)
|
- **Package error?** → [misc/tools.func/](misc/tools.func/)
|
||||||
|
|
||||||
### By Role
|
### By Role
|
||||||
- **Contributor** → [CONTRIBUTION_GUIDE.md](CONTRIBUTION_GUIDE.md)
|
- **Contributor** → [contribution/README.md](contribution/README.md)
|
||||||
- **Operator** → [DEFAULTS_SYSTEM_GUIDE.md](DEFAULTS_SYSTEM_GUIDE.md)
|
- **Operator** → [DEFAULTS_SYSTEM_GUIDE.md](DEFAULTS_SYSTEM_GUIDE.md)
|
||||||
- **Developer** → [TECHNICAL_REFERENCE.md](TECHNICAL_REFERENCE.md)
|
- **Developer** → [TECHNICAL_REFERENCE.md](TECHNICAL_REFERENCE.md)
|
||||||
- **Architect** → [misc/README.md](misc/README.md)
|
- **Architect** → [misc/README.md](misc/README.md)
|
||||||
@ -262,7 +262,7 @@ Documentation for `/misc` - 9 core function libraries with complete references.
|
|||||||
|
|
||||||
## 🚀 **Start Here**
|
## 🚀 **Start Here**
|
||||||
|
|
||||||
**New to ProxmoxVED?** → [CONTRIBUTION_GUIDE.md](CONTRIBUTION_GUIDE.md)
|
**New to ProxmoxVED?** → [contribution/README.md](contribution/README.md)
|
||||||
|
|
||||||
**Looking for something specific?** → Choose your role above or browse by directory
|
**Looking for something specific?** → Choose your role above or browse by directory
|
||||||
|
|
||||||
@ -276,9 +276,9 @@ Documentation for `/misc` - 9 core function libraries with complete references.
|
|||||||
|
|
||||||
Found an error? Want to improve docs?
|
Found an error? Want to improve docs?
|
||||||
|
|
||||||
1. Open issue: [GitHub Issues](https://github.com/community-scripts/ProxmoxVED/issues)
|
1. See: [contribution/README.md](contribution/README.md) for full contribution guide
|
||||||
2. Or submit PR with improvements
|
2. Open issue: [GitHub Issues](https://github.com/community-scripts/ProxmoxVED/issues)
|
||||||
3. See [CONTRIBUTION_GUIDE.md](CONTRIBUTION_GUIDE.md) for details
|
3. Or submit PR with improvements
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
14
docs/contribution/CODE-AUDIT.md
Normal file
14
docs/contribution/CODE-AUDIT.md
Normal file
@ -0,0 +1,14 @@
|
|||||||
|
<div align="center">
|
||||||
|
<img src="https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/images/logo.png" height="100px" />
|
||||||
|
</div>
|
||||||
|
<h2><div align="center">Exploring the Scripts and Steps Involved in an Application LXC Installation</div></h2>
|
||||||
|
|
||||||
|
1) [adguard.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/ct/adguard.sh): This script collects system parameters. (Also holds the function to update the application.)
|
||||||
|
2) [build.func](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/build.func): Adds user settings and integrates collected information.
|
||||||
|
3) [create_lxc.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/create_lxc.sh): Constructs the LXC container.
|
||||||
|
4) [adguard-install.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/install/adguard-install.sh): Executes functions from [install.func](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/install.func), and installs the application.
|
||||||
|
5) [adguard.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/ct/adguard.sh) (again): To display the completion message.
|
||||||
|
|
||||||
|
The installation process uses reusable scripts: [build.func](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/build.func), [create_lxc.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/create_lxc.sh), and [install.func](https://github.com/community-scripts/ProxmoxVE/blob/main/misc/install.func), which are not specific to any particular application.
|
||||||
|
|
||||||
|
To gain a better understanding, focus on reviewing [adguard-install.sh](https://github.com/community-scripts/ProxmoxVE/blob/main/install/adguard-install.sh). This script contains the commands and configurations for installing and configuring AdGuard Home within the LXC container.
|
||||||
106
docs/contribution/CONTRIBUTING.md
Normal file
106
docs/contribution/CONTRIBUTING.md
Normal file
@ -0,0 +1,106 @@
|
|||||||
|
|
||||||
|
# Community Scripts Contribution Guide
|
||||||
|
|
||||||
|
## **Welcome to the communty-scripts Repository!**
|
||||||
|
|
||||||
|
📜 These documents outline the essential coding standards for all our scripts and JSON files. Adhering to these standards ensures that our codebase remains consistent, readable, and maintainable. By following these guidelines, we can improve collaboration, reduce errors, and enhance the overall quality of our project.
|
||||||
|
|
||||||
|
### Why Coding Standards Matter
|
||||||
|
|
||||||
|
Coding standards are crucial for several reasons:
|
||||||
|
|
||||||
|
1. **Consistency**: Consistent code is easier to read, understand, and maintain. It helps new team members quickly get up to speed and reduces the learning curve.
|
||||||
|
2. **Readability**: Clear and well-structured code is easier to debug and extend. It allows developers to quickly identify and fix issues.
|
||||||
|
3. **Maintainability**: Code that follows a standard structure is easier to refactor and update. It ensures that changes can be made with minimal risk of introducing new bugs.
|
||||||
|
4. **Collaboration**: When everyone follows the same standards, it becomes easier to collaborate on code. It reduces friction and misunderstandings during code reviews and merges.
|
||||||
|
|
||||||
|
### Scope of These Documents
|
||||||
|
|
||||||
|
These documents cover the coding standards for the following types of files in our project:
|
||||||
|
|
||||||
|
- **`install/$AppName-install.sh` Scripts**: These scripts are responsible for the installation of applications.
|
||||||
|
- **`ct/$AppName.sh` Scripts**: These scripts handle the creation and updating of containers.
|
||||||
|
- **`json/$AppName.json`**: These files store structured data and are used for the website.
|
||||||
|
|
||||||
|
Each section provides detailed guidelines on various aspects of coding, including shebang usage, comments, variable naming, function naming, indentation, error handling, command substitution, quoting, script structure, and logging. Additionally, examples are provided to illustrate the application of these standards.
|
||||||
|
|
||||||
|
By following the coding standards outlined in this document, we ensure that our scripts and JSON files are of high quality, making our project more robust and easier to manage. Please refer to this guide whenever you create or update scripts and JSON files to maintain a high standard of code quality across the project. 📚🔍
|
||||||
|
|
||||||
|
Let's work together to keep our codebase clean, efficient, and maintainable! 💪🚀
|
||||||
|
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
Before contributing, please ensure that you have the following setup:
|
||||||
|
|
||||||
|
1. **Visual Studio Code** (recommended for script development)
|
||||||
|
2. **Recommended VS Code Extensions:**
|
||||||
|
- [Shell Syntax](https://marketplace.visualstudio.com/items?itemName=bmalehorn.shell-syntax)
|
||||||
|
- [ShellCheck](https://marketplace.visualstudio.com/items?itemName=timonwong.shellcheck)
|
||||||
|
- [Shell Format](https://marketplace.visualstudio.com/items?itemName=foxundermoon.shell-format)
|
||||||
|
|
||||||
|
### Important Notes
|
||||||
|
- Use [AppName.sh](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.sh) and [AppName-install.sh](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.sh) as templates when creating new scripts.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 🚀 The Application Script (ct/AppName.sh)
|
||||||
|
|
||||||
|
- You can find all coding standards, as well as the structure for this file [here](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.md).
|
||||||
|
- These scripts are responsible for container creation, setting the necessary variables and handling the update of the application once installed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 🛠 The Installation Script (install/AppName-install.sh)
|
||||||
|
|
||||||
|
- You can find all coding standards, as well as the structure for this file [here](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.md).
|
||||||
|
- These scripts are responsible for the installation of the application.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Building Your Own Scripts
|
||||||
|
|
||||||
|
Start with the [template script](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.sh)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤝 Contribution Process
|
||||||
|
|
||||||
|
### 1. Fork the repository
|
||||||
|
Fork to your GitHub account
|
||||||
|
|
||||||
|
### 2. Clone your fork on your local environment
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/yourUserName/ForkName
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Create a new branch
|
||||||
|
```bash
|
||||||
|
git switch -c your-feature-branch
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Change paths in build.func install.func and AppName.sh
|
||||||
|
To be able to develop from your own branch you need to change `https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main` to `https://raw.githubusercontent.com/[USER]/[REPOSITORY]/refs/heads/[BRANCH]`. You need to make this change atleast in misc/build.func misc/install.func and in your ct/AppName.sh. This change is only for testing. Before opening a Pull Request you should change this line change all this back to point to `https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main`.
|
||||||
|
|
||||||
|
### 4. Commit changes (without build.func and install.func!)
|
||||||
|
```bash
|
||||||
|
git commit -m "Your commit message"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Push to your fork
|
||||||
|
```bash
|
||||||
|
git push origin your-feature-branch
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Create a Pull Request
|
||||||
|
Open a Pull Request from your feature branch to the main repository branch. You must only include your **$AppName.sh**, **$AppName-install.sh** and **$AppName.json** files in the pull request.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 Pages
|
||||||
|
|
||||||
|
- [CT Template: AppName.sh](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/ct/AppName.sh)
|
||||||
|
- [Install Template: AppName-install.sh](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/install/AppName-install.sh)
|
||||||
|
- [JSON Template: AppName.json](https://github.com/community-scripts/ProxmoxVED/blob/main/.github/CONTRIBUTOR_AND_GUIDES/json/AppName.json)
|
||||||
|
|
||||||
|
|
||||||
186
docs/contribution/FORK_SETUP.md
Normal file
186
docs/contribution/FORK_SETUP.md
Normal file
@ -0,0 +1,186 @@
|
|||||||
|
# 🍴 Fork Setup Guide
|
||||||
|
|
||||||
|
**Just forked ProxmoxVED? Run this first!**
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Clone your fork
|
||||||
|
git clone https://github.com/YOUR_USERNAME/ProxmoxVED.git
|
||||||
|
cd ProxmoxVED
|
||||||
|
|
||||||
|
# Run setup script (auto-detects your username from git)
|
||||||
|
bash setup-fork.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
That's it! ✅
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What Does It Do?
|
||||||
|
|
||||||
|
The `setup-fork.sh` script automatically:
|
||||||
|
|
||||||
|
1. **Detects** your GitHub username from git config
|
||||||
|
2. **Updates** 22 hardcoded links in documentation to point to your fork
|
||||||
|
3. **Creates** `.git-setup-info` with recommended git workflows
|
||||||
|
4. **Backs up** all modified files (*.backup)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### Auto-Detect (Recommended)
|
||||||
|
```bash
|
||||||
|
bash setup-fork.sh
|
||||||
|
```
|
||||||
|
Automatically reads your GitHub username from `git remote origin url`
|
||||||
|
|
||||||
|
### Specify Username
|
||||||
|
```bash
|
||||||
|
bash setup-fork.sh john
|
||||||
|
```
|
||||||
|
Updates links to `github.com/john/ProxmoxVED`
|
||||||
|
|
||||||
|
### Custom Repository Name
|
||||||
|
```bash
|
||||||
|
bash setup-fork.sh john my-fork
|
||||||
|
```
|
||||||
|
Updates links to `github.com/john/my-fork`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What Gets Updated?
|
||||||
|
|
||||||
|
The script updates these documentation files:
|
||||||
|
- `docs/CONTRIBUTION_GUIDE.md` (4 links)
|
||||||
|
- `docs/README.md` (1 link)
|
||||||
|
- `docs/INDEX.md` (3 links)
|
||||||
|
- `docs/EXIT_CODES.md` (2 links)
|
||||||
|
- `docs/DEFAULTS_SYSTEM_GUIDE.md` (2 links)
|
||||||
|
- `docs/api/README.md` (1 link)
|
||||||
|
- `docs/APP-ct.md` (1 link)
|
||||||
|
- `docs/APP-install.md` (1 link)
|
||||||
|
- `docs/alpine-install.func.md` (2 links)
|
||||||
|
- `docs/install.func.md` (1 link)
|
||||||
|
- And code examples in documentation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## After Setup
|
||||||
|
|
||||||
|
1. **Review changes**
|
||||||
|
```bash
|
||||||
|
git diff docs/
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Read git workflow tips**
|
||||||
|
```bash
|
||||||
|
cat .git-setup-info
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Start contributing**
|
||||||
|
```bash
|
||||||
|
git checkout -b feature/my-app
|
||||||
|
# Make your changes...
|
||||||
|
git commit -m "feat: add my awesome app"
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Follow the guide**
|
||||||
|
```bash
|
||||||
|
cat docs/CONTRIBUTION_GUIDE.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Workflows
|
||||||
|
|
||||||
|
### Keep Your Fork Updated
|
||||||
|
```bash
|
||||||
|
# Add upstream if you haven't already
|
||||||
|
git remote add upstream https://github.com/community-scripts/ProxmoxVED.git
|
||||||
|
|
||||||
|
# Get latest from upstream
|
||||||
|
git fetch upstream
|
||||||
|
git rebase upstream/main
|
||||||
|
git push origin main
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create a Feature Branch
|
||||||
|
```bash
|
||||||
|
git checkout -b feature/docker-improvements
|
||||||
|
# Make changes...
|
||||||
|
git push origin feature/docker-improvements
|
||||||
|
# Then create PR on GitHub
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sync Before Contributing
|
||||||
|
```bash
|
||||||
|
git fetch upstream
|
||||||
|
git rebase upstream/main
|
||||||
|
git push -f origin main # Update your fork's main
|
||||||
|
git checkout -b feature/my-feature
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### "Git is not installed" or "not a git repository"
|
||||||
|
```bash
|
||||||
|
# Make sure you cloned the repo first
|
||||||
|
git clone https://github.com/YOUR_USERNAME/ProxmoxVED.git
|
||||||
|
cd ProxmoxVED
|
||||||
|
bash setup-fork.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### "Could not auto-detect GitHub username"
|
||||||
|
```bash
|
||||||
|
# Your git origin URL isn't set up correctly
|
||||||
|
git remote -v
|
||||||
|
# Should show your fork URL, not community-scripts
|
||||||
|
|
||||||
|
# Fix it:
|
||||||
|
git remote set-url origin https://github.com/YOUR_USERNAME/ProxmoxVED.git
|
||||||
|
bash setup-fork.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### "Permission denied"
|
||||||
|
```bash
|
||||||
|
# Make script executable
|
||||||
|
chmod +x setup-fork.sh
|
||||||
|
bash setup-fork.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### Reverted Changes by Accident?
|
||||||
|
```bash
|
||||||
|
# Backups are created automatically
|
||||||
|
git checkout docs/*.backup
|
||||||
|
# Or just re-run setup-fork.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
1. ✅ Run `bash setup-fork.sh`
|
||||||
|
2. 📖 Read [docs/CONTRIBUTION_GUIDE.md](docs/CONTRIBUTION_GUIDE.md)
|
||||||
|
3. 🍴 Choose your contribution path:
|
||||||
|
- **Containers** → [docs/ct/README.md](docs/ct/README.md)
|
||||||
|
- **Installation** → [docs/install/README.md](docs/install/README.md)
|
||||||
|
- **VMs** → [docs/vm/README.md](docs/vm/README.md)
|
||||||
|
- **Tools** → [docs/tools/README.md](docs/tools/README.md)
|
||||||
|
4. 💻 Create your feature branch and contribute!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Questions?
|
||||||
|
|
||||||
|
- **Fork Setup Issues?** → See [Troubleshooting](#troubleshooting) above
|
||||||
|
- **How to Contribute?** → [docs/CONTRIBUTION_GUIDE.md](docs/CONTRIBUTION_GUIDE.md)
|
||||||
|
- **Git Workflows?** → `cat .git-setup-info`
|
||||||
|
- **Project Structure?** → [docs/README.md](docs/README.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Happy Contributing! 🚀**
|
||||||
341
docs/contribution/README.md
Normal file
341
docs/contribution/README.md
Normal file
@ -0,0 +1,341 @@
|
|||||||
|
# 🤝 Contributing to ProxmoxVED
|
||||||
|
|
||||||
|
Complete guide to contributing to the ProxmoxVED project - from your first fork to submitting your pull request.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Table of Contents
|
||||||
|
|
||||||
|
- [Quick Start](#quick-start)
|
||||||
|
- [Setting Up Your Fork](#setting-up-your-fork)
|
||||||
|
- [Coding Standards](#coding-standards)
|
||||||
|
- [Code Audit](#code-audit)
|
||||||
|
- [Guides & Resources](#guides--resources)
|
||||||
|
- [FAQ](#faq)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Quick Start
|
||||||
|
|
||||||
|
### 60 Seconds to Contributing
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Fork on GitHub
|
||||||
|
# Visit: https://github.com/community-scripts/ProxmoxVED → Fork (top right)
|
||||||
|
|
||||||
|
# 2. Clone your fork
|
||||||
|
git clone https://github.com/YOUR_USERNAME/ProxmoxVED.git
|
||||||
|
cd ProxmoxVED
|
||||||
|
|
||||||
|
# 3. Auto-configure your fork
|
||||||
|
bash docs/contribution/setup-fork.sh
|
||||||
|
|
||||||
|
# 4. Create a feature branch
|
||||||
|
git checkout -b feature/my-awesome-app
|
||||||
|
|
||||||
|
# 5. Read the guides
|
||||||
|
cat docs/README.md # Documentation overview
|
||||||
|
cat docs/ct/DETAILED_GUIDE.md # For container scripts
|
||||||
|
cat docs/install/DETAILED_GUIDE.md # For install scripts
|
||||||
|
|
||||||
|
# 6. Create your contribution
|
||||||
|
cp ct/example.sh ct/myapp.sh
|
||||||
|
cp install/example-install.sh install/myapp-install.sh
|
||||||
|
# ... edit files ...
|
||||||
|
|
||||||
|
# 7. Test and commit
|
||||||
|
bash ct/myapp.sh
|
||||||
|
git add ct/myapp.sh install/myapp-install.sh
|
||||||
|
git commit -m "feat: add MyApp"
|
||||||
|
git push origin feature/my-awesome-app
|
||||||
|
|
||||||
|
# 8. Create Pull Request on GitHub
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🍴 Setting Up Your Fork
|
||||||
|
|
||||||
|
### Automatic Setup (Recommended)
|
||||||
|
|
||||||
|
When you clone your fork, run the setup script to automatically configure everything:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bash docs/contribution/setup-fork.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
This will:
|
||||||
|
- Auto-detect your GitHub username
|
||||||
|
- Update all documentation links to point to your fork
|
||||||
|
- Create `.git-setup-info` with recommended git workflows
|
||||||
|
|
||||||
|
**See**: [FORK_SETUP.md](FORK_SETUP.md) for detailed instructions
|
||||||
|
|
||||||
|
### Manual Setup
|
||||||
|
|
||||||
|
If the script doesn't work, manually configure:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Set git user
|
||||||
|
git config user.name "Your Name"
|
||||||
|
git config user.email "your.email@example.com"
|
||||||
|
|
||||||
|
# Add upstream remote for syncing
|
||||||
|
git remote add upstream https://github.com/community-scripts/ProxmoxVED.git
|
||||||
|
|
||||||
|
# Verify remotes
|
||||||
|
git remote -v
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📖 Coding Standards
|
||||||
|
|
||||||
|
All scripts and configurations must follow our coding standards to ensure consistency and quality.
|
||||||
|
|
||||||
|
### Available Guides
|
||||||
|
|
||||||
|
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Essential coding standards and best practices
|
||||||
|
- **[CODE_AUDIT.md](CODE_AUDIT.md)** - Code review checklist and audit procedures
|
||||||
|
- **Container Scripts** - `/ct/` templates and guidelines
|
||||||
|
- **Install Scripts** - `/install/` templates and guidelines
|
||||||
|
- **JSON Configurations** - `/json/` structure and format
|
||||||
|
|
||||||
|
### Quick Checklist
|
||||||
|
|
||||||
|
- ✅ Use `/ct/example.sh` as template for container scripts
|
||||||
|
- ✅ Use `/install/example-install.sh` as template for install scripts
|
||||||
|
- ✅ Follow naming conventions: `appname.sh` and `appname-install.sh`
|
||||||
|
- ✅ Include proper shebang: `#!/usr/bin/env bash`
|
||||||
|
- ✅ Add copyright header with author
|
||||||
|
- ✅ Handle errors properly with `msg_error`, `msg_ok`, etc.
|
||||||
|
- ✅ Test before submitting PR
|
||||||
|
- ✅ Update documentation if needed
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔍 Code Audit
|
||||||
|
|
||||||
|
Before submitting a pull request, ensure your code passes our audit:
|
||||||
|
|
||||||
|
**See**: [CODE_AUDIT.md](CODE_AUDIT.md) for complete audit checklist
|
||||||
|
|
||||||
|
Key points:
|
||||||
|
- Code consistency with existing scripts
|
||||||
|
- Proper error handling
|
||||||
|
- Correct variable naming
|
||||||
|
- Adequate comments and documentation
|
||||||
|
- Security best practices
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 Guides & Resources
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
|
||||||
|
- **[docs/README.md](../README.md)** - Main documentation hub
|
||||||
|
- **[docs/ct/README.md](../ct/README.md)** - Container scripts overview
|
||||||
|
- **[docs/install/README.md](../install/README.md)** - Installation scripts overview
|
||||||
|
- **[docs/ct/DETAILED_GUIDE.md](../ct/DETAILED_GUIDE.md)** - Complete ct/ script reference
|
||||||
|
- **[docs/install/DETAILED_GUIDE.md](../install/DETAILED_GUIDE.md)** - Complete install/ script reference
|
||||||
|
- **[docs/TECHNICAL_REFERENCE.md](../TECHNICAL_REFERENCE.md)** - Architecture deep-dive
|
||||||
|
- **[docs/EXIT_CODES.md](../EXIT_CODES.md)** - Exit codes reference
|
||||||
|
- **[docs/DEV_MODE.md](../DEV_MODE.md)** - Debugging guide
|
||||||
|
|
||||||
|
### Community Guides
|
||||||
|
|
||||||
|
See [USER_SUBMITTED_GUIDES.md](USER_SUBMITTED_GUIDES.md) for excellent community-written guides:
|
||||||
|
- Home Assistant installation and configuration
|
||||||
|
- Frigate setup on Proxmox
|
||||||
|
- Docker and Portainer installation
|
||||||
|
- Database setup and optimization
|
||||||
|
- And many more!
|
||||||
|
|
||||||
|
### Templates
|
||||||
|
|
||||||
|
Use these templates when creating new scripts:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Container script
|
||||||
|
cp ct/example.sh ct/my-app.sh
|
||||||
|
|
||||||
|
# Installation script
|
||||||
|
cp install/example-install.sh install/my-app-install.sh
|
||||||
|
|
||||||
|
# JSON configuration (if needed)
|
||||||
|
cp json/example.json json/my-app.json
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Git Workflow
|
||||||
|
|
||||||
|
### Keep Your Fork Updated
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Fetch latest from upstream
|
||||||
|
git fetch upstream
|
||||||
|
|
||||||
|
# Rebase your work on latest main
|
||||||
|
git rebase upstream/main
|
||||||
|
|
||||||
|
# Push to your fork
|
||||||
|
git push -f origin main
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create Feature Branch
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create and switch to new branch
|
||||||
|
git checkout -b feature/my-feature
|
||||||
|
|
||||||
|
# Make changes...
|
||||||
|
git add .
|
||||||
|
git commit -m "feat: description of changes"
|
||||||
|
|
||||||
|
# Push to your fork
|
||||||
|
git push origin feature/my-feature
|
||||||
|
|
||||||
|
# Create Pull Request on GitHub
|
||||||
|
```
|
||||||
|
|
||||||
|
### Before Submitting PR
|
||||||
|
|
||||||
|
1. **Sync with upstream**
|
||||||
|
```bash
|
||||||
|
git fetch upstream
|
||||||
|
git rebase upstream/main
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Test your changes**
|
||||||
|
```bash
|
||||||
|
bash ct/my-app.sh
|
||||||
|
# Follow prompts and test the container
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Check code standards**
|
||||||
|
- [ ] Follows template structure
|
||||||
|
- [ ] Proper error handling
|
||||||
|
- [ ] Documentation updated (if needed)
|
||||||
|
- [ ] No hardcoded values
|
||||||
|
- [ ] Version tracking implemented
|
||||||
|
|
||||||
|
4. **Push final changes**
|
||||||
|
```bash
|
||||||
|
git push origin feature/my-feature
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📋 Pull Request Checklist
|
||||||
|
|
||||||
|
Before opening a PR:
|
||||||
|
|
||||||
|
- [ ] Code follows coding standards (see CONTRIBUTING.md)
|
||||||
|
- [ ] All templates used correctly
|
||||||
|
- [ ] Tested on Proxmox VE
|
||||||
|
- [ ] Error handling implemented
|
||||||
|
- [ ] Documentation updated (if applicable)
|
||||||
|
- [ ] No merge conflicts
|
||||||
|
- [ ] Synced with upstream/main
|
||||||
|
- [ ] Clear PR title and description
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ❓ FAQ
|
||||||
|
|
||||||
|
### How do I test my changes?
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# For container scripts
|
||||||
|
bash ct/my-app.sh
|
||||||
|
|
||||||
|
# For install scripts (runs inside container)
|
||||||
|
# The ct script will call it automatically
|
||||||
|
|
||||||
|
# For advanced debugging
|
||||||
|
VERBOSE=yes bash ct/my-app.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### What if my PR has conflicts?
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Sync with upstream
|
||||||
|
git fetch upstream
|
||||||
|
git rebase upstream/main
|
||||||
|
|
||||||
|
# Resolve conflicts in your editor
|
||||||
|
git add .
|
||||||
|
git rebase --continue
|
||||||
|
git push -f origin your-branch
|
||||||
|
```
|
||||||
|
|
||||||
|
### How do I keep my fork updated?
|
||||||
|
|
||||||
|
See "Keep Your Fork Updated" section above, or run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bash docs/contribution/setup-fork.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### Where do I ask questions?
|
||||||
|
|
||||||
|
- **GitHub Issues**: For bugs and feature requests
|
||||||
|
- **GitHub Discussions**: For general questions
|
||||||
|
- **Discord**: Community-scripts server
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎓 Learning Resources
|
||||||
|
|
||||||
|
### For First-Time Contributors
|
||||||
|
|
||||||
|
1. Read: [docs/README.md](../README.md) - Documentation overview
|
||||||
|
2. Read: [docs/contribution/FORK_SETUP.md](FORK_SETUP.md) - Fork setup guide
|
||||||
|
3. Choose your path:
|
||||||
|
- Containers → [docs/ct/DETAILED_GUIDE.md](../ct/DETAILED_GUIDE.md)
|
||||||
|
- Installation → [docs/install/DETAILED_GUIDE.md](../install/DETAILED_GUIDE.md)
|
||||||
|
4. Study existing scripts in same category
|
||||||
|
5. Create your contribution
|
||||||
|
|
||||||
|
### For Experienced Developers
|
||||||
|
|
||||||
|
1. Review [CONTRIBUTING.md](CONTRIBUTING.md) - Coding standards
|
||||||
|
2. Review [CODE_AUDIT.md](CODE_AUDIT.md) - Audit checklist
|
||||||
|
3. Check templates in `/ct/` and `/install/`
|
||||||
|
4. Submit PR with confidence
|
||||||
|
|
||||||
|
### For Reviewers/Maintainers
|
||||||
|
|
||||||
|
1. Use [CODE_AUDIT.md](CODE_AUDIT.md) as review guide
|
||||||
|
2. Reference [docs/TECHNICAL_REFERENCE.md](../TECHNICAL_REFERENCE.md) for architecture
|
||||||
|
3. Check [docs/EXIT_CODES.md](../EXIT_CODES.md) for error handling
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Ready to Contribute?
|
||||||
|
|
||||||
|
1. **Fork** the repository
|
||||||
|
2. **Clone** your fork and **setup** with `bash docs/contribution/setup-fork.sh`
|
||||||
|
3. **Choose** your contribution type (container, installation, tools, etc.)
|
||||||
|
4. **Read** the appropriate detailed guide
|
||||||
|
5. **Create** your feature branch
|
||||||
|
6. **Develop** and **test** your changes
|
||||||
|
7. **Commit** with clear messages
|
||||||
|
8. **Push** to your fork
|
||||||
|
9. **Create** Pull Request
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📞 Contact & Support
|
||||||
|
|
||||||
|
- **GitHub**: https://github.com/community-scripts/ProxmoxVED
|
||||||
|
- **Issues**: https://github.com/community-scripts/ProxmoxVED/issues
|
||||||
|
- **Discussions**: https://github.com/community-scripts/ProxmoxVED/discussions
|
||||||
|
- **Discord**: [Join Server](https://discord.gg/UHrpNWGwkH)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Thank you for contributing to ProxmoxVED!** 🙏
|
||||||
|
|
||||||
|
Your efforts help make Proxmox VE automation accessible to everyone. Happy coding! 🚀
|
||||||
44
docs/contribution/USER_SUBMITTED_GUIDES.md
Normal file
44
docs/contribution/USER_SUBMITTED_GUIDES.md
Normal file
@ -0,0 +1,44 @@
|
|||||||
|
<div align="center">
|
||||||
|
<a href="#">
|
||||||
|
<img src="https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/misc/images/logo.png" height="100px" />
|
||||||
|
</a>
|
||||||
|
</div>
|
||||||
|
<h2 align="center">User Submitted Guides </h2>
|
||||||
|
|
||||||
|
<sub> In order to contribute a guide on installing with Proxmox VE Helper Scripts, you should open a pull request that adds the guide to the `USER_SUBMITTED_GUIDES.md` file. </sub>
|
||||||
|
|
||||||
|
[Proxmox Automation with Proxmox Helper Scripts!](https://www.youtube.com/watch?v=kcpu4z5eSEU)
|
||||||
|
|
||||||
|
[Installing Home Assistant OS using Proxmox 8](https://community.home-assistant.io/t/installing-home-assistant-os-using-proxmox-8/201835)
|
||||||
|
|
||||||
|
[How To Separate Zigbee2MQTT From Home Assistant In Proxmox](https://smarthomescene.com/guides/how-to-separate-zigbee2mqtt-from-home-assistant-in-proxmox/)
|
||||||
|
|
||||||
|
[How To Install Home Assistant On Proxmox: The Easy Way](https://smarthomescene.com/guides/how-to-install-home-assistant-on-proxmox-the-easy-way/)
|
||||||
|
|
||||||
|
[Home Assistant: Installing InfluxDB (LXC)](https://www.derekseaman.com/2023/04/home-assistant-installing-influxdb-lxc.html)
|
||||||
|
|
||||||
|
[Home Assistant: Proxmox Quick Start Guide](https://www.derekseaman.com/2023/10/home-assistant-proxmox-ve-8-0-quick-start-guide-2.html)
|
||||||
|
|
||||||
|
[Home Assistant: Installing Grafana (LXC) with Let’s Encrypt SSL](https://www.derekseaman.com/2023/04/home-assistant-installing-grafana-lxc.html)
|
||||||
|
|
||||||
|
[Proxmox: Plex LXC with Alder Lake Transcoding](https://www.derekseaman.com/2023/04/proxmox-plex-lxc-with-alder-lake-transcoding.html)
|
||||||
|
|
||||||
|
[How To Backup Home Assistant In Proxmox](https://smarthomescene.com/guides/how-to-backup-home-assistant-in-proxmox/)
|
||||||
|
|
||||||
|
[Running Frigate on Proxmox](https://www.homeautomationguy.io/blog/running-frigate-on-proxmox)
|
||||||
|
|
||||||
|
[Frigate VM on Proxmox with PCIe Coral TPU](https://www.derekseaman.com/2023/06/home-assistant-frigate-vm-on-proxmox-with-pcie-coral-tpu.html)
|
||||||
|
|
||||||
|
[Moving Home Assistant’s Database To MariaDB On Proxmox](https://smarthomescene.com/guides/moving-home-assistants-database-to-mariadb-on-proxmox/)
|
||||||
|
|
||||||
|
[How-to: Proxmox VE 7.4 to 8.0 Upgrade](https://www.derekseaman.com/2023/06/how-to-proxmox-7-4-to-8-0-upgrade.html)
|
||||||
|
|
||||||
|
[iGPU Transcoding In Proxmox with Jellyfin](https://www.youtube.com/watch?v=XAa_qpNmzZs)
|
||||||
|
|
||||||
|
[Proxmox + NetData](<https://dbt3ch.com/books/proxmox-netdata-for-better-insights-and-notifications/page/proxmox-netdata-for-better-insights-and-notifications>)
|
||||||
|
|
||||||
|
[Proxmox Homelab Series](<https://blog.kye.dev/proxmox-series>)
|
||||||
|
|
||||||
|
[The fastest installation of Docker and Portainer on Proxmox VE](https://lavr.site/en-fastest-install-docker-portainer-proxmox/)
|
||||||
|
|
||||||
|
[How To Setup Proxmox Backuper Server Using Helper Scripts](<https://youtu.be/6C2JOsrZZZw?si=kkrrcL_nLCDBJkOB>)
|
||||||
313
docs/contribution/setup-fork.sh
Normal file
313
docs/contribution/setup-fork.sh
Normal file
@ -0,0 +1,313 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# ProxmoxVED Fork Setup Script
|
||||||
|
#
|
||||||
|
# Automatically configures documentation and scripts for your fork
|
||||||
|
# Detects your GitHub username and repository from git config
|
||||||
|
# Updates all hardcoded links to point to your fork
|
||||||
|
#
|
||||||
|
# Usage:
|
||||||
|
# ./setup-fork.sh # Auto-detect from git config
|
||||||
|
# ./setup-fork.sh YOUR_USERNAME # Specify username
|
||||||
|
# ./setup-fork.sh YOUR_USERNAME REPO_NAME # Specify both
|
||||||
|
#
|
||||||
|
# Examples:
|
||||||
|
# ./setup-fork.sh john # Uses john/ProxmoxVED
|
||||||
|
# ./setup-fork.sh john my-fork # Uses john/my-fork
|
||||||
|
################################################################################
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
# Colors for output
|
||||||
|
RED='\033[0;31m'
|
||||||
|
GREEN='\033[0;32m'
|
||||||
|
YELLOW='\033[1;33m'
|
||||||
|
BLUE='\033[0;34m'
|
||||||
|
NC='\033[0m' # No Color
|
||||||
|
|
||||||
|
# Default values
|
||||||
|
REPO_NAME="ProxmoxVED"
|
||||||
|
USERNAME=""
|
||||||
|
AUTO_DETECT=true
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# FUNCTIONS
|
||||||
|
################################################################################
|
||||||
|
|
||||||
|
print_header() {
|
||||||
|
echo -e "\n${BLUE}╔════════════════════════════════════════════════════════════╗${NC}"
|
||||||
|
echo -e "${BLUE}║${NC} ProxmoxVED Fork Setup Script"
|
||||||
|
echo -e "${BLUE}║${NC} Configuring for your fork..."
|
||||||
|
echo -e "${BLUE}╚════════════════════════════════════════════════════════════╝${NC}\n"
|
||||||
|
}
|
||||||
|
|
||||||
|
print_info() {
|
||||||
|
echo -e "${BLUE}ℹ${NC} $1"
|
||||||
|
}
|
||||||
|
|
||||||
|
print_success() {
|
||||||
|
echo -e "${GREEN}✓${NC} $1"
|
||||||
|
}
|
||||||
|
|
||||||
|
print_warning() {
|
||||||
|
echo -e "${YELLOW}⚠${NC} $1"
|
||||||
|
}
|
||||||
|
|
||||||
|
print_error() {
|
||||||
|
echo -e "${RED}✗${NC} $1"
|
||||||
|
}
|
||||||
|
|
||||||
|
# Detect username from git remote
|
||||||
|
detect_username() {
|
||||||
|
local remote_url
|
||||||
|
|
||||||
|
# Try to get from origin
|
||||||
|
if ! remote_url=$(git config --get remote.origin.url 2>/dev/null); then
|
||||||
|
return 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Extract username from SSH or HTTPS URL
|
||||||
|
if [[ $remote_url =~ git@github.com:([^/]+) ]]; then
|
||||||
|
echo "${BASH_REMATCH[1]}"
|
||||||
|
elif [[ $remote_url =~ github.com/([^/]+) ]]; then
|
||||||
|
echo "${BASH_REMATCH[1]}"
|
||||||
|
else
|
||||||
|
return 1
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
# Detect repo name from git remote
|
||||||
|
detect_repo_name() {
|
||||||
|
local remote_url
|
||||||
|
|
||||||
|
if ! remote_url=$(git config --get remote.origin.url 2>/dev/null); then
|
||||||
|
return 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Extract repo name (remove .git if present)
|
||||||
|
if [[ $remote_url =~ /([^/]+?)(.git)?$ ]]; then
|
||||||
|
local repo="${BASH_REMATCH[1]}"
|
||||||
|
echo "${repo%.git}"
|
||||||
|
else
|
||||||
|
return 1
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
# Ask user for confirmation
|
||||||
|
confirm() {
|
||||||
|
local prompt="$1"
|
||||||
|
local response
|
||||||
|
|
||||||
|
read -p "$(echo -e ${YELLOW})$prompt (y/n)${NC} " -r response
|
||||||
|
[[ $response =~ ^[Yy]$ ]]
|
||||||
|
}
|
||||||
|
|
||||||
|
# Update links in files
|
||||||
|
update_links() {
|
||||||
|
local old_repo="community-scripts"
|
||||||
|
local old_name="ProxmoxVED"
|
||||||
|
local new_owner="$1"
|
||||||
|
local new_repo="$2"
|
||||||
|
local files_updated=0
|
||||||
|
|
||||||
|
print_info "Scanning for hardcoded links..."
|
||||||
|
|
||||||
|
# Find all markdown and shell files
|
||||||
|
local -a files_to_update=(
|
||||||
|
"docs/DEFAULTS_SYSTEM_GUIDE.md"
|
||||||
|
"docs/alpine-install.func.md"
|
||||||
|
"docs/install.func.md"
|
||||||
|
"docs/APP-install.md"
|
||||||
|
"docs/APP-ct.md"
|
||||||
|
"docs/CONTRIBUTION_GUIDE.md"
|
||||||
|
"docs/INDEX.md"
|
||||||
|
"docs/README.md"
|
||||||
|
"docs/EXIT_CODES.md"
|
||||||
|
"docs/api/README.md"
|
||||||
|
)
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
for file in "${files_to_update[@]}"; do
|
||||||
|
if [[ -f "$file" ]]; then
|
||||||
|
# Count occurrences
|
||||||
|
local count=$(grep -c "github.com/$old_repo/$old_name" "$file" 2>/dev/null || echo 0)
|
||||||
|
|
||||||
|
if [[ $count -gt 0 ]]; then
|
||||||
|
# Backup original
|
||||||
|
cp "$file" "$file.backup"
|
||||||
|
|
||||||
|
# Replace links
|
||||||
|
sed -i "s|github.com/$old_repo/$old_name|github.com/$new_owner/$new_repo|g" "$file"
|
||||||
|
|
||||||
|
((files_updated++))
|
||||||
|
print_success "Updated $file ($count links)"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
return $files_updated
|
||||||
|
}
|
||||||
|
|
||||||
|
# Create user git config setup info
|
||||||
|
create_git_setup_info() {
|
||||||
|
local username="$1"
|
||||||
|
|
||||||
|
cat >.git-setup-info <<'EOF'
|
||||||
|
# Git Configuration for ProxmoxVED Development
|
||||||
|
|
||||||
|
## Recommended Git Configuration
|
||||||
|
|
||||||
|
### Set up remotes for easy syncing with upstream:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# View your current remotes
|
||||||
|
git remote -v
|
||||||
|
|
||||||
|
# If you don't have 'upstream' configured, add it:
|
||||||
|
git remote add upstream https://github.com/community-scripts/ProxmoxVED.git
|
||||||
|
|
||||||
|
# Verify both remotes exist:
|
||||||
|
git remote -v
|
||||||
|
# Should show:
|
||||||
|
# origin https://github.com/YOUR_USERNAME/ProxmoxVED.git (fetch)
|
||||||
|
# origin https://github.com/YOUR_USERNAME/ProxmoxVED.git (push)
|
||||||
|
# upstream https://github.com/community-scripts/ProxmoxVED.git (fetch)
|
||||||
|
# upstream https://github.com/community-scripts/ProxmoxVED.git (push)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configure Git User (if not done globally)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git config user.name "Your Name"
|
||||||
|
git config user.email "your.email@example.com"
|
||||||
|
|
||||||
|
# Or configure globally:
|
||||||
|
git config --global user.name "Your Name"
|
||||||
|
git config --global user.email "your.email@example.com"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Useful Git Workflows
|
||||||
|
|
||||||
|
**Keep your fork up-to-date:**
|
||||||
|
```bash
|
||||||
|
git fetch upstream
|
||||||
|
git rebase upstream/main
|
||||||
|
git push origin main
|
||||||
|
```
|
||||||
|
|
||||||
|
**Create feature branch:**
|
||||||
|
```bash
|
||||||
|
git checkout -b feature/my-awesome-app
|
||||||
|
# Make changes...
|
||||||
|
git commit -m "feat: add my awesome app"
|
||||||
|
git push origin feature/my-awesome-app
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pull latest from upstream:**
|
||||||
|
```bash
|
||||||
|
git fetch upstream
|
||||||
|
git merge upstream/main
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
For more help, see: docs/CONTRIBUTION_GUIDE.md
|
||||||
|
EOF
|
||||||
|
|
||||||
|
print_success "Created .git-setup-info file"
|
||||||
|
}
|
||||||
|
|
||||||
|
################################################################################
|
||||||
|
# MAIN LOGIC
|
||||||
|
################################################################################
|
||||||
|
|
||||||
|
print_header
|
||||||
|
|
||||||
|
# Parse command line arguments
|
||||||
|
if [[ $# -gt 0 ]]; then
|
||||||
|
USERNAME="$1"
|
||||||
|
AUTO_DETECT=false
|
||||||
|
|
||||||
|
if [[ $# -gt 1 ]]; then
|
||||||
|
REPO_NAME="$2"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
# Try auto-detection
|
||||||
|
if username=$(detect_username); then
|
||||||
|
USERNAME="$username"
|
||||||
|
print_success "Detected GitHub username: $USERNAME"
|
||||||
|
else
|
||||||
|
print_error "Could not auto-detect GitHub username from git config"
|
||||||
|
echo -e "${YELLOW}Please run:${NC}"
|
||||||
|
echo " ./setup-fork.sh YOUR_USERNAME"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if repo_name=$(detect_repo_name); then
|
||||||
|
REPO_NAME="$repo_name"
|
||||||
|
if [[ "$REPO_NAME" != "ProxmoxVED" ]]; then
|
||||||
|
print_info "Detected custom repo name: $REPO_NAME"
|
||||||
|
else
|
||||||
|
print_success "Using default repo name: ProxmoxVED"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Validate inputs
|
||||||
|
if [[ -z "$USERNAME" ]]; then
|
||||||
|
print_error "Username cannot be empty"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [[ -z "$REPO_NAME" ]]; then
|
||||||
|
print_error "Repository name cannot be empty"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Show what we'll do
|
||||||
|
echo -e "${BLUE}Configuration Summary:${NC}"
|
||||||
|
echo " Repository URL: https://github.com/$USERNAME/$REPO_NAME"
|
||||||
|
echo " Files to update: 10 files with documentation"
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Ask for confirmation
|
||||||
|
if ! confirm "Apply these changes?"; then
|
||||||
|
print_warning "Setup cancelled"
|
||||||
|
exit 0
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Update all links
|
||||||
|
if update_links "$USERNAME" "$REPO_NAME"; then
|
||||||
|
links_changed=$?
|
||||||
|
print_success "Updated $links_changed files"
|
||||||
|
else
|
||||||
|
print_warning "No links needed updating or some files not found"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Create git setup info file
|
||||||
|
create_git_setup_info "$USERNAME"
|
||||||
|
|
||||||
|
# Final summary
|
||||||
|
echo ""
|
||||||
|
echo -e "${GREEN}╔════════════════════════════════════════════════════════════╗${NC}"
|
||||||
|
echo -e "${GREEN}║${NC} Fork Setup Complete! ${GREEN}║${NC}"
|
||||||
|
echo -e "${GREEN}╚════════════════════════════════════════════════════════════╝${NC}"
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
print_success "All documentation links updated to point to your fork"
|
||||||
|
print_info "Your fork: https://github.com/$USERNAME/$REPO_NAME"
|
||||||
|
print_info "Upstream: https://github.com/community-scripts/ProxmoxVED"
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
echo -e "${BLUE}Next Steps:${NC}"
|
||||||
|
echo " 1. Review the changes: git diff"
|
||||||
|
echo " 2. Check .git-setup-info for recommended git workflow"
|
||||||
|
echo " 3. Start developing: git checkout -b feature/my-app"
|
||||||
|
echo " 4. Read: docs/CONTRIBUTION_GUIDE.md"
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
print_success "Happy contributing! 🚀"
|
||||||
286
docs/contribution/templates_ct/AppName.md
Normal file
286
docs/contribution/templates_ct/AppName.md
Normal file
@ -0,0 +1,286 @@
|
|||||||
|
# **AppName<span></span>.sh Scripts**
|
||||||
|
|
||||||
|
`AppName.sh` scripts found in the `/ct` directory. These scripts are responsible for the installation of the desired application. For this guide we take `/ct/snipeit.sh` as example.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [**AppName.sh Scripts**](#appnamesh-scripts)
|
||||||
|
- [Table of Contents](#table-of-contents)
|
||||||
|
- [1. **File Header**](#1-file-header)
|
||||||
|
- [1.1 **Shebang**](#11-shebang)
|
||||||
|
- [1.2 **Import Functions**](#12-import-functions)
|
||||||
|
- [1.3 **Metadata**](#13-metadata)
|
||||||
|
- [2 **Variables and function import**](#2-variables-and-function-import)
|
||||||
|
- [2.1 **Default Values**](#21-default-values)
|
||||||
|
- [2.2 **📋 App output \& base settings**](#22--app-output--base-settings)
|
||||||
|
- [2.3 **🛠 Core functions**](#23--core-functions)
|
||||||
|
- [3 **Update function**](#3-update-function)
|
||||||
|
- [3.1 **Function Header**](#31-function-header)
|
||||||
|
- [3.2 **Check APP**](#32-check-app)
|
||||||
|
- [3.3 **Check version**](#33-check-version)
|
||||||
|
- [3.4 **Verbosity**](#34-verbosity)
|
||||||
|
- [3.5 **Backups**](#35-backups)
|
||||||
|
- [3.6 **Cleanup**](#36-cleanup)
|
||||||
|
- [3.7 **No update function**](#37-no-update-function)
|
||||||
|
- [4 **End of the script**](#4-end-of-the-script)
|
||||||
|
- [5. **Contribution checklist**](#5-contribution-checklist)
|
||||||
|
|
||||||
|
## 1. **File Header**
|
||||||
|
|
||||||
|
### 1.1 **Shebang**
|
||||||
|
|
||||||
|
- Use `#!/usr/bin/env bash` as the shebang.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/usr/bin/env bash
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.2 **Import Functions**
|
||||||
|
|
||||||
|
- Import the build.func file.
|
||||||
|
- When developing your own script, change the URL to your own repository.
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
> You also need to change all apperances of this URL in `misc/build.func` and `misc/install.func`
|
||||||
|
|
||||||
|
Example for development:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source <(curl -s https://raw.githubusercontent.com/[USER]/[REPO]/refs/heads/[BRANCH]/misc/build.func)
|
||||||
|
```
|
||||||
|
|
||||||
|
Final script:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source <(curl -s https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/misc/build.func)
|
||||||
|
```
|
||||||
|
|
||||||
|
> [!CAUTION]
|
||||||
|
> Before opening a Pull Request, change the URLs to point to the community-scripts repo.
|
||||||
|
|
||||||
|
### 1.3 **Metadata**
|
||||||
|
|
||||||
|
- Add clear comments for script metadata, including author, copyright, and license information.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Copyright (c) 2021-2025 community-scripts ORG
|
||||||
|
# Author: [YourUserName]
|
||||||
|
# License: MIT | https://github.com/community-scripts/ProxmoxVED/raw/main/LICENSE
|
||||||
|
# Source: [SOURCE_URL]
|
||||||
|
```
|
||||||
|
|
||||||
|
> [!NOTE]:
|
||||||
|
>
|
||||||
|
> - Add your username and source URL
|
||||||
|
> - For existing scripts, add "| Co-Author [YourUserName]" after the current author
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2 **Variables and function import**
|
||||||
|
>
|
||||||
|
> [!NOTE]
|
||||||
|
> You need to have all this set in your script, otherwise it will not work!
|
||||||
|
|
||||||
|
### 2.1 **Default Values**
|
||||||
|
|
||||||
|
- This section sets the default values for the container.
|
||||||
|
- `APP` needs to be set to the application name and must be equal to the filenames of your scripts.
|
||||||
|
- `var_tags`: You can set Tags for the CT wich show up in the Proxmox UI. Don´t overdo it!
|
||||||
|
|
||||||
|
>[!NOTE]
|
||||||
|
>Description for all Default Values
|
||||||
|
>
|
||||||
|
>| Variable | Description | Notes |
|
||||||
|
>|----------|-------------|-------|
|
||||||
|
>| `APP` | Application name | Must match ct\AppName.sh |
|
||||||
|
>| `var_tags` | Proxmox display tags without Spaces, only ; | Limit the number |
|
||||||
|
>| `var_cpu` | CPU cores | Number of cores |
|
||||||
|
>| `var_ram` | RAM | In MB |
|
||||||
|
>| `var_disk` | Disk capacity | In GB |
|
||||||
|
>| `var_os` | Operating system | alpine, debian, ubuntu |
|
||||||
|
>| `var_version` | OS version | e.g., 3.20, 11, 12, 20.04 |
|
||||||
|
>| `var_unprivileged` | Container type | 1 = Unprivileged, 0 = Privileged |
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
APP="SnipeIT"
|
||||||
|
var_tags="asset-management;foss"
|
||||||
|
var_cpu="2"
|
||||||
|
var_ram="2048"
|
||||||
|
var_disk="4"
|
||||||
|
var_os="debian"
|
||||||
|
var_version="12"
|
||||||
|
var_unprivileged="1"
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2.2 **📋 App output & base settings**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
header_info "$APP"
|
||||||
|
```
|
||||||
|
- `header_info`: Generates ASCII header for APP
|
||||||
|
|
||||||
|
## 2.3 **🛠 Core functions**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
variables
|
||||||
|
color
|
||||||
|
catch_errors
|
||||||
|
```
|
||||||
|
|
||||||
|
- `variables`: Processes input and prepares variables
|
||||||
|
- `color`: Sets icons, colors, and formatting
|
||||||
|
- `catch_errors`: Enables error handling
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3 **Update function**
|
||||||
|
|
||||||
|
### 3.1 **Function Header**
|
||||||
|
|
||||||
|
- If applicable write a function that updates the application and the OS in the container.
|
||||||
|
- Each update function starts with the same code:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
function update_script() {
|
||||||
|
header_info
|
||||||
|
check_container_storage
|
||||||
|
check_container_resources
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 **Check APP**
|
||||||
|
|
||||||
|
- Before doing anything update-wise, check if the app is installed in the container.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
if [[ ! -d /opt/snipe-it ]]; then
|
||||||
|
msg_error "No ${APP} Installation Found!"
|
||||||
|
exit
|
||||||
|
fi
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 **Check version**
|
||||||
|
|
||||||
|
- Before updating, check if a new version exists.
|
||||||
|
- We use the `${APPLICATION}_version.txt` file created in `/opt` during the install to compare new versions against the currently installed version.
|
||||||
|
|
||||||
|
Example with a Github Release:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
RELEASE=$(curl -fsSL https://api.github.com/repos/snipe/snipe-it/releases/latest | grep "tag_name" | awk '{print substr($2, 3, length($2)-4) }')
|
||||||
|
if [[ ! -f /opt/${APP}_version.txt ]] || [[ "${RELEASE}" != "$(cat /opt/${APP}_version.txt)" ]]; then
|
||||||
|
msg_info "Updating ${APP} to v${RELEASE}"
|
||||||
|
#DO UPDATE
|
||||||
|
else
|
||||||
|
msg_ok "No update required. ${APP} is already at v${RELEASE}."
|
||||||
|
fi
|
||||||
|
exit
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.4 **Verbosity**
|
||||||
|
|
||||||
|
- Use the appropriate flag (**-q** in the examples) for a command to suppress its output.
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsSL
|
||||||
|
unzip -q
|
||||||
|
```
|
||||||
|
|
||||||
|
- If a command does not come with this functionality use `$STD` to suppress it's output.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$STD php artisan migrate --force
|
||||||
|
$STD php artisan config:clear
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.5 **Backups**
|
||||||
|
|
||||||
|
- Backup user data if necessary.
|
||||||
|
- Move all user data back in the directory when the update is finished.
|
||||||
|
|
||||||
|
>[!NOTE]
|
||||||
|
>This is not meant to be a permanent backup
|
||||||
|
|
||||||
|
Example backup:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mv /opt/snipe-it /opt/snipe-it-backup
|
||||||
|
```
|
||||||
|
|
||||||
|
Example config restore:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp /opt/snipe-it-backup/.env /opt/snipe-it/.env
|
||||||
|
cp -r /opt/snipe-it-backup/public/uploads/ /opt/snipe-it/public/uploads/
|
||||||
|
cp -r /opt/snipe-it-backup/storage/private_uploads /opt/snipe-it/storage/private_uploads
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.6 **Cleanup**
|
||||||
|
|
||||||
|
- Do not forget to remove any temporary files/folders such as zip-files or temporary backups.
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rm -rf /opt/v${RELEASE}.zip
|
||||||
|
rm -rf /opt/snipe-it-backup
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.7 **No update function**
|
||||||
|
|
||||||
|
- In case you can not provide an update function use the following code to provide user feedback.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
function update_script() {
|
||||||
|
header_info
|
||||||
|
check_container_storage
|
||||||
|
check_container_resources
|
||||||
|
if [[ ! -d /opt/snipeit ]]; then
|
||||||
|
msg_error "No ${APP} Installation Found!"
|
||||||
|
exit
|
||||||
|
fi
|
||||||
|
msg_error "Currently we don't provide an update function for this ${APP}."
|
||||||
|
exit
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4 **End of the script**
|
||||||
|
|
||||||
|
- `start`: Launches Whiptail dialogue
|
||||||
|
- `build_container`: Collects and integrates user settings
|
||||||
|
- `description`: Sets LXC container description
|
||||||
|
- With `echo -e "${TAB}${GATEWAY}${BGN}http://${IP}${CL}"` you can point the user to the IP:PORT/folder needed to access the app.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
start
|
||||||
|
build_container
|
||||||
|
description
|
||||||
|
|
||||||
|
msg_ok "Completed Successfully!\n"
|
||||||
|
echo -e "${CREATING}${GN}${APP} setup has been successfully initialized!${CL}"
|
||||||
|
echo -e "${INFO}${YW} Access it using the following URL:${CL}"
|
||||||
|
echo -e "${TAB}${GATEWAY}${BGN}http://${IP}${CL}"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. **Contribution checklist**
|
||||||
|
|
||||||
|
- [ ] Shebang is correctly set (`#!/usr/bin/env bash`).
|
||||||
|
- [ ] Correct link to *build.func*
|
||||||
|
- [ ] Metadata (author, license) is included at the top.
|
||||||
|
- [ ] Variables follow naming conventions.
|
||||||
|
- [ ] Update function exists.
|
||||||
|
- [ ] Update functions checks if app is installed and for new version.
|
||||||
|
- [ ] Update function cleans up temporary files.
|
||||||
|
- [ ] Script ends with a helpful message for the user to reach the application.
|
||||||
86
docs/contribution/templates_ct/AppName.sh
Normal file
86
docs/contribution/templates_ct/AppName.sh
Normal file
@ -0,0 +1,86 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
source <(curl -s https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/misc/build.func)
|
||||||
|
# Copyright (c) 2021-2025 community-scripts ORG
|
||||||
|
# Author: [YourUserName]
|
||||||
|
# License: MIT | https://github.com/community-scripts/ProxmoxVED/raw/main/LICENSE
|
||||||
|
# Source: [SOURCE_URL]
|
||||||
|
|
||||||
|
# App Default Values
|
||||||
|
APP="[APP_NAME]"
|
||||||
|
# Name of the app (e.g. Google, Adventurelog, Apache-Guacamole"
|
||||||
|
var_tags="[TAGS]"
|
||||||
|
# Tags for Proxmox VE, maximum 2 pcs., no spaces allowed, separated by a semicolon ; (e.g. database | adblock;dhcp)
|
||||||
|
var_cpu="[CPU]"
|
||||||
|
# Number of cores (1-X) (e.g. 4) - default are 2
|
||||||
|
var_ram="[RAM]"
|
||||||
|
# Amount of used RAM in MB (e.g. 2048 or 4096)
|
||||||
|
var_disk="[DISK]"
|
||||||
|
# Amount of used disk space in GB (e.g. 4 or 10)
|
||||||
|
var_os="[OS]"
|
||||||
|
# Default OS (e.g. debian, ubuntu, alpine)
|
||||||
|
var_version="[VERSION]"
|
||||||
|
# Default OS version (e.g. 12 for debian, 24.04 for ubuntu, 3.20 for alpine)
|
||||||
|
var_unprivileged="[UNPRIVILEGED]"
|
||||||
|
# 1 = unprivileged container, 0 = privileged container
|
||||||
|
|
||||||
|
header_info "$APP"
|
||||||
|
variables
|
||||||
|
color
|
||||||
|
catch_errors
|
||||||
|
|
||||||
|
function update_script() {
|
||||||
|
header_info
|
||||||
|
check_container_storage
|
||||||
|
check_container_resources
|
||||||
|
|
||||||
|
# Check if installation is present | -f for file, -d for folder
|
||||||
|
if [[ ! -f [INSTALLATION_CHECK_PATH] ]]; then
|
||||||
|
msg_error "No ${APP} Installation Found!"
|
||||||
|
exit
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Crawling the new version and checking whether an update is required
|
||||||
|
RELEASE=$(curl -fsSL [RELEASE_URL] | [PARSE_RELEASE_COMMAND])
|
||||||
|
if [[ "${RELEASE}" != "$(cat /opt/${APP}_version.txt)" ]] || [[ ! -f /opt/${APP}_version.txt ]]; then
|
||||||
|
# Stopping Services
|
||||||
|
msg_info "Stopping $APP"
|
||||||
|
systemctl stop [SERVICE_NAME]
|
||||||
|
msg_ok "Stopped $APP"
|
||||||
|
|
||||||
|
# Creating Backup
|
||||||
|
msg_info "Creating Backup"
|
||||||
|
tar -czf "/opt/${APP}_backup_$(date +%F).tar.gz" [IMPORTANT_PATHS]
|
||||||
|
msg_ok "Backup Created"
|
||||||
|
|
||||||
|
# Execute Update
|
||||||
|
msg_info "Updating $APP to v${RELEASE}"
|
||||||
|
[UPDATE_COMMANDS]
|
||||||
|
msg_ok "Updated $APP to v${RELEASE}"
|
||||||
|
|
||||||
|
# Starting Services
|
||||||
|
msg_info "Starting $APP"
|
||||||
|
systemctl start [SERVICE_NAME]
|
||||||
|
msg_ok "Started $APP"
|
||||||
|
|
||||||
|
# Cleaning up
|
||||||
|
msg_info "Cleaning Up"
|
||||||
|
rm -rf [TEMP_FILES]
|
||||||
|
msg_ok "Cleanup Completed"
|
||||||
|
|
||||||
|
# Last Action
|
||||||
|
echo "${RELEASE}" >/opt/${APP}_version.txt
|
||||||
|
msg_ok "Update Successful"
|
||||||
|
else
|
||||||
|
msg_ok "No update required. ${APP} is already at v${RELEASE}"
|
||||||
|
fi
|
||||||
|
exit
|
||||||
|
}
|
||||||
|
|
||||||
|
start
|
||||||
|
build_container
|
||||||
|
description
|
||||||
|
|
||||||
|
msg_ok "Completed Successfully!\n"
|
||||||
|
echo -e "${CREATING}${GN}${APP} setup has been successfully initialized!${CL}"
|
||||||
|
echo -e "${INFO}${YW} Access it using the following URL:${CL}"
|
||||||
|
echo -e "${TAB}${GATEWAY}${BGN}http://${IP}:[PORT]${CL}"
|
||||||
353
docs/contribution/templates_install/AppName-install.md
Normal file
353
docs/contribution/templates_install/AppName-install.md
Normal file
@ -0,0 +1,353 @@
|
|||||||
|
|
||||||
|
# **AppName<span></span>-install.sh Scripts**
|
||||||
|
|
||||||
|
`AppName-install.sh` scripts found in the `/install` directory. These scripts are responsible for the installation of the application. For this guide we take `/install/snipeit-install.sh` as example.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [**AppName-install.sh Scripts**](#appname-installsh-scripts)
|
||||||
|
- [Table of Contents](#table-of-contents)
|
||||||
|
- [1. **File header**](#1-file-header)
|
||||||
|
- [1.1 **Shebang**](#11-shebang)
|
||||||
|
- [1.2 **Comments**](#12-comments)
|
||||||
|
- [1.3 **Variables and function import**](#13-variables-and-function-import)
|
||||||
|
- [2. **Variable naming and management**](#2-variable-naming-and-management)
|
||||||
|
- [2.1 **Naming conventions**](#21-naming-conventions)
|
||||||
|
- [3. **Dependencies**](#3-dependencies)
|
||||||
|
- [3.1 **Install all at once**](#31-install-all-at-once)
|
||||||
|
- [3.2 **Collapse dependencies**](#32-collapse-dependencies)
|
||||||
|
- [4. **Paths to application files**](#4-paths-to-application-files)
|
||||||
|
- [5. **Version management**](#5-version-management)
|
||||||
|
- [5.1 **Install the latest release**](#51-install-the-latest-release)
|
||||||
|
- [5.2 **Save the version for update checks**](#52-save-the-version-for-update-checks)
|
||||||
|
- [6. **Input and output management**](#6-input-and-output-management)
|
||||||
|
- [6.1 **User feedback**](#61-user-feedback)
|
||||||
|
- [6.2 **Verbosity**](#62-verbosity)
|
||||||
|
- [7. **String/File Manipulation**](#7-stringfile-manipulation)
|
||||||
|
- [7.1 **File Manipulation**](#71-file-manipulation)
|
||||||
|
- [8. **Security practices**](#8-security-practices)
|
||||||
|
- [8.1 **Password generation**](#81-password-generation)
|
||||||
|
- [8.2 **File permissions**](#82-file-permissions)
|
||||||
|
- [9. **Service Configuration**](#9-service-configuration)
|
||||||
|
- [9.1 **Configuration files**](#91-configuration-files)
|
||||||
|
- [9.2 **Credential management**](#92-credential-management)
|
||||||
|
- [9.3 **Enviroment files**](#93-enviroment-files)
|
||||||
|
- [9.4 **Services**](#94-services)
|
||||||
|
- [10. **Cleanup**](#10-cleanup)
|
||||||
|
- [10.1 **Remove temporary files**](#101-remove-temporary-files)
|
||||||
|
- [10.2 **Autoremove and autoclean**](#102-autoremove-and-autoclean)
|
||||||
|
- [11. **Best Practices Checklist**](#11-best-practices-checklist)
|
||||||
|
- [Example: High-Level Script Flow](#example-high-level-script-flow)
|
||||||
|
|
||||||
|
## 1. **File header**
|
||||||
|
|
||||||
|
### 1.1 **Shebang**
|
||||||
|
|
||||||
|
- Use `#!/usr/bin/env bash` as the shebang.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/usr/bin/env bash
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.2 **Comments**
|
||||||
|
|
||||||
|
- Add clear comments for script metadata, including author, copyright, and license information.
|
||||||
|
- Use meaningful inline comments to explain complex commands or logic.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Copyright (c) 2021-2025 community-scripts ORG
|
||||||
|
# Author: [YourUserName]
|
||||||
|
# License: MIT | https://github.com/community-scripts/ProxmoxVED/raw/main/LICENSE
|
||||||
|
# Source: [SOURCE_URL]
|
||||||
|
```
|
||||||
|
|
||||||
|
> [!NOTE]:
|
||||||
|
>
|
||||||
|
> - Add your username
|
||||||
|
> - When updating/reworking scripts, add "| Co-Author [YourUserName]"
|
||||||
|
|
||||||
|
### 1.3 **Variables and function import**
|
||||||
|
|
||||||
|
- This sections adds the support for all needed functions and variables.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||||
|
color
|
||||||
|
verb_ip6
|
||||||
|
catch_errors
|
||||||
|
setting_up_container
|
||||||
|
network_check
|
||||||
|
update_os
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. **Variable naming and management**
|
||||||
|
|
||||||
|
### 2.1 **Naming conventions**
|
||||||
|
|
||||||
|
- Use uppercase names for constants and environment variables.
|
||||||
|
- Use lowercase names for local script variables.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
DB_NAME=snipeit_db # Environment-like variable (constant)
|
||||||
|
db_user="snipeit" # Local variable
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. **Dependencies**
|
||||||
|
|
||||||
|
### 3.1 **Install all at once**
|
||||||
|
|
||||||
|
- Install all dependencies with a single command if possible
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$STD apt-get install -y \
|
||||||
|
curl \
|
||||||
|
composer \
|
||||||
|
git \
|
||||||
|
sudo \
|
||||||
|
mc \
|
||||||
|
nginx
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 **Collapse dependencies**
|
||||||
|
|
||||||
|
Collapse dependencies to keep the code readable.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
Use
|
||||||
|
|
||||||
|
```bash
|
||||||
|
php8.2-{bcmath,common,ctype}
|
||||||
|
```
|
||||||
|
|
||||||
|
instead of
|
||||||
|
|
||||||
|
```bash
|
||||||
|
php8.2-bcmath php8.2-common php8.2-ctype
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. **Paths to application files**
|
||||||
|
|
||||||
|
If possible install the app and all necessary files in `/opt/`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. **Version management**
|
||||||
|
|
||||||
|
### 5.1 **Install the latest release**
|
||||||
|
|
||||||
|
- Always try and install the latest release
|
||||||
|
- Do not hardcode any version if not absolutely necessary
|
||||||
|
|
||||||
|
Example for a git release:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
RELEASE=$(curl -fsSL https://api.github.com/repos/snipe/snipe-it/releases/latest | grep "tag_name" | awk '{print substr($2, 3, length($2)-4) }')
|
||||||
|
curl -fsSL "https://github.com/snipe/snipe-it/archive/refs/tags/v${RELEASE}.zip"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 **Save the version for update checks**
|
||||||
|
|
||||||
|
- Write the installed version into a file.
|
||||||
|
- This is used for the update function in **AppName.sh** to check for if a Update is needed.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
echo "${RELEASE}" >"/opt/AppName_version.txt"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. **Input and output management**
|
||||||
|
|
||||||
|
### 6.1 **User feedback**
|
||||||
|
|
||||||
|
- Use standard functions like `msg_info`, `msg_ok` or `msg_error` to print status messages.
|
||||||
|
- Each `msg_info` must be followed with a `msg_ok` before any other output is made.
|
||||||
|
- Display meaningful progress messages at key stages.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
msg_info "Installing Dependencies"
|
||||||
|
$STD apt-get install -y ...
|
||||||
|
msg_ok "Installed Dependencies"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.2 **Verbosity**
|
||||||
|
|
||||||
|
- Use the appropiate flag (**-q** in the examples) for a command to suppres its output
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsSL
|
||||||
|
unzip -q
|
||||||
|
```
|
||||||
|
|
||||||
|
- If a command dose not come with such a functionality use `$STD` (a custom standard redirection variable) for managing output verbosity.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
$STD apt-get install -y nginx
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. **String/File Manipulation**
|
||||||
|
|
||||||
|
### 7.1 **File Manipulation**
|
||||||
|
|
||||||
|
- Use `sed` to replace placeholder values in configuration files.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sed -i -e "s|^DB_DATABASE=.*|DB_DATABASE=$DB_NAME|" \
|
||||||
|
-e "s|^DB_USERNAME=.*|DB_USERNAME=$DB_USER|" \
|
||||||
|
-e "s|^DB_PASSWORD=.*|DB_PASSWORD=$DB_PASS|" .env
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. **Security practices**
|
||||||
|
|
||||||
|
### 8.1 **Password generation**
|
||||||
|
|
||||||
|
- Use `openssl` to generate random passwords.
|
||||||
|
- Use only alphanumeric values to not introduce unknown behaviour.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
DB_PASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.2 **File permissions**
|
||||||
|
|
||||||
|
Explicitly set secure ownership and permissions for sensitive files.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
chown -R www-data: /opt/snipe-it
|
||||||
|
chmod -R 755 /opt/snipe-it
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. **Service Configuration**
|
||||||
|
|
||||||
|
### 9.1 **Configuration files**
|
||||||
|
|
||||||
|
Use `cat <<EOF` to write configuration files in a clean and readable way.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat <<EOF >/etc/nginx/conf.d/snipeit.conf
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
root /opt/snipe-it/public;
|
||||||
|
index index.php;
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9.2 **Credential management**
|
||||||
|
|
||||||
|
Store the generated credentials in a file.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
USERNAME=username
|
||||||
|
PASSWORD=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13)
|
||||||
|
{
|
||||||
|
echo "Application-Credentials"
|
||||||
|
echo "Username: $USERNAME"
|
||||||
|
echo "Password: $PASSWORD"
|
||||||
|
} >> ~/application.creds
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9.3 **Enviroment files**
|
||||||
|
|
||||||
|
Use `cat <<EOF` to write enviromental files in a clean and readable way.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat <<EOF >/path/to/.env
|
||||||
|
VARIABLE="value"
|
||||||
|
PORT=3000
|
||||||
|
DB_NAME="${DB_NAME}"
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9.4 **Services**
|
||||||
|
|
||||||
|
Enable affected services after configuration changes and start them right away.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
systemctl enable -q --now nginx
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. **Cleanup**
|
||||||
|
|
||||||
|
### 10.1 **Remove temporary files**
|
||||||
|
|
||||||
|
Remove temporary files and downloads after use.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rm -rf /opt/v${RELEASE}.zip
|
||||||
|
```
|
||||||
|
|
||||||
|
### 10.2 **Autoremove and autoclean**
|
||||||
|
|
||||||
|
Remove unused dependencies to reduce disk space usage.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apt-get -y autoremove
|
||||||
|
apt-get -y autoclean
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. **Best Practices Checklist**
|
||||||
|
|
||||||
|
- [ ] Shebang is correctly set (`#!/usr/bin/env bash`).
|
||||||
|
- [ ] Metadata (author, license) is included at the top.
|
||||||
|
- [ ] Variables follow naming conventions.
|
||||||
|
- [ ] Sensitive values are dynamically generated.
|
||||||
|
- [ ] Files and services have proper permissions.
|
||||||
|
- [ ] Script cleans up temporary files.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Example: High-Level Script Flow
|
||||||
|
|
||||||
|
1. Dependencies installation
|
||||||
|
2. Database setup
|
||||||
|
3. Download and configure application
|
||||||
|
4. Service configuration
|
||||||
|
5. Final cleanup
|
||||||
83
docs/contribution/templates_install/AppName-install.sh
Normal file
83
docs/contribution/templates_install/AppName-install.sh
Normal file
@ -0,0 +1,83 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
|
||||||
|
# Copyright (c) 2021-2025 community-scripts ORG
|
||||||
|
# Author: [YourUserName]
|
||||||
|
# License: MIT | https://github.com/community-scripts/ProxmoxVED/raw/main/LICENSE
|
||||||
|
# Source: [SOURCE_URL]
|
||||||
|
|
||||||
|
# Import Functions und Setup
|
||||||
|
source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
|
||||||
|
color
|
||||||
|
verb_ip6
|
||||||
|
catch_errors
|
||||||
|
setting_up_container
|
||||||
|
network_check
|
||||||
|
update_os
|
||||||
|
|
||||||
|
# Installing Dependencies with the 3 core dependencies (curl;sudo;mc)
|
||||||
|
msg_info "Installing Dependencies"
|
||||||
|
$STD apt-get install -y \
|
||||||
|
curl \
|
||||||
|
sudo \
|
||||||
|
mc \
|
||||||
|
[PACKAGE_1] \
|
||||||
|
[PACKAGE_2] \
|
||||||
|
[PACKAGE_3]
|
||||||
|
msg_ok "Installed Dependencies"
|
||||||
|
|
||||||
|
# Template: MySQL Database
|
||||||
|
msg_info "Setting up Database"
|
||||||
|
DB_NAME=[DB_NAME]
|
||||||
|
DB_USER=[DB_USER]
|
||||||
|
DB_PASS=$(openssl rand -base64 18 | tr -dc 'a-zA-Z0-9' | head -c13)
|
||||||
|
$STD mysql -u root -e "CREATE DATABASE $DB_NAME;"
|
||||||
|
$STD mysql -u root -e "CREATE USER '$DB_USER'@'localhost' IDENTIFIED WITH mysql_native_password AS PASSWORD('$DB_PASS');"
|
||||||
|
$STD mysql -u root -e "GRANT ALL ON $DB_NAME.* TO '$DB_USER'@'localhost'; FLUSH PRIVILEGES;"
|
||||||
|
{
|
||||||
|
echo "${APPLICATION} Credentials"
|
||||||
|
echo "Database User: $DB_USER"
|
||||||
|
echo "Database Password: $DB_PASS"
|
||||||
|
echo "Database Name: $DB_NAME"
|
||||||
|
} >>~/$APP_NAME.creds
|
||||||
|
msg_ok "Set up Database"
|
||||||
|
|
||||||
|
# Temp
|
||||||
|
|
||||||
|
# Setup App
|
||||||
|
msg_info "Setup ${APPLICATION}"
|
||||||
|
RELEASE=$(curl -s https://api.github.com/repos/[REPO]/releases/latest | grep "tag_name" | awk '{print substr($2, 2, length($2)-3) }')
|
||||||
|
curl -fsSL "https://github.com/[REPO]/archive/refs/tags/${RELEASE}.zip"
|
||||||
|
unzip -q ${RELEASE}.zip
|
||||||
|
mv ${APPLICATION}-${RELEASE}/ /opt/${APPLICATION}
|
||||||
|
#
|
||||||
|
#
|
||||||
|
#
|
||||||
|
echo "${RELEASE}" >/opt/${APPLICATION}_version.txt
|
||||||
|
msg_ok "Setup ${APPLICATION}"
|
||||||
|
|
||||||
|
# Creating Service (if needed)
|
||||||
|
msg_info "Creating Service"
|
||||||
|
cat <<EOF >/etc/systemd/system/${APPLICATION}.service
|
||||||
|
[Unit]
|
||||||
|
Description=${APPLICATION} Service
|
||||||
|
After=network.target
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
ExecStart=[START_COMMAND]
|
||||||
|
Restart=always
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=multi-user.target
|
||||||
|
EOF
|
||||||
|
systemctl enable -q --now ${APPLICATION}.service
|
||||||
|
msg_ok "Created Service"
|
||||||
|
|
||||||
|
motd_ssh
|
||||||
|
customize
|
||||||
|
|
||||||
|
# Cleanup
|
||||||
|
msg_info "Cleaning up"
|
||||||
|
rm -f ${RELEASE}.zip
|
||||||
|
$STD apt-get -y autoremove
|
||||||
|
$STD apt-get -y autoclean
|
||||||
|
msg_ok "Cleaned"
|
||||||
@ -12,9 +12,9 @@ Each script has standardized documentation following the project pattern.
|
|||||||
|
|
||||||
## Key Resources
|
## Key Resources
|
||||||
|
|
||||||
- **[UPDATED_APP-ct.md](../UPDATED_APP-ct.md)** - Complete guide for creating ct scripts
|
- **[DETAILED_GUIDE.md](DETAILED_GUIDE.md)** - Complete reference for creating ct scripts
|
||||||
- **[CONTRIBUTION_GUIDE.md](../CONTRIBUTION_GUIDE.md)** - Contribution workflow
|
- **[../contribution/README.md](../contribution/README.md)** - How to contribute
|
||||||
- **[misc/build.func/](../misc/build.func/)** - Core orchestrator documentation
|
- **[../misc/build.func/](../misc/build.func/)** - Core orchestrator documentation
|
||||||
|
|
||||||
## Container Creation Flow
|
## Container Creation Flow
|
||||||
|
|
||||||
|
|||||||
@ -12,10 +12,10 @@ Each installation script category has documentation following the project patter
|
|||||||
|
|
||||||
## Key Resources
|
## Key Resources
|
||||||
|
|
||||||
- **[UPDATED_APP-install.md](../UPDATED_APP-install.md)** - Complete guide for creating install scripts
|
- **[DETAILED_GUIDE.md](DETAILED_GUIDE.md)** - Complete reference for creating install scripts
|
||||||
- **[CONTRIBUTION_GUIDE.md](../CONTRIBUTION_GUIDE.md)** - Contribution workflow
|
- **[../contribution/README.md](../contribution/README.md)** - How to contribute
|
||||||
- **[misc/install.func/](../misc/install.func/)** - Installation workflow documentation
|
- **[../misc/install.func/](../misc/install.func/)** - Installation workflow documentation
|
||||||
- **[misc/tools.func/](../misc/tools.func/)** - Package installation documentation
|
- **[../misc/tools.func/](../misc/tools.func/)** - Package installation documentation
|
||||||
|
|
||||||
## Installation Script Flow
|
## Installation Script Flow
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user