Developer Workflow

pages/docs/contribution-handbook/_meta.json

@@ -1,5 +1,6 @@
 {
   "guides": "Guides",
   "file-structure": "FOSSBilling File Structure",
-  "code-of-conduct": "Code of Conduct"
+  "code-of-conduct": "Code of Conduct",
+  "developer-workflow": "Developer Workflow"
 }

pages/docs/contribution-handbook/developer-workflow.mdx

@@ -0,0 +1,55 @@
+---
+title: Developer Workflow
+description: How to set up your development environment and submit your first pull request.
+---
+
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
+import { Callout } from 'nextra-theme-docs'
+import { Card, Cards } from '../../../components/Card/'
+import { faDocker, faCpanel, faWindows } from '@fortawesome/free-brands-svg-icons'
+import { faServer, faBoxOpen, faBolt, faRobot, faHand, faCircleInfo } from '@fortawesome/free-solid-svg-icons'
+
+# Developer Workflow
+
+<Callout type="info" emoji={<FontAwesomeIcon icon={faCircleInfo} />}>
+  This section is a work in progress. Some sections may be incomplete or missing. Feedback is appreciated.
+</Callout>
+
+This guide will walk you through setting up your development environment and submitting your first pull request.
+
+## Prepare Code
+
+1. Create your own [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) from [FOSSBilling](https://github.com/FOSSBilling/FOSSBilling/fork).
+2. Clone your own fork instead of the FOSSBilling repo.
+3. [Setup your upstream](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) to help keep your fork in sync. Alternatively, use the web UI.
+
+## Environments
+
+There are multiple ways to set up your environment. Choose the one that works best for you.
+
+Proceed to the next section once your environment is configured.
+
+<Cards>
+  <Card icon={<FontAwesomeIcon icon={faServer} size="xl" />} title="Remote Installation" href="/docs/contribution-handbook/developer-workflow/remote"/>
+  <Card icon={<FontAwesomeIcon icon={faDocker} size="xl" />} title="Docker (Local)" href="/docs/contribution-handbook/developer-workflow/docker"/>
+</Cards>
+
+## Modifying Code
+
+1. Create a new branch under your fork. Name it something brief and relevant to what you are working on.
+2. Commit your changes into the new branch.
+3. If your commit is related to an existing issue, tag the issue ID in your commit message. For example: `#1234 add verify checkbox`. This will make your commit show within the issue history.
+4. Keep each set of changes isolated into their own branches. Avoid creating branches that have mixed changes across various modules. Each branch should solve a specific problem or task.
+5. Run PHPUnit tests to validate existing logic, and create new tests for any new logic.
+6. When your changes are finished, you are ready to submit a pull request.
+
+
+## Submitting a Pull Request
+
+1. Submit a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) from your forked branch targeting `main` on the FOSSBilling repo.
+2. Clearly document what your pull request is for and any new features it introduces or changes. Tag any open issues the pull request relates to. For example: `Closes #1234`.
+3. Submit your request.
+4. Verify that the automated tests complete successfully. The status will be shown in the pull request. The tests will take a moment to execute and finish.
+5. Monitor for and respond to any feedback on your request.
+6. If all tests pass and at least one maintainer leaves approval, your pull request will be accepted and your update will be merged into the main FOSSBilling branch.
+7. Sync your fork with the FOSSBilling upstream to now find your new code in your fork's `main` branch.

pages/docs/contribution-handbook/developer-workflow/_meta.json

@@ -0,0 +1,4 @@
+{
+  "remote": "Remote Installation",
+  "docker": "Docker"
+}

pages/docs/contribution-handbook/developer-workflow/docker.mdx

@@ -0,0 +1,146 @@
+---
+title: Docker
+description: Setting up your FOSSBilling development environment with Docker.
+---
+
+import { Callout } from 'nextra-theme-docs'
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
+import { faHand, faCircleInfo } from '@fortawesome/free-solid-svg-icons'
+
+# Docker
+
+<Callout type="error" emoji={<FontAwesomeIcon icon={faHand} />}>
+  This guide is for setting up a streamlined local development environment only. Some configurations are not ideal for production use. Do not expose this enviornment to the public unless you know what you are doing.
+
+  Some functionality may require remote external connections to be active, such as webhooks, payment notifications, or other cases where a third party needs to be able to reach FOSSBilling. This development environment will not allow you to develop or work with those features.
+
+  If you need to create a publicly accessible environment, refer to [Remote Installation](/docs/contribution-handbook/developer-workflow/remote) instead.
+</Callout>
+
+## Requirements
+
+You will need:
+
+1. Your own forked FOSSBilling repository already cloned on your development workstation.
+2. [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed.
+
+## Docker Configs
+
+Create new files in the root folder of your local FOSSBilling repository with the following names and contents:
+
+### docker-compose.yml
+
+```yaml
+version: "3.8"
+
+services:
+  web:
+    build:
+      dockerfile: Dockerfile
+      context: ./
+    image: php:8.1-apache
+    ports:
+      - 80:80
+    volumes:
+      - ./:/var/www/fossbilling
+  mysql:
+    image: mysql:8.0
+    environment:
+      MYSQL_ROOT_PASSWORD: fossbilling
+      MYSQL_DATABASE: fossbilling
+      MYSQL_USER: fossbilling
+      MYSQL_PASSWORD: fossbilling
+    volumes:
+      - mysql:/var/lib/mysql
+volumes:
+  mysql:
+```
+
+### Dockerfile
+
+```dockerfile
+FROM php:8.1-apache
+
+ENV APACHE_DOCUMENT_ROOT=/var/www/fossbilling/src
+RUN sed -ri -e 's!/var/www/html!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/sites-available/*.conf
+RUN sed -ri -e 's!/var/www/html!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/apache2.conf /etc/apache2/conf-available/*.conf
+
+RUN rm -f /var/lib/apt/lists/* ||true
+RUN apt update -y
+RUN apt install git unzip libzip-dev -y
+
+RUN a2enmod rewrite headers
+RUN docker-php-ext-install pdo pdo_mysql zip
+
+COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer
+COPY --from=node:20-slim /usr/local/bin /usr/local/bin
+COPY --from=node:20-slim /usr/local/lib/node_modules /usr/local/lib/node_modules
+
+ADD . /var/www/fossbilling
+```
+
+## Manage Containers
+
+Run the following command to build and start the containers:
+
+```
+docker-compose up --build -d
+```
+
+You can now interact with the containers via Docker Desktop.
+
+To destroy the containers via command line, run:
+
+```
+docker-compose down --volumes
+```
+
+
+## Installing FOSSBilling
+
+### Set Debug Mode
+
+Open `config-sample.php` and set `debug` to `true`.
+
+This will set debug mode by default, and prevent the `install` folder from being deleted during the installation process. This prevents the folder deletion from being shown in your git history and allows the installer files to still be referenced after installation.
+
+Once installation is completed, you can revert your change to `config-sample.php` to clear your local git changes.
+
+### Install Dependencies
+
+Use Docker Desktop to access the `Terminal` for the `web` container.
+
+Run the following commands:
+
+```
+cd /var/www/fossbilling
+composer install
+npm install
+npm run build
+```
+
+### Web Installer
+
+Visit http://localhost/install/install.php and follow the steps.
+
+Use `mysql` as the database hostname, and `fossbilling` for the database name, username, and password.
+
+<Callout type="info" emoji={<FontAwesomeIcon icon={faCircleInfo} />}>
+  It may take around 15 to 30 seconds for the MySQL container to fully initialize. The webserver will respond before MySQL is fully ready. Attempting to install FOSSBilling before MySQL finishes initializing will result in a database connection error. If you get this issue, wait a moment and try again, or check Docker logs to ensure MySQL finished initalizing.
+
+  Keep this in mind if you are rapidly re-creating the development environment or reinstalling FOSSBilling.
+</Callout>
+
+### Running Tests
+
+Use the following command in the `web` container to run `phpunit` tests:
+
+```
+php /var/www/fossbilling/src/vendor/phpunit/phpunit/phpunit
+```
+
+## Summary
+
+You have completed configuring a local development environment with Docker. Making changes to code on your local machine will be reflected within your development containers without needing to rebuild them.
+
+You may now refer back to [Developer Workflow](/docs/contribution-handbook/developer-workflow) for modifying and contributing code.

pages/docs/contribution-handbook/developer-workflow/remote.mdx

@@ -0,0 +1,80 @@
+---
+title: Remote Installation
+description: Setting up your FOSSBilling development environment as a remote installation.
+---
+
+import { Callout } from 'nextra-theme-docs'
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
+import { faCircleInfo } from '@fortawesome/free-solid-svg-icons'
+
+
+# Remote Installation
+
+## Requirements
+
+You will need:
+
+1. Your own forked FOSSBilling repository already cloned on your development workstation.
+2. A remote hosting service meeting the appropriate system requirements. Installation instructions and options are available [here](http://localhost:3000/docs/getting-started).
+
+<Callout type="info" emoji={<FontAwesomeIcon icon={faCircleInfo} />}>
+    For the purposes of developer workflow, ignore the sections regarding downloading and uploading FOSSBilling files. This workflow guide replaces that process.
+</Callout>
+
+## General Workflow
+
+1. Modify relevant files via your locally cloned repository.
+2. Use a File Sync method to sync your modified files into your remote installation.
+3. Visit your remote installation to test and debug.
+4. Refer back to [Developer Workflow](/docs/contribution-handbook/developer-workflow) for submitting commits and pull requests.
+
+## File Sync Methods
+
+You can use any of these methods to sync files into your remote installation. Use the method that works best for you.
+
+All methods involve copying the `src/` folder from your local repository into the public folder for your remote installation, refered to as `www`. All examples assume you are working from the project root directory.
+
+
+### Command Line: rsync
+
+Utilize [rsync](https://linux.die.net/man/1/rsync) via command line to sync only files that have changed.
+
+```
+rsync -ahP src/ user@domainorip:/path/to/www
+```
+
+Add the `-I` flag to force sync all files regardless of changes:
+
+```
+rsync -ahPI src/ user@domainorip:/path/to/www
+```
+
+To skip uploading the `src/install` folder, use the `--exclude` flag:
+
+```
+rsync -ahPI --exclude 'src/install' src/ user@domainorip:/path/to/www
+```
+
+Use [explain shell](https://explainshell.com/explain?cmd=rsync+-ahPI+--exclude+%27src%2Finstall%27+src%2F+user%40domainorip%3A%2Fpath%2Fto%2Fwww) for an interactive description.
+
+### FTP / SFTP GUI
+
+Use a FTP/SFTP client with a GUI such as [FileZilla](https://filezilla-project.org/download.php).
+
+Once connected, simply drag and drop your updates into your remote `www` folder.
+
+### Visual Studio Code
+
+Use the inline terminal to run your required sync commands or scripts. This allows you to edit and deploy all from one area.
+
+For a more interactive but still inline solution, consider an extension like [SFTP](https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp) to help automatically sync your code on each change.
+
+## Install Folder Handling
+
+Syncing in your local repository into an existing FOSSBilling installation will cause the `src/install/` folder to reappear. An error will be thrown in FOSSBilling requesting you to delete the `install` folder.
+
+You have a few options to work around this. Pick one of the following:
+
+1. Skip uploading the `src/install` folder when you upload your latest files.
+2. Manually delete your remote `www/install` folder each time after uploading.
+3. Set `'debug' => true,` in your `config.php`. This will bypass the restriction and allow you to access FOSSBilling without deleting the `www/install` folder. You will still be shown warnings inside the UI to delete the folder, but the UI will be functional.