docs(init): create documentation website using vitepress

- rename podlibre to adaures - rename castopod-host to castopod - simplify README and redirect to docs site - move INSTALL and UPDATE docs - add new gitlabci pipeline to deploy docs - upgrade node to v16 in Dockerfile
2026-04-11 18:56:42 +02:00 · 2022-02-19 16:06:11 +00:00 · 2022-02-19 16:06:11 +00:00 · fa5b5f51a4
commit fa5b5f51a4
parent 472842fae6
327 changed files with 5619 additions and 1445 deletions
--- a/docs/src/getting-started/_category_.json
+++ b/docs/src/getting-started/_category_.json
@ -0,0 +1,4 @@
+{
+  "label": "Getting Started",
+  "position": 2
+}
--- a/docs/src/getting-started/install.md
+++ b/docs/src/getting-started/install.md
@ -0,0 +1,154 @@
+---
+title: Installation
+sidebarDepth: 3
+---
+
+# How to install Castopod?
+
+Castopod was thought-out to be easy to install. Whether using dedicated or
+shared hosting, you can install it on most PHP-MySQL compatible web servers.
+
+## Requirements
+
+- PHP v8.0 or higher
+- MySQL version 5.7 or higher or MariaDB version 10.2 or higher
+- HTTPS support
+
+### PHP v8.0 or higher
+
+PHP version 8.0 or higher is required, with the following extensions installed:
+
+- [intl](https://php.net/manual/en/intl.requirements.php)
+- [libcurl](https://php.net/manual/en/curl.requirements.php)
+- [mbstring](https://php.net/manual/en/mbstring.installation.php)
+- [gd](https://www.php.net/manual/en/image.installation.php) with **JPEG**,
+  **PNG** and **WEBP** libraries.
+
+Additionally, make sure that the following extensions are enabled in your PHP:
+
+- json (enabled by default - don't turn it off)
+- xml (enabled by default - don't turn it off)
+- [mysqlnd](https://php.net/manual/en/mysqlnd.install.php)
+
+### MySQL compatible database
+
+> We recommend using [MariaDB](https://mariadb.org).
+
+::: warning
+
+Castopod only works with supported MySQL 5.7 or higher compatible databases. It
+will break with the previous MySQL v5.6 for example as its end of life was on
+February 5, 2021.
+
+:::
+
+You will need the server hostname, database name, username and password to
+complete the installation process. If you do not have these, please contact your
+server administrator.
+
+#### Privileges
+
+User must have at least these privileges on the database for Castopod to work:
+`CREATE`, `ALTER`, `DELETE`, `EXECUTE`, `INDEX`, `INSERT`, `SELECT`, `UPDATE`.
+
+### (Optional) FFmpeg v4.1.8 or higher for Video Clips
+
+[FFmpeg](https://www.ffmpeg.org/) version 4.1.8 or higher is required if you
+want to generate Video Clips. The following extensions must be installed:
+
+- **FreeType 2** library for
+  [gd](https://www.php.net/manual/en/image.installation.php).
+
+### (Optional) Other recommendations
+
+- Redis for better cache performances.
+- CDN for static files caching and better performances.
+- e-mail gateway for lost passwords.
+
+## Install instructions
+
+### Pre-requisites
+
+0. Get a Web Server with [requirements](#requirements) installed
+1. Create a MySQL database for Castopod with a user having access and
+   modification privileges (for more info, see
+   [MySQL compatible database](#mysql-compatible-database)).
+2. Activate HTTPS on your domain with an _SSL certificate_.
+3. Download and unzip the latest [Castopod Package](https://castopod.org/) onto
+   the web server if you haven’t already.
+   - ⚠️ Set the web server document root to the `public/` sub-folder within the
+     `castopod` folder.
+4. Add **cron tasks** on your web server for various background processes
+   (replace the paths accordingly):
+
+   - For social features to work properly, this task is used to broadcast social
+     activities to your followers on the fediverse:
+
+   ```bash
+      * * * * * /path/to/php /path/to/castopod/public/index.php scheduled-activities
+   ```
+
+   - For Video Clips to be created (see
+     [FFmpeg requirements](#ffmpeg-v418-or-higher-for-video-clips)):
+
+   ```bash
+      * * * * * /path/to/php /path/to/castopod/public/index.php scheduled-video-clips
+   ```
+
+   > These tasks run **every minute**. You may set the frequency depending on
+   > your needs: every 5, 10 minutes or more.
+
+### (recommended) Install Wizard
+
+1. Run the Castopod install script by going to the install wizard page
+   (`https://your_domain_name.com/cp-install`) in your favorite web browser.
+2. Follow the instructions on your screen.
+3. Start podcasting!
+
+::: info Note
+
+The install script writes a `.env` file in the package root. If you cannot go
+through the install wizard, you can
+[create and update the `.env` file manually](#alternative-manual-configuration).
+
+:::
+
+## Community packages
+
+If you don't want to bother with installing Castopod manually, you may use one
+of the packages created and maintained by the open-source community.
+
+### Install with YunoHost
+
+[YunoHost](https://yunohost.org/) is a distribution based on Debian GNU/Linux
+made up of free and open-source software packages. It manages the hardships of
+self-hosting for you.
+
+<div class="flex flex-wrap items-center gap-4">
+
+<a href="https://install-app.yunohost.org/?app=castopod" target="_blank" rel="noopener noreferrer">
+   <img src="https://install-app.yunohost.org/install-with-yunohost.svg" alt="Install Castopod with YunoHost" class="align-middle" />
+</a>
+
+<a href="https://github.com/YunoHost-Apps/castopod_ynh" target="_blank" rel="noopener noreferrer" class="inline-flex items-center px-4 py-[.3rem] mx-auto font-semibold text-center text-black rounded-md gap-x-1 border-2 border-solid border-[#333] hover:no-underline hover:bg-gray-100"><svg
+   xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="1em" height="1em"
+   class="text-xl"><path fill="none" d="M0 0h24v24H0z"/><path d="M12 2A10 10 0 0 0 2 12a10 10 0 0 0 6.84 9.49c.5.09.69-.21.69-.48l-.02-1.86c-2.51.46-3.16-.61-3.36-1.18-.11-.28-.6-1.17-1.02-1.4-.35-.2-.85-.66-.02-.67.79-.01 1.35.72 1.54 1.02.9 1.52 2.34 1.1 2.91.83a2.1 2.1 0 0 1 .64-1.34c-2.22-.25-4.55-1.11-4.55-4.94A3.9 3.9 0 0 1 6.68 8.8a3.6 3.6 0 0 1 .1-2.65s.83-.27 2.75 1.02a9.28 9.28 0 0 1 2.5-.34c.85 0 1.7.12 2.5.34 1.9-1.3 2.75-1.02 2.75-1.02.54 1.37.2 2.4.1 2.65.63.7 1.02 1.58 1.02 2.68 0 3.84-2.34 4.7-4.56 4.94.36.31.67.91.67 1.85l-.01 2.75c0 .26.19.58.69.48A10.02 10.02 0 0 0 22 12 10 10 0 0 0 12 2z"/></svg>Github
+Repo</a>
+
+</div>
+
+### Install with Docker
+
+I you wish to use Docker to install Castopod, it is possible thanks to
+[Romain de Laage](https://podcastindex.social/web/@rdelaage@mamot.fr)!
+
+<a href="https://gitlab.utc.fr/picasoft/projets/services/castopod" target="_blank" rel="noopener noreferrer" class="inline-flex items-center px-4 py-2 mx-auto font-semibold text-center text-white rounded-md shadow gap-x-1 bg-[#1282d7] hover:no-underline hover:bg-[#0f6eb5]">Install
+with
+Docker<svg viewBox="0 0 24 24" width="1em" height="1em" class="text-xl text-pine-200"><path fill="currentColor" d="m16.172 11-5.364-5.364 1.414-1.414L20 12l-7.778 7.778-1.414-1.414L16.172 13H4v-2z"></path></svg></a>
+
+::: info Note
+
+Given high demand for docker, we are planning on maintaining an official Docker
+image directly into the Castopod repository.
+
+:::
--- a/docs/src/getting-started/security.md
+++ b/docs/src/getting-started/security.md
@ -0,0 +1,26 @@
+---
+title: Security
+---
+
+# Security concerns
+
+Castopod is built on top of [CodeIgniter4](https://codeigniter.com/), a PHP
+framework that encourages
+[good security practices](https://codeigniter.com/user_guide/concepts/security.html).
+
+To maximize your instance's safety and prevent any malicious attack, we
+recommend you update all your Castopod files permissions after installation or
+updates (to avoid any prior permission error):
+
+- `writable/` folder must be **readable** and **writable**.
+- `public/media/` folder must be **readable** and **writable**.
+- any other file must be set to **readonly**.
+
+For instance, if you are using Apache or NGINX with Ubuntu you may do the
+following:
+
+```bash
+sudo chown -R root:root /path/to/castopod
+sudo chown -R www-data:www-data /path/to/castopod/writable
+sudo chown -R www-data:www-data /path/to/castopod/public/media
+```
--- a/docs/src/getting-started/update.md
+++ b/docs/src/getting-started/update.md
@ -0,0 +1,93 @@
+---
+title: Update
+sidebarDepth: 3
+---
+
+# How to update Castopod?
+
+After installing Castopod, you may want to update your instance to the latest
+version in order to enjoy the latest features ✨, bug fixes 🐛 and performance
+improvements ⚡.
+
+## Automatic update instructions
+
+> Coming soon... 👀
+
+## Manual update instructions
+
+1. Go to the
+   [releases page](https://code.castopod.org/ad-aures/castopod/-/releases) and
+   see if your instance is up to date with the latest Castopod version
+
+   - cf.
+     [Where can I find my Castopod version?](#where-can-i-find-my-castopod-version)
+
+2. Download the latest release package named `Castopod Package`, you may choose
+   between the `zip` or `tar.gz` archives
+
+   - ⚠️ Make sure you download the Castopod Package and **NOT** the Source Code
+
+3. On your server:
+
+   - Remove all files except `.env` and `public/media`
+   - Copy the new files from the downloaded package into your server
+
+     ::: info Note
+
+     You may need to reset files permissions as during the install process.
+     Check [Security Concerns](./security.md).
+
+     :::
+
+4. Releases may come with additional update instructions (see
+   [releases page](https://code.castopod.org/ad-aures/castopod/-/releases)).
+   They are usually database migration scripts in `.sql` format to update your
+   database schema.
+
+   - 👉 Make sure you run the scripts on your phpmyadmin panel or using command
+     line to update the database along with the package files!
+   - cf.
+     [I haven't updated my instance in a long time… What should I do?](#i-havent-updated-my-instance-in-a-long-time-what-should-i-do)
+
+5. If you are using redis, clear your cache.
+6. ✨ Enjoy your fresh instance, you're all done!
+
+## Frequently asked questions (FAQ)
+
+### Where can I find my Castopod version?
+
+Go to your Castopod admin panel, the version is displayed on the bottom left
+corner.
+
+Alternatively, you can find the version in the `app > Config > Constants.php`
+file.
+
+### I haven't updated my instance in a long time… What should I do?
+
+No problem! Just get the latest release as described above. Only, when going
+through the release instructions (4), perform them sequentially, from the oldest
+to the newest.
+
+> You may want to backup your instance depending on how long you haven't updated
+> Castopod.
+
+For example, if you're on `v1.0.0-alpha.42` and would like to upgrade to
+`v1.0.0-beta.1`:
+
+0. (highly recommended) Make a backup of your files and database.
+
+1. Download the latest release, overwrite your files whilst keeping `.env` and
+   `public/media`.
+
+2. Go through each release update instructions sequentially (from oldest to
+   newest) starting with `v1.0.0-alpha.43`, `v1.0.0-alpha.44`,
+   `v1.0.0-alpha.45`, …, `v1.0.0-beta.1`.
+
+3. ✨ Enjoy your fresh instance, you're all done!
+
+### Should I make a backup before updating?
+
+We advise you do, so you don't lose everything if anything goes wrong!
+
+More generally, we advise you make regular backups of your Castopod files and
+database to prevent you from losing it all…