diff --git a/astro.config.mjs b/astro.config.mjs index 06d475f..0bc1739 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -37,6 +37,10 @@ export default defineConfig({ { label: 'Getting Started', items: [ + { + label: 'Overview', + link: '/getting-started/', + }, { label: 'System Requirements', link: '/getting-started/requirements', diff --git a/src/content/docs/getting-started/building.mdoc b/src/content/docs/getting-started/building.mdoc index 07da413..bd45798 100644 --- a/src/content/docs/getting-started/building.mdoc +++ b/src/content/docs/getting-started/building.mdoc @@ -9,7 +9,7 @@ Build FOSSBilling from source when you want to contribute code, test changes loc {% aside %} Make sure you have: -- PHP 8.2 or newer +- PHP 8.3 or newer - [Composer](https://getcomposer.org/) (latest version) - [Node.js](https://nodejs.org/) (LTS version) with npm {% /aside %} @@ -66,8 +66,4 @@ cd src php -S localhost:8000 ``` -Then visit `http://localhost:8000` in your browser. - -{% aside type="tip" %} -The built-in server is fine for development, but use a proper web server (Apache/NGINX) for production. -{% /aside %} +Then visit `http://localhost:8000` in your browser. \ No newline at end of file diff --git a/src/content/docs/getting-started/docker.mdoc b/src/content/docs/getting-started/docker.mdoc index babc548..677254a 100644 --- a/src/content/docs/getting-started/docker.mdoc +++ b/src/content/docs/getting-started/docker.mdoc @@ -3,10 +3,6 @@ title: Docker Installation description: Run FOSSBilling with Docker for a consistent, isolated environment. --- -{% aside type="tip" %} -Docker is useful when you want a predictable local or server setup without installing FOSSBilling's runtime dependencies directly on the host. -{% /aside %} - ## Prerequisites - [Docker Engine](https://docs.docker.com/engine/install/) installed on your system @@ -14,7 +10,7 @@ Docker is useful when you want a predictable local or server setup without insta ## Choose a Setup {% aside %} -Use the `latest` tag for the current stable release. For production deployments, pin a specific version such as `0.6.0` and upgrade intentionally after testing. +Use the `latest` tag for the current stable release. {% /aside %} {% tabs %} @@ -86,24 +82,8 @@ Open `http://localhost` or your server's IP/hostname to continue with the instal ## Post-Installation -{% aside type="danger" %} -**Cron is required.** FOSSBilling won't work properly without it. -{% /aside %} - After installation, set up the cron job on your host: ```bash (crontab -l; echo "*/5 * * * * docker exec su www-data -s /usr/local/bin/php /var/www/html/cron.php") | awk '!x[$0]++' | crontab - -``` - -Find your container name/ID: - -```bash -docker ps -``` - -## Next Steps - -1. Complete the web installer -2. Configure the cron job shown above -3. [Secure your installation](/security/) +``` \ No newline at end of file diff --git a/src/content/docs/getting-started/index.mdoc b/src/content/docs/getting-started/index.mdoc new file mode 100644 index 0000000..d694d4a --- /dev/null +++ b/src/content/docs/getting-started/index.mdoc @@ -0,0 +1,29 @@ +--- +title: Getting Started +description: Choose the right setup path for FOSSBilling and work through the essentials before going live. +--- + +Use this section if you are setting up FOSSBilling for the first time, evaluating installation methods, or preparing a development environment. + +{% cardgrid %} + {% linkcard + title="System Requirements" + href="/getting-started/requirements/" + description="Check supported web servers, PHP versions, extensions, and database requirements." + /%} + {% linkcard + title="Installing FOSSBilling" + href="/getting-started/installation/" + description="Set up FOSSBilling on a standard web server stack with the full installation guide." + /%} + {% linkcard + title="Docker Installation" + href="/getting-started/docker/" + description="Run FOSSBilling in containers for a predictable and isolated setup." + /%} + {% linkcard + title="Building FOSSBilling" + href="/getting-started/building/" + description="Build from source for development, contributing, or custom packaging." + /%} +{% /cardgrid %} diff --git a/src/content/docs/getting-started/installation.mdoc b/src/content/docs/getting-started/installation.mdoc index bcd59b8..c2b06b8 100644 --- a/src/content/docs/getting-started/installation.mdoc +++ b/src/content/docs/getting-started/installation.mdoc @@ -22,8 +22,8 @@ Apache usually requires no extra application-specific configuration. The templat {% /aside %} {% tabs %} - {% tabitem label="Apache / LiteSpeed / OpenLiteSpeed" %} - FOSSBilling includes a ready-to-use `.htaccess` file for Apache, LiteSpeed, and OpenLiteSpeed. Set up your domain as you normally would, then proceed with installation. + {% tabitem label="Apache & LiteSpeed / OpenLiteSpeed" %} + FOSSBilling includes a ready-to-use `.htaccess` file for Apache and LiteSpeed / OpenLiteSpeed. Set up your domain as you normally would, then proceed with installation. **OpenLiteSpeed users:** After installation, remember to reload the web server so it picks up the new `.htaccess` file. {% /tabitem %} @@ -115,9 +115,9 @@ server { ## Pre-installation Steps -1. **Download FOSSBilling**: Download the latest [stable release](https://fossbilling.org/downloads) from our downloads page. Preview builds are for testing, not production. +1. **Download FOSSBilling**: Download the latest [stable release](https://fossbilling.org/downloads) from our downloads page. 2. **Prepare your database**: Create a new MySQL database and a dedicated user for this installation. Keep the credentials handy for the installer. -3. **Set up SSL**: If you plan to use HTTPS, and you should, configure and verify your certificate *before* you start the installer. That avoids redirect and mixed-URL issues later. +3. **Set up SSL**: If you plan to use HTTPS, and you should, configure and verify your certificate *before* you start the installer. 4. **Configure reverse-proxy headers**: If you run behind a reverse proxy, forward the `X-Forwarded-Host` and `X-Forwarded-Proto` headers so FOSSBilling can generate the correct URLs and enforce HTTPS properly. ## Installation Steps @@ -157,29 +157,17 @@ If installation fails, you may need to manually empty the database before retryi ## Post-installation Steps -Once the installer finishes, configure the cron job before you begin using the system in earnest. +Once the installer finishes, configure the cron job before you begin using the system as soon as possible. ### Configuring the Cronjob FOSSBilling relies on cron to handle renewals, expired orders, email delivery, background checks, and other scheduled work. It needs to be configured correctly, run consistently, and execute often enough to keep the platform healthy. -We recommend running cron every five minutes. If more than 15 minutes pass without a run, FOSSBilling will show a warning in the admin panel. Treat that warning as urgent. +We recommend running cron every five minutes. If more than 15 minutes pass without a run, FOSSBilling will show a warning in the admin panel. Treat the warning as urgent. ![FOSSBilling warning about cron execution](/img/guides/install/cron-warning.png) -#### Option 1: Local Cron Job - -{% aside %} - The cronjob also needs to be run on a PHP version that FOSSBilling supports. If you are running into errors, you may be experiencing a common issue where your cronjob isn't being run on the same PHP version as your domain is configured for. For troubleshooting steps, please check [this forum post](https://forum.fossbilling.org/d/117-error-in-cron-after-update/3) for some pointers. -{% /aside %} +#### Local Cron Job FOSSBilling shows the correct cron command on the installation-complete screen and again in the admin panel. If you need to find it later, go to `Settings` -> `Scheduled Tasks` (`/admin/extension/settings/cron`). ![Cron settings - correct cron command](/img/guides/install/cron-settings-command.png) - -#### Option 2: Remote Cron Service - -If you cannot run cron locally, you can use a remote service to call a URL instead. First, go to `Settings` -> `Scheduled Tasks` (`/admin/extension/settings/cron`), enable the cron API endpoint, and click **Update**. - -After that, you can give the displayed URL to an external cron service so it can trigger scheduled tasks for you. - -![Cron settings - remote URL](/img/guides/install/cron-settings-remote.png) diff --git a/src/content/docs/getting-started/requirements.mdoc b/src/content/docs/getting-started/requirements.mdoc index eeee638..51c4555 100644 --- a/src/content/docs/getting-started/requirements.mdoc +++ b/src/content/docs/getting-started/requirements.mdoc @@ -7,54 +7,27 @@ description: What you need to run FOSSBilling — web servers, PHP extensions, a FOSSBilling works with any of these: -- **Apache** (with `mod_rewrite` enabled) -- **LiteSpeed Web Server** -- **NGINX** — [see our recommended config](/getting-started/installation#web-server-configuration) -- **OpenLiteSpeed** — note: may not be ideal if you're *selling* web hosting (FOSSBilling itself runs fine) - -**Our recommendation:** Apache or Apache behind an NGINX reverse proxy (handling static files). Most control panels are set up this way by default. +- **Apache** (with `mod_rewrite`) +- **LiteSpeed/OpenLiteSpeed Web Server** +- **NGINX** — [see recommended config](/getting-started/installation#web-server-configuration) If you're using something else, you'll need to configure URL rewriting manually. Use one of our existing configurations as a reference. ## PHP -### Supported Versions - -- **8.2, 8.3, or 8.4** - -### Required Extensions - -These must be installed: - -- `curl` -- `dom` -- `iconv` -- `intl` -- `json` -- `openssl` -- `pdo_mysql` -- `xml` -- `zlib` - -### Recommended Extensions - -Install these for better performance and features: - -| Extension | Why You Want It | -|-----------|-----------------| -| `mbstring` | Proper handling of multibyte characters | -| `opcache` | **Highly recommended** — significantly improves performance | -| `imagick` or `gd` | Image processing for logos and PDFs | -| `bz2` | Extract `.tar.bz2` archives (module/theme installs) | -| `simplexml` | Required for the Plesk integration only | - -### PHP Configuration - -Edit your `php.ini`: - -- **`memory_limit`**: At least `64M`. Increase if you run many modules or have high traffic. -- **`max_execution_time`**: Default `30` seconds is usually fine. Increase to `45`–`60` on shared hosting if needed. -- **`allow_url_fopen`**: Set to `On` if you need remote images in PDFs or emails. +- **Supported Versions**: 8.3, 8.4, or 8.5. +- **Required Extensions**: `curl`, `dom`, `iconv`, `intl`, `json`, `openssl`, `pdo_mysql`, `xml`, and `zlib`. +- **Recommended Extensions**: + | Extension | Why Recommended | + |-----------|-----------------| + | `mbstring` | Proper handling of multibyte characters | + | `opcache` | Significantly improves performance | + | `imagick` or `gd` | Image processing for logos and PDFs | + | `simplexml` | Required for Plesk integration only | +- **Configuration (`php.ini`)**: + - **`memory_limit`**: At least `64M`. Increase if you run many modules or have high traffic. + - **`max_execution_time`**: Default `30` seconds is usually fine. Increase to `45`–`60` on shared hosting if needed. + - **`allow_url_fopen`**: Set to `On` if you need remote images in PDFs or emails. ## Database @@ -65,13 +38,4 @@ Use `utf8mb4` with `utf8mb4_unicode_ci` collation. Your database user needs full FOSSBilling requires a MySQL-compatible database: - **MySQL** 8.0 or newer -- **MariaDB** 10.3 or newer - -## Quick Checklist - -Before installing, verify: - -- [ ] Web server running with rewrite support -- [ ] PHP 8.2–8.4 installed with required extensions -- [ ] MySQL 8.0+ or MariaDB 10.3+ available -- [ ] Database and user created with appropriate privileges +- **MariaDB** 10.3 or newer \ No newline at end of file diff --git a/src/content/docs/index.mdoc b/src/content/docs/index.mdoc index a4a838e..a656e14 100644 --- a/src/content/docs/index.mdoc +++ b/src/content/docs/index.mdoc @@ -3,7 +3,7 @@ title: Introduction description: Learn what FOSSBilling is, where to start, and how to get involved with the project. --- -FOSSBilling (FOSS: Free and Open Source Software) is a billing and client management solution for hosting providers and digital service businesses. +FOSSBilling (*FOSS*: Free and Open Source Software) is a billing and client management solution for hosting providers and digital service businesses. What sets FOSSBilling apart is its commitment to being fully open source. You can audit exactly what is running on your server, adapt it to your needs, and contribute back to the project. @@ -23,11 +23,4 @@ If you'd like to get involved, join the [Discord community](https://fossbilling. ## Need any help? -If you did not find what you were looking for in the [FAQ](/faq/), check the [Troubleshooting](/troubleshooting/) guide or ask the community in [Discord](https://fossbilling.org/discord). - -If you've just discovered FOSSBilling and want the fastest path forward, start with these pages: - -- [System Requirements](/getting-started/requirements/) -- [Standard Installation](/getting-started/installation/) -- [Install using Docker](/getting-started/docker/) -- [Updating FOSSBilling](/maintaining-fossbilling/updating/) +If you didn't find what you were looking for in the [FAQ](/faq/), check the [Troubleshooting](/troubleshooting/) guide or ask the community in [Discord](https://fossbilling.org/discord). \ No newline at end of file