diff --git a/content/doc/applications/php.md b/content/doc/applications/php.md deleted file mode 100644 index 8c85aa3fa..000000000 --- a/content/doc/applications/php.md +++ /dev/null @@ -1,627 +0,0 @@ ---- -type: docs -linkTitle: PHP with Apache -title: PHP with Apache -description: Deploy PHP applications on Clever Cloud with support for multiple frameworks, Composer dependencies, and database integration -keywords: -- php hosting -- apache -- composer -- laravel -- symfony -- wordpress -aliases: -- /applications/php -- /deploy/application/php/php-apps -- /doc/deploy/application/php -- /doc/deploy/application/php/php-apps -- /doc/doc/php -- /doc/php -- /doc/php/php-apps -- /doc/doc/php/php-apps -- /doc/getting-started/by-language/php -- /doc/partials/language-specific-deploy/php -- /getting-started/by-language/php -- /php -- /php/php-apps ---- - -## Overview - -PHP is a widely-used general-purpose scripting language that is especially suited for Web development and can be embedded -into HTML. - -The HTTP server is [Apache 2](https://httpd.apache.org/), and the PHP code is executed by [PHP-FPM](https://php-fpm.org/). - -{{% content "create-application" %}} - -{{% content "set-env-vars" %}} - -## Configure your PHP application - -### Choose your PHP version - -Set the `CC_PHP_VERSION` environment variable to one of the following versions. - -{{< runtimes_versions php >}} - -All new PHP applications are created with a default `CC_PHP_VERSION`. You can of course change it whenever you want then redeploy your application to use the version you want. We only support values based on the first two digits (`X` or `X.Y`, not `X.Y.Z`). - -### Change the webroot - -Since one of the best practices of PHP development is to take the libraries and core files outside the webroot, you may -want to set another webroot than the default one (*the root of your application*). - -#### Using an environment variable - -Add a new environment variable called `CC_WEBROOT` and set `/public` as its value. - -```shell -clever env set CC_WEBROOT /public -``` - -### Change PHP settings - -#### PHP settings - -Most PHP settings can be changed using a `.user.ini` file. - -If you want the settings to be applied to the whole application, you should put this file in your `webroot`. If you did not change it (see above), then your `webroot` is the root of the repository. - -If you put the `.user.ini` file in a subdirectory; settings will be applied recursively starting from this subdirectory. - -#### Same configuration between PHP-CLI and PHP-FPM. - -`.user.ini` files aren't loaded by the PHP CLI by default. - -However, some PHP applications may want to check for the PHP-FPM configuration pre-requisites, `post_max_size` or `upload_max_filesize` values for example. - -To load the PHP-FPM `.user.ini` file during a PHP-CLI process, in a [hook](/doc/develop/build-hooks/), use the `PHP_INI_SCAN_DIR` environment variable to load the additional file. - -Assuming the script runs at the root-folder of the application: - -```bash -#!/usr/bin/env bash - -export PHP_INI_SCAN_DIR=":." -php myscript.php -``` - -This appends the current directory while still loading the default configuration. - -**Note**: The `:` at the beginning of the string is mandatory. It indicates defaults files must still load. - -A specific `.ini` file can be loaded with: - -``` -#!/usr/bin/env bash - -export PHP_INI_SCAN_DIR=":.php-configuration/" -php myscript.php -``` - -This loads every `.ini` files in the `php-configuration/` directory. - -##### Timezone configuration - -All instances on Clever Cloud run on the UTC timezone. We recommend to handle all your dates in UTC internally, and only handle timezones when reading or displaying dates. - -Additionally, you can set PHP's time zone setting with `.user.ini`. For instance, to use the french time zone, edit `.user.ini` to add this line: - -```ini -date.timezone=Europe/Paris -``` - -##### Header injection - -###### With .htaccess - -To inject headers on HTTP responses, add this configuration to `.htaccess` file: - -```sh -Header Set Access-Control-Allow-Origin "https://www.example.com" -Header Set Access-Control-Allow-Headers "Authorization" -``` - -{{< callout type="info" >}} -You can use a `.htaccess` file to create or update headers, but you can't delete them. -{{< /callout >}} - -###### With PHP - -You can also do it from PHP: - -```php -header("Access-Control-Allow-Origin: https://www.example.com"); -header("Access-Control-Allow-Headers: Authorization"); -``` - -If you want to keep this separate from your application, you can configure the application to execute some code on every request. - -In `.user.ini`, add the following line (you need to create `inject_headers.php` first): - -```ini -auto_prepend_file=./inject_headers.php -``` - -Please refer to the [official documentation](https://www.php.net/manual/en/configuration.file.per-user.php) for more information. - -You can review the [available directives](https://www.php.net/manual/en/ini.list.php); all the `PHP_INI_USER`, `PHP_INI_PERDIR`, and `PHP_INI_ALL` directives can be set from within `.user.ini`. - -##### Memory Limit - -When php-fpm spawns a worker it allocates a smaller part of the application's memory to the worker, here is the allocated memory for each flavor: - - | Flavor | Memory Limit | - |----------|--------------| - |Pico | 64M | - |Nano | 64M | - |XS | 128M | - |S | 256M | - |M | 384M | - |L | 512M | - |XL | 768M | - |2XL | 1024M | - |3XL | 1536M | - |4XL+ | 2048M | - -To change this limit you can define `MEMORY_LIMIT` [environment variable](/doc/reference/reference-environment-variables#php). - -If you define a limit exceeding the application memory it will use the default one. - -## Configure Apache - -We use Apache 2 as HTTP Server. In order to configure it, you can create a `.htaccess` file and set directives inside this file. - -### htaccess - -The `.htaccess` file can be created everywhere in you app, depending of the part of the application covered by directives. - -However, directives who applies to the entire application must be declared in a `.htaccess` file to the application root. - -### htpasswd - -You can configure basic authentication using [environment variables](/doc/reference/reference-environment-variables#php). You will need to set `CC_HTTP_BASIC_AUTH` variable to your own `login:password` pair. If you need to allow access to multiple users, you can create additional environment `CC_HTTP_BASIC_AUTH_n` (where `n` is a number) variables. - -### Define a custom HTTP timeout - -You can define the timeout of an HTTP request in Apache using the `HTTP_TIMEOUT` [environment variable](/doc/develop/env-variables). - -**By default, the HTTP timeout is set to 3 minutes (180 seconds)**. - -### Header size - -Default Apache header size is `8k`. If you need to increase it, you can set `CC_APACHE_HEADERS_SIZE` environment variable, between `8` and `256`. Effective value depends on deployment region. [Ask for a dedicated load balancer](https://console.clever-cloud.com/ticket-center-choice) for a specific value. - -### Force HTTPS traffic - -Load balancers handle HTTPS traffic ahead of your application. You can use the `X-Forwarded-Proto` header to know the original protocol (`http` or `https`). - -Place the following snippet in a `.htaccess` file to ensure that your visitors only access your application through HTTPS. - -```conf -RewriteEngine On -RewriteCond %{HTTPS} off -RewriteCond %{HTTP:X-Forwarded-Proto} !https -RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301] -``` - -### Prevent Apache to redirect HTTPS calls to HTTP when adding a trailing slash - -`DirectorySlash` is enabled by default on the PHP scalers, therefore Apache will add a trailing slash to a resource when it detects that it is a directory. - -E.g. if foobar is a directory, Apache will automatically redirect `http://example.com/foobar` to `http://example.com/foobar/`. - -Unfortunately the module is unable to detect if the request comes from a secure connection or not. As a result it will force an HTTPS call to be redirected to HTTP. - -In order to prevent this behavior, you can add the following statements in a `.htaccess` file: - -```conf -DirectorySlash Off -RewriteEngine On -RewriteCond %{REQUEST_FILENAME} -d -RewriteRule ^(.+[^/])$ %{HTTP:X-Forwarded-Proto}://%{HTTP_HOST}/$1/ [R=301,L,QSA] -``` - -These statements will keep the former protocol of the request when issuing the redirect. Assuming that the header `X-Forwarded-Proto` is always filled (which is the case on our platform). - -If you want to force all redirects to HTTPS, you can replace `%{HTTP:X-Forwarded-Proto}` with `https`. - -### Change the FastCGI module - -You can choose between two FastCGI modules, `fastcgi` and `proxy_fcgi`, using the `CC_CGI_IMPLEMENTATION` environment variable. If you don't set it `proxy_fcgi` is used as default value. We recommend it, as `fastcgi` implementation is not maintained anymore. - -If you have issues with downloading content, it could be related to the `fastcgi` module not working correctly in combination with the `deflate` module, as the `Content-Length` header is not updated to the new size of the encoded content. To resolve this issue, use `proxy_fcgi`. - -### Environment injection - -As mentioned above, Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -To access the variables, use the `getenv` function. So, for example, if -your application has a postgresql add-on linked: - -```php -$host = getenv("POSTGRESQL_ADDON_HOST"); -$database = getenv("POSTGRESQL_ADDON_DB"); -$username = getenv("POSTGRESQL_ADDON_USER"); -$password = getenv("POSTGRESQL_ADDON_PASSWORD"); - -$pg = new PDO("postgresql:host={$host};dbname={$database}, $username, $password); -``` - -{{< callout type="warning" >}} -Environment variables are displayed in the default output of `phpinfo()`. If you want to use `phpinfo()` without exposing environment variables, you have to call it this way: `phpinfo(INFO_GENERAL | INFO_CREDITS | INFO_CONFIGURATION | INFO_MODULES | INFO_LICENSE)` -{{< /callout >}} - -## Composer - -We support Composer build out of the box. You just need to provide a `composer.json` file in the root of your repository and we will run `composer.phar install --no-ansi --no-progress --no-interaction --no-dev` for you. - -You can also set the `CC_COMPOSER_VERSION` to `1` or `2` to select the composer version to use. - -{{< callout type="info" >}} -If you encounter any issues, add your own `composer.phar` file in the root of your repository which will override the version we use. -{{< /callout >}} - -You can perform your own `composer.phar install` by using the [Post Build hook](/doc/develop/build-hooks#post-build-cc_post_build_hook). - -Example of a `composer.json` file: - -```json{linenos=table} -{ - "require": { - "laravel/framework": "4.1.*", - "ruflin/Elastica": "dev-master", - "shift31/laravel-elasticsearch": "dev-master", - "natxet/CssMin": "dev-master" - }, - "repositories": [ - { - "type": "vcs", - "url": "https://github.com/timothylhuillier/laravel-elasticsearch.git" - } - ], - "autoload": { - "classmap": [ - "app/controllers", - "app/models", - "app/database/migrations", - "app/database/seeds" - ], - "psr-0": { - "SomeApp": "app" - } - }, - "config": { - "preferred-install": "dist" - }, - "minimum-stability": "dev" -} -``` - -Example of a minimalist PHP application using composer and custom scripts: [php-composer-demo](https://github.com/CleverCloud/php-composer-demo) - -## Development Dependencies - -Development dependencies will not be automatically installed during the deployment. You can control their installation by using the `CC_PHP_DEV_DEPENDENCIES` environment variable which takes `install` value. - -Any other value than `install` will prevent development dependencies from being installed. - -### GitHub rate limit - -Sometimes, you can encounter the following error when downloading dependencies: - -```txt -Failed to download symfony/symfony from dist: Could not authenticate against GitHub.com -``` - -To prevent this download dependencies's fails that is often caused by rate limit of GitHub API while deploying your apps, -we recommend you to add `oauth` token in your composer configuration file or in separate file named as described in -[composer FAQ (API rate limit and OAuth tokens)](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens). - -You can find more documentation about composer configuration at [getcomposer.com](https://getcomposer.org/doc/04-schema.md). - -#### Example - -You use Artisan to manage your project and you want to execute *artisan migrate* before running your app. - -To do this, we use a post build hook, you have to set a new environment variable on your Clever application as following: - -```bash -CC_POST_BUILD_HOOK=php artisan migrate --force -``` - -**Note:** You must add the *execute* permission to your file (`chmod u+x yourfile`) before pushing it. - -## Frameworks and CMS - -The following is the list of tested CMS by our team. - -It's quite not exhaustive, so it does not mean that other CMS can't work on the Clever Cloud platform. - -{{< cards >}} - {{< card link="/developers/guides/tutorial-drupal" title="Drupal" subtitle= "Deploy a Drupal-based website on Clever Cloud" icon="drupal" >}} - {{< card link="/developers/guides/tutorial-laravel" title="Laravel" subtitle= "Deploy a Laravel app on Clever Cloud" icon="laravel" >}} - {{< card link="/developers/guides/tutorial-symfony" title="Symfony" subtitle= "Deploy a Symfony application on Clever Cloud" icon="symfony" >}} - {{< card link="/developers/guides/tutorial-wordpress" title="WordPress" subtitle= "Deploy WordPress on Clever Cloud" icon="wordpress" >}} - {{< card link="/developers/guides/moodle" title="Moodle" subtitle="Full Moodle installation and configuration guide" icon="moodle" >}} - -{{< /cards >}} - -Others PHP frameworks tested on Clever Cloud: - -- Prestashop -- Dokuwiki -- Joomla -- SugarCRM -- Drupal -- Magento -- Status.net -- Symfony -- Thelia -- Laravel -- Sylius - -## Available extensions and modules - -Clever Cloud PHP with Apache applications enable the following extensions by default: - -`amqp`, `bcmath`, `bz2`, `calendar`, `ctype`, `curl`, `dba`, `exif`, `fileinfo`, `filter`, `ftp`, `gd`, `gettext`, `gmp`, `iconv`, `imagick`, `imap`, `intl`, `json`, `ldap`, `libsodium`, `mbstring`, `mcrypt`, `memcached`, `memcache`, `mongodb`, `mysql`, `mysqli`, `opcache`, `pcntl`, `pcre`, `pdo-mysql`, `pdo-odbc`, `pdo-pgsql`, `pdo-sqlite`, `pgsql`, `phar`, `posix`, `pspell`, `readline`, `redis`, `session`, `shmop`, `sockets`, `sodium`, `solr`, `ssh2`, `ssl`, `tidy`, `tokenizer`, `unixodbc`, `xml`, `xmlrpc`, `xsl`, `zip`, `zlib`. - -You can also enable the following extensions on demand: - -`apcu`, `blackfire`, `elastic_apm_agent`, `event`, `excimer`, `geos`, `gnupg`, `grpc`, `ioncube`, `imap`, `mailparse`, `maxminddb`, `mongo`, `newrelic`, `oauth`, `opentelemetry`, `pcs`, `PDFlib`, `pdo_sqlsrv`, `protobuf`, `pspell`, `rdkafka`, `scoutapm`, `sqlsrv`, `sqreen`, `tideways`, `uopz`, `uploadprogress`, `xdebug`, `xmlrpc`, `yaml` - ->[!NOTE] ->Only some extensions support PHP 8.5 for now: `amqp`, `apcu`, `blackfire`, `event`, `excimer`, `gnupg`, `grpc`, `imagick`, `imap`, `mailparse`, `maxminddb`, `memcached`, `oauth`, `opentelemetry`, `pdo_sqlsrv`, `protobuf`, `pspell`, `rdkafka`, `redis`, `sqlsrv`, `ssh2`, `tideways`, `uploadprogress`, `yaml`, `zip`. We'll add support for more extensions as they are released. - -You can check extensions and versions by viewing our `phpinfo()` for: - -- [PHP 5.6](https://php56info.cleverapps.io) -- [PHP 7.1](https://php71info.cleverapps.io) -- [PHP 7.2](https://php72info.cleverapps.io) -- [PHP 7.3](https://php73info.cleverapps.io) -- [PHP 7.4](https://php74info.cleverapps.io) -- [PHP 8.0](https://php80info.cleverapps.io) -- [PHP 8.1](https://php81info.cleverapps.io) -- [PHP 8.2](https://php82info.cleverapps.io) -- [PHP 8.3](https://php83info.cleverapps.io) -- [PHP 8.4](https://php84info.cleverapps.io) -- [PHP 8.5](https://php85info.cleverapps.io) - -If you have a request about extensions, contact [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice). - -### Enable specific extensions - -Some extensions need to be enabled explicitly. To do so, set the corresponding [environment variable](#setting-up-environment-variables-on-clever-cloud): - -- APCu: set `ENABLE_APCU` to `true`. - - APCu is an in-memory key-value store for PHP. Keys are of type string and values can be any PHP variables. - -- Elastic APM Agent: set `ENABLE_ELASTIC_APM_AGENT` to `true` (default if `ELASTIC_APM_SERVER_URL` is defined). - - Elastic APM agent is Elastic's APM agent extension for PHP. The PHP agent enables you to trace the execution of operations - in your application, sending performance metrics and errors to the Elastic APM server. - **Warning**: This extension is available starting PHP 7.2. - -- Event: set `ENABLE_EVENT` to `true`. - - Event is an extension to schedule I/O, time and signal based events. - -- Excimer: set `ENABLE_EXCIMER` to `true`. - - Excimer is an extension that provides a low-overhead interrupting timer and sampling profiler. - -- GEOS: set `ENABLE_GEOS` to `true`. - - GEOS (Geometry Engine - Open Source) is a C++ port of the Java Topology Suite (JTS). - -- GnuPG: set `ENABLE_GNUPG` to `true`. - - GnuPG is an extension that provides methods to interact with GNU Privacy Guard (OpenPGP implementation). - -- gRPC: set `ENABLE_GRPC` to `true`. - - gRPC is an extension for the high performance, open source, general RPC framework layered over HTTP/2. - -- IonCube: set `ENABLE_IONCUBE` to `true`. - - IonCube is a tool to obfuscate PHP code. It's often used by paying Prestashop and WordPress plugins. - -- IMAP (only for PHP 8.4+): set `ENABLE_IMAP` to `true`. - - IMAP is an extension to operate with the IMAP protocol, as well as the NNTP, POP3, and local mailbox access methods. - -- Mailparse: set `ENABLE_MAILPARSE` to `true`. - - Mailparse is an extension for parsing and working with email messages. It can deal with RFC 822 and RFC 2045 (MIME) compliant messages. - -- MaxMind DB: set `ENABLE_MAXMINDDB` to `true`. - - Extension for reading MaxMind DB files. MaxMind DB is a binary file format that stores data indexed by IP address subnets (IPv4 or IPv6). - -- Mongo: set `ENABLE_MONGO` to `true`. - - MongoDB is a NoSQL Database. This extension allows to use it from PHP. - **Warning**: this extension is now superseded by the `mongodb` extension. We provide it for backward compatibility. - -- NewRelic: set `ENABLE_NEWRELIC` to `true`. - - Newrelic Agent for PHP. Newrelic is a software analytics tool. - -- OAuth: set `ENABLE_OAUTH` to `true`. - - OAuth consumer extension. OAuth is an authorization protocol built on top of HTTP. - -- OpenTelemetry: set `ENABLE_OPENTELEMETRY` to `true`. - - OpenTelemetry is an extension to facilitate the generation, export, collection of telemetry data such as traces, metrics, and logs. - -- PCS: set `ENABLE_PCS` to `true`. - - PCS provides a fast and easy way to mix C and PHP code in your PHP extension. - -- PDFlib: set `ENABLE_PDFlib` to `true`. - - PDFlib is a commercial library for generating PDF files. It provides a PHP extension to create and manipulate PDF documents. - -- Protobuf: set `ENABLE_PROTOBUF` to `true`. - - Protobuf is an extension for the language-neutral, platform-neutral extensible mechanism for serializing structured data. - -- Pspell: set `ENABLE_PSPELL` to `true`. - - Pspell is an extension to check the spelling of words and offer suggestions. - -- Rdkafka: set `ENABLE_RDKAFKA` to `true`. - - PHP-rdkafka is a thin librdkafka binding providing a working PHP 5 / PHP 7 Kafka client. - -- Scout APM: set `ENABLE_SCOUTAPM` to `true`. - - The Scout APM extension to provide additional capabilities to application monitoring over just using the base PHP userland library. - -- SQL Server: set `ENABLE_SQLSRV` or `ENABLE_PDO_SQLSRV` to `true`. - - These extensions enable drivers that rely on the Microsoft ODBC Driver to handle the low-level communication with SQL Server. The `SQLSRV` extension provides a procedural interface while the `PDO_SQLSRV` extension implements PDO for accessing data in all editions of SQL Server 2012 and later (including Azure SQL DB). - -- Sqreen: The Sqreen agent is started automatically after adding the environment variables (`SQREEN_API_APP_NAME` and `SQREEN_API_TOKEN`). - -- Tideways: set `ENABLE_TIDEWAYS` to `true`. - - Tideways is an extension that provides profiling and monitoring capabilities for PHP applications. - -- Uopz: set `ENABLE_UOPZ` to `true`. - - The uopz extension is focused on providing utilities to aid with unit testing PHP code. - -- Uploadprogress: set `ENABLE_UPLOADPROGRESS` to `true`. - - The uploadprogress extension is used to track the progress of a file download. - -- XDebug: set `ENABLE_XDEBUG` to `true`. - - XDebug is a debugger and profiler tool for PHP. - -- XML RPC: set `ENABLE_XMLRPC` to `true`. - - XML-RPC is an extension for server and client bindings - -- YAML: set `ENABLE_YAML` to `true`. - - YAML is an extension providing a YAML-1.1 parser and emitter - -You can use `DISABLE_=true` in your [environment variables](/doc/reference/reference-environment-variables/) to disable an extension. - -## Configure the session storage - -By default, an [FS Bucket](/doc/addons/fs-bucket/) is created for each PHP applications, so that session data is available on each instance. This FS Bucket is also used to store TMP files by default. You can change this behavior by setting the `TMPDIR` environment variable. You can set it to `/tmp` for example. - -> [!NOTE] FS Buckets are not available in HDS regions -> To deploy a PHP application on an HDS region, set [`CC_PHP_DISABLE_APP_BUCKET=true`](/doc/applications/php/#speed-up-or-disable-the-session-fs-bucket). Consider using Redis to manage PHP sessions. - -### Speed up or disable the session FS Bucket - -You can set the following environment variables: - -- `CC_PHP_ASYNC_APP_BUCKET=async` to mount the session FS Bucket with the `async` option. - It speeds up the FS Bucket usage, but it can corrupt files in case of a network outage. -- `CC_PHP_DISABLE_APP_BUCKET=(true|yes|disable)` to entirely prevent the session FS Bucket - from being mounted. - Use this if you don't use the default PHP session library. - It will speed up your application but users might lose their session across instances - and deployments. - -### Use Materia KV or Redis to store PHP Sessions - -Clever Cloud allows to store PHP sessions easily in a [Materia KV](/doc/addons/materia-kv) or [Redis](/doc/addons/redis) add-on to improve performance/reliability. - -To enable this feature, you need to: - -- Set `ENABLE_REDIS=true` as [environment variable](/doc/develop/env-variables) in the PHP application -- Set `SESSION_TYPE=redis` as [environment variable](/doc/develop/env-variables) in the PHP application -- Create and link a Materia KV or Redis add-on to the PHP application - -## Sending emails - -The PHP language has the `mail` function to directly send emails. While we do not provide a SMTP server (needed to send the emails), you can configure one through environment variables. - -We provide Mailpace add-on to send emails through PHP `mail()` function. You have to turn TLS on with port 465 (environment variable `CC_MTA_SERVER_USE_TLS=true`) to make Mailpace working. - -We also recommend you to use [Mailgun](https://www.mailgun.com/) or [Mailjet](https://www.mailjet.com/) if your project supports it. These services already have everything you need to send emails from your code. - -### Configure the SMTP server - -Services like [Mailgun](https://www.mailgun.com/) or [Mailjet](https://www.mailjet.com/) provide SMTP servers. If your application has no other way but to use the `mail` function of PHP to send emails, you have to configure a SMTP server. This can be done through environment variables: - -- `CC_MTA_SERVER_HOST`: Host of the SMTP server. -- `CC_MTA_SERVER_PORT`: Port of the SMTP server. Defaults to `465` whether TLS is enabled or not. -- `CC_MTA_AUTH_USER`: User to authenticate to the SMTP server. -- `CC_MTA_AUTH_PASSWORD`: Password to authenticate to the SMTP server. -- `CC_MTA_SERVER_USE_TLS`: Enable or disable TLS. Defaults to `true`. -- `CC_MTA_SERVER_STARTTLS`: Enable or disable STARTTLS. Defaults to `false`. -- `CC_MTA_SERVER_AUTH_METHOD`: Enable or disable authentication. Defaults to `on`. - -## Configure Monolog - -A lot of frameworks (including Symfony) use Monolog to handle logging. The default configuration of Monolog doesn't allow to log errors into the console. - -Here is a basic configuration of Monolog to send your application's logs into our logging system and access them into the Console: - -```yaml -monolog: - handlers: - clever_logs: - type: error_log - level: warning -``` - -You can change the level to whatever level you desire. For Symfony, the configuration file is `app/config/config_prod.yml`. - -Laravel doesn't need Monolog to retrieve logs via Clever console or Clever CLI. Here, ensure that you have the following line in `config/app.php`: - -```php -return [ - // … - 'log' => env('APP_LOG'), - // … -]; -``` - -Then, set `APP_LOG=syslog` as Clever application environment variable. - -## Using HTTP authentication - -Using basic HTTP authentication, PHP usually handles the values of user and password in variables named `$_SERVER['PHP_AUTH_USER']` and `$_SERVER['PHP_AUTH_PW']`. - -At Clever Cloud, we have enabled an Apache option to pass directly the Authorization header, even though we are using FastCGI; still, the header is not used by PHP, and the aforementioned variables are empty. - -You can do this to fill them using the Authorization header: - -```php -list($_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW']) = explode(':' , base64_decode(substr($_SERVER['Authorization'], 6))); -``` - -{{% content "new-relic" %}} - -{{% content "blackfire" %}} - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via **Git or FTP**. - -{{% content "deploy-git" %}} - -{{% content "deploy-ftp" %}} - -## ProxySQL - -{{% content "proxysql" %}} - -You can learn more about ProxySQL on the [dedicated documentation page](/guides/proxysql) - -{{% content "more-config" %}} - -{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/php/_index.md b/content/doc/applications/php/_index.md new file mode 100644 index 000000000..c7dacd53f --- /dev/null +++ b/content/doc/applications/php/_index.md @@ -0,0 +1,218 @@ +--- +type: docs +linkTitle: PHP with Apache +title: PHP with Apache application runtime +description: Deploy PHP applications on Clever Cloud with Apache, PHP-FPM, Composer dependencies, and framework support +keywords: +- php hosting +- apache +- composer +- laravel +- symfony +- wordpress +aliases: +- /applications/php +- /deploy/application/php/php-apps +- /doc/deploy/application/php +- /doc/deploy/application/php/php-apps +- /doc/doc/php +- /doc/php +- /doc/php/php-apps +- /doc/doc/php/php-apps +- /doc/getting-started/by-language/php +- /doc/partials/language-specific-deploy/php +- /getting-started/by-language/php +- /php +- /php/php-apps +--- + +## Overview + +PHP is a widely-used general-purpose scripting language that is especially suited for Web development and can be embedded +into HTML. + +The HTTP server is [Apache 2](https://httpd.apache.org/), and the PHP code is executed by [PHP-FPM](https://php-fpm.org/). + +## Create your PHP application + +To create a new PHP application, use the [Clever Cloud Console](https://console.clever-cloud.com) or [Clever Tools](https://github.com/CleverCloud/clever-tools): + +```bash +clever create --type php +``` +- [Learn more about Clever Tools](/doc/cli/) +- [Learn more about Clever Cloud application deployment](/doc/quickstart/#create-an-application-step-by-step) + +## Configure your PHP application + +### Mandatory needs + +PHP runtime requires a working web application. The HTTP server is Apache 2 with PHP-FPM. If you need to serve files from a specific directory, set the `CC_WEBROOT` environment variable (e.g. `/public`). + +```shell +clever env set CC_WEBROOT /public +``` + +- [Learn more about environment variables on Clever Cloud](/doc/reference/reference-environment-variables/) + +### Build phase + +Composer build is supported out of the box. If a `composer.json` file is present at the root of your repository, dependencies are installed automatically during the build phase. + +- [Learn more about Composer on Clever Cloud](/doc/applications/php/composer/) +- [Learn more about Deployment hooks](/doc/develop/build-hooks/) + +### PHP version + +Set the `CC_PHP_VERSION` environment variable to one of the following versions. + +{{< runtimes_versions php >}} + +All new PHP applications are created with a default `CC_PHP_VERSION`. You can change it whenever you want then redeploy your application to use the version you want. Only values based on the first two digits (`X` or `X.Y`, not `X.Y.Z`) are supported. + +### Custom PHP configuration + +Most PHP settings can be changed using a `.user.ini` file. + +If you want the settings to be applied to the whole application, you should put this file in your `webroot`. If you did not change it, then your `webroot` is the root of the repository. + +If you put the `.user.ini` file in a subdirectory, settings will be applied recursively starting from this subdirectory. + +You can review the [available directives](https://www.php.net/manual/en/ini.list.php); all the `PHP_INI_USER`, `PHP_INI_PERDIR`, and `PHP_INI_ALL` directives can be set from within `.user.ini`. + +- [Learn more about .user.ini](https://www.php.net/manual/en/configuration.file.per-user.php) + +#### Same configuration between PHP-CLI and PHP-FPM + +`.user.ini` files are not loaded by the PHP CLI by default. + +However, some PHP applications may want to check for the PHP-FPM configuration pre-requisites, `post_max_size` or `upload_max_filesize` values for example. + +To load the PHP-FPM `.user.ini` file during a PHP-CLI process, in a [hook](/doc/develop/build-hooks/), use the `PHP_INI_SCAN_DIR` environment variable to load the additional file. + +Assuming the script runs at the root-folder of the application: + +```bash +#!/usr/bin/env bash + +export PHP_INI_SCAN_DIR=":." +php myscript.php +``` + +This appends the current directory while still loading the default configuration. + +> [!NOTE] +> The `:` at the beginning of the string is mandatory. It indicates defaults files must still load. + +A specific `.ini` file can be loaded with: + +```bash +#!/usr/bin/env bash + +export PHP_INI_SCAN_DIR=":.php-configuration/" +php myscript.php +``` + +This loads every `.ini` files in the `php-configuration/` directory. + +#### Timezone configuration + +All instances on Clever Cloud run on the UTC timezone. We recommend to handle all your dates in UTC internally, and only handle timezones when reading or displaying dates. + +Additionally, you can set PHP's time zone setting with `.user.ini`. For instance, to use the french time zone, edit `.user.ini` to add this line: + +```ini +date.timezone=Europe/Paris +``` + +#### Memory Limit + +When php-fpm spawns a worker it allocates a smaller part of the application's memory to the worker, here is the allocated memory for each flavor: + + | Flavor | Memory Limit | + |----------|--------------| + |Pico | 64M | + |Nano | 64M | + |XS | 128M | + |S | 256M | + |M | 384M | + |L | 512M | + |XL | 768M | + |2XL | 1024M | + |3XL | 1536M | + |4XL+ | 2048M | + +To change this limit you can define `MEMORY_LIMIT` [environment variable](/doc/reference/reference-environment-variables#php). + +If you define a limit exceeding the application memory it will use the default one. + +## Frameworks and CMS + +The following is the list of tested CMS by our team. + +It's quite not exhaustive, so it does not mean that other CMS can't work on the Clever Cloud platform. + +{{< cards >}} + {{< card link="/developers/guides/tutorial-drupal" title="Drupal" subtitle= "Deploy a Drupal-based website on Clever Cloud" icon="drupal" >}} + {{< card link="/developers/guides/tutorial-laravel" title="Laravel" subtitle= "Deploy a Laravel app on Clever Cloud" icon="laravel" >}} + {{< card link="/developers/guides/tutorial-symfony" title="Symfony" subtitle= "Deploy a Symfony application on Clever Cloud" icon="symfony" >}} + {{< card link="/developers/guides/tutorial-wordpress" title="WordPress" subtitle= "Deploy WordPress on Clever Cloud" icon="wordpress" >}} + {{< card link="/developers/guides/moodle" title="Moodle" subtitle="Full Moodle installation and configuration guide" icon="moodle" >}} + +{{< /cards >}} + +Others PHP frameworks tested on Clever Cloud: + +- Prestashop +- Dokuwiki +- Joomla +- SugarCRM +- Drupal +- Magento +- Status.net +- Symfony +- Thelia +- Laravel +- Sylius + +## Configure Monolog + +A lot of frameworks (including Symfony) use Monolog to handle logging. The default configuration of Monolog doesn't allow to log errors into the console. + +Here is a basic configuration of Monolog to send your application's logs into our logging system and access them into the Console: + +```yaml +monolog: + handlers: + clever_logs: + type: error_log + level: warning +``` + +You can change the level to whatever level you desire. For Symfony, the configuration file is `app/config/config_prod.yml`. + +Laravel doesn't need Monolog to retrieve logs via Clever console or Clever CLI. Here, ensure that you have the following line in `config/app.php`: + +```php +return [ + // … + 'log' => env('APP_LOG'), + // … +]; +``` + +Then, set `APP_LOG=syslog` as Clever application environment variable. + +{{% content "new-relic" %}} + +{{% content "blackfire" %}} + +## ProxySQL + +{{% content "proxysql" %}} + +You can learn more about ProxySQL on the [dedicated documentation page](/guides/proxysql) + +{{% content "url_healthcheck" %}} +{{% content "redirectionio" %}} +{{% content "varnish" %}} diff --git a/content/doc/applications/php/apache.md b/content/doc/applications/php/apache.md new file mode 100644 index 000000000..ddc8de643 --- /dev/null +++ b/content/doc/applications/php/apache.md @@ -0,0 +1,121 @@ +--- +type: docs +linkTitle: Apache +title: Apache web server configuration +description: Configure Apache 2 for PHP applications on Clever Cloud with htaccess, authentication, HTTPS redirection, and FastCGI settings +keywords: +- apache +- htaccess +- htpasswd +- fastcgi +- https redirect +--- + +## Configure Apache + +Apache 2 is used as HTTP Server for PHP applications on Clever Cloud. You can configure it with `.htaccess` files and environment variables. + +### htaccess + +The `.htaccess` file can be created everywhere in your app, depending of the part of the application covered by directives. + +However, directives who applies to the entire application must be declared in a `.htaccess` file to the application root. + +### Basic authentication + +You can configure basic authentication using [environment variables](/doc/reference/reference-environment-variables#php). You will need to set `CC_HTTP_BASIC_AUTH` variable to your own `login:password` pair. If you need to allow access to multiple users, you can create additional environment `CC_HTTP_BASIC_AUTH_n` (where `n` is a number) variables. + +### HTTP timeout + +You can define the timeout of an HTTP request in Apache using the `HTTP_TIMEOUT` [environment variable](/doc/develop/env-variables). + +**By default, the HTTP timeout is set to 3 minutes (180 seconds)**. + +### Header size + +Default Apache header size is `8k`. If you need to increase it, you can set `CC_APACHE_HEADERS_SIZE` environment variable, between `8` and `256`. Effective value depends on deployment region. [Ask for a dedicated load balancer](https://console.clever-cloud.com/ticket-center-choice) for a specific value. + +### Force HTTPS traffic + +Load balancers handle HTTPS traffic ahead of your application. You can use the `X-Forwarded-Proto` header to know the original protocol (`http` or `https`). + +Place the following snippet in a `.htaccess` file to ensure that your visitors only access your application through HTTPS. + +```conf +RewriteEngine On +RewriteCond %{HTTPS} off +RewriteCond %{HTTP:X-Forwarded-Proto} !https +RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301] +``` + +### Prevent Apache to redirect HTTPS calls to HTTP when adding a trailing slash + +`DirectorySlash` is enabled by default on the PHP scalers, therefore Apache will add a trailing slash to a resource when it detects that it is a directory. + +E.g. if foobar is a directory, Apache will automatically redirect `http://example.com/foobar` to `http://example.com/foobar/`. + +Unfortunately the module is unable to detect if the request comes from a secure connection or not. As a result it will force an HTTPS call to be redirected to HTTP. + +In order to prevent this behavior, you can add the following statements in a `.htaccess` file: + +```conf +DirectorySlash Off +RewriteEngine On +RewriteCond %{REQUEST_FILENAME} -d +RewriteRule ^(.+[^/])$ %{HTTP:X-Forwarded-Proto}://%{HTTP_HOST}/$1/ [R=301,L,QSA] +``` + +These statements will keep the former protocol of the request when issuing the redirect. Assuming that the header `X-Forwarded-Proto` is always filled (which is the case on our platform). + +If you want to force all redirects to HTTPS, you can replace `%{HTTP:X-Forwarded-Proto}` with `https`. + +### Change the FastCGI module + +You can choose between two FastCGI modules, `fastcgi` and `proxy_fcgi`, using the `CC_CGI_IMPLEMENTATION` environment variable. If you don't set it `proxy_fcgi` is used as default value. `proxy_fcgi` is recommended, as `fastcgi` implementation is not maintained anymore. + +If you have issues with downloading content, it could be related to the `fastcgi` module not working correctly in combination with the `deflate` module, as the `Content-Length` header is not updated to the new size of the encoded content. To resolve this issue, use `proxy_fcgi`. + +## Header injection + +### With .htaccess + +To inject headers on HTTP responses, add this configuration to `.htaccess` file: + +```sh +Header Set Access-Control-Allow-Origin "https://www.example.com" +Header Set Access-Control-Allow-Headers "Authorization" +``` + +> [!NOTE] +> You can use a `.htaccess` file to create or update headers, but you can't delete them. + +### With PHP + +You can also do it from PHP: + +```php +header("Access-Control-Allow-Origin: https://www.example.com"); +header("Access-Control-Allow-Headers: Authorization"); +``` + +If you want to keep this separate from your application, you can configure the application to execute some code on every request. + +In `.user.ini`, add the following line (you need to create `inject_headers.php` first): + +```ini +auto_prepend_file=./inject_headers.php +``` + +- [Learn more about .user.ini directives](https://www.php.net/manual/en/configuration.file.per-user.php) + +## Using HTTP authentication + +Using basic HTTP authentication, PHP usually handles the values of user and password in variables named `$_SERVER['PHP_AUTH_USER']` and `$_SERVER['PHP_AUTH_PW']`. + +At Clever Cloud, an Apache option is enabled to pass directly the Authorization header, even though FastCGI is used; still, the header is not used by PHP, and the aforementioned variables are empty. + +You can do this to fill them using the Authorization header: + +```php +list($_SERVER['PHP_AUTH_USER'], $_SERVER['PHP_AUTH_PW']) = explode(':' , base64_decode(substr($_SERVER['Authorization'], 6))); +``` diff --git a/content/doc/applications/php/composer.md b/content/doc/applications/php/composer.md new file mode 100644 index 000000000..7e0e1672f --- /dev/null +++ b/content/doc/applications/php/composer.md @@ -0,0 +1,91 @@ +--- +type: docs +linkTitle: Composer +title: Composer and dependencies +description: Manage PHP dependencies with Composer on Clever Cloud, including version selection, development dependencies, and private repositories +keywords: +- composer +- php dependencies +- github rate limit +- dev dependencies +--- + +## Composer + +Composer build is supported out of the box. You just need to provide a `composer.json` file in the root of your repository and `composer.phar install --no-ansi --no-progress --no-interaction --no-dev` is run automatically during the build phase. + +You can also set the `CC_COMPOSER_VERSION` to `1` or `2` to select the composer version to use. + +> [!TIP] Use a local Composer version +> If you put a `composer.phar` file at the root of your project, it will be used to install dependencies. + +You can perform your own `composer.phar install` by using the [Post Build hook](/doc/develop/build-hooks#post-build-cc_post_build_hook). + +Example of a `composer.json` file: + +```json +{ + "require": { + "laravel/framework": "4.1.*", + "ruflin/Elastica": "dev-master", + "shift31/laravel-elasticsearch": "dev-master", + "natxet/CssMin": "dev-master" + }, + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/timothylhuillier/laravel-elasticsearch.git" + } + ], + "autoload": { + "classmap": [ + "app/controllers", + "app/models", + "app/database/migrations", + "app/database/seeds" + ], + "psr-0": { + "SomeApp": "app" + } + }, + "config": { + "preferred-install": "dist" + }, + "minimum-stability": "dev" +} +``` + +- [Example: minimalist PHP application using Composer and custom scripts](https://github.com/CleverCloud/php-composer-demo) + +## Development Dependencies + +Development dependencies are not automatically installed during the deployment. You can control their installation by using the `CC_PHP_DEV_DEPENDENCIES` environment variable which takes `install` value. + +Any other value than `install` will prevent development dependencies from being installed. + +## GitHub rate limit + +Sometimes, you can encounter the following error when downloading dependencies: + +```txt +Failed to download symfony/symfony from dist: Could not authenticate against GitHub.com +``` + +To prevent this download dependencies's fails that is often caused by rate limit of GitHub API while deploying your apps, +we recommend you to add `oauth` token in your composer configuration file or in separate file named as described in +[composer FAQ (API rate limit and OAuth tokens)](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens). + +You can find more documentation about composer configuration at [getcomposer.com](https://getcomposer.org/doc/04-schema.md). + +## Post-build hook example + +You use Artisan to manage your project and you want to execute *artisan migrate* before running your app. + +To do this, use a post build hook by setting the following environment variable on your Clever application: + +```bash +CC_POST_BUILD_HOOK=php artisan migrate --force +``` + +> [!NOTE] +> You must add the *execute* permission to your file (`chmod u+x yourfile`) before pushing it. diff --git a/content/doc/applications/php/extensions.md b/content/doc/applications/php/extensions.md new file mode 100644 index 000000000..51482d5e1 --- /dev/null +++ b/content/doc/applications/php/extensions.md @@ -0,0 +1,167 @@ +--- +type: docs +linkTitle: Extensions +title: PHP extensions +description: Available and on-demand PHP extensions on Clever Cloud, with activation instructions and phpinfo links +keywords: +- php extensions +- apcu +- xdebug +- opcache +- grpc +- opentelemetry +--- + +## Available extensions and modules + +Clever Cloud PHP with Apache applications enable the following extensions by default: + +`amqp`, `bcmath`, `bz2`, `calendar`, `ctype`, `curl`, `dba`, `exif`, `fileinfo`, `filter`, `ftp`, `gd`, `gettext`, `gmp`, `iconv`, `imagick`, `imap`, `intl`, `json`, `ldap`, `libsodium`, `mbstring`, `mcrypt`, `memcached`, `memcache`, `mongodb`, `mysql`, `mysqli`, `opcache`, `pcntl`, `pcre`, `pdo-mysql`, `pdo-odbc`, `pdo-pgsql`, `pdo-sqlite`, `pgsql`, `phar`, `posix`, `pspell`, `readline`, `redis`, `session`, `shmop`, `sockets`, `sodium`, `solr`, `ssh2`, `ssl`, `tidy`, `tokenizer`, `unixodbc`, `xml`, `xmlrpc`, `xsl`, `zip`, `zlib`. + +You can also enable the following extensions on demand: + +`apcu`, `blackfire`, `elastic_apm_agent`, `event`, `excimer`, `geos`, `gnupg`, `grpc`, `ioncube`, `imap`, `mailparse`, `maxminddb`, `mongo`, `newrelic`, `oauth`, `opentelemetry`, `pcs`, `PDFlib`, `pdo_sqlsrv`, `protobuf`, `pspell`, `rdkafka`, `scoutapm`, `sqlsrv`, `sqreen`, `tideways`, `uopz`, `uploadprogress`, `xdebug`, `xmlrpc`, `yaml` + +> [!NOTE] +> Only some extensions support PHP 8.5 for now: `amqp`, `apcu`, `blackfire`, `event`, `excimer`, `gnupg`, `grpc`, `imagick`, `imap`, `mailparse`, `maxminddb`, `memcached`, `oauth`, `opentelemetry`, `pdo_sqlsrv`, `protobuf`, `pspell`, `rdkafka`, `redis`, `sqlsrv`, `ssh2`, `tideways`, `uploadprogress`, `yaml`, `zip`. More extensions will be added as they are released. + +You can check extensions and versions by viewing the `phpinfo()` for: + +- [PHP 5.6](https://php56info.cleverapps.io) +- [PHP 7.1](https://php71info.cleverapps.io) +- [PHP 7.2](https://php72info.cleverapps.io) +- [PHP 7.3](https://php73info.cleverapps.io) +- [PHP 7.4](https://php74info.cleverapps.io) +- [PHP 8.0](https://php80info.cleverapps.io) +- [PHP 8.1](https://php81info.cleverapps.io) +- [PHP 8.2](https://php82info.cleverapps.io) +- [PHP 8.3](https://php83info.cleverapps.io) +- [PHP 8.4](https://php84info.cleverapps.io) +- [PHP 8.5](https://php85info.cleverapps.io) + +If you have a request about extensions, contact [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice). + +## Enable specific extensions + +Some extensions need to be enabled explicitly. To do so, set the corresponding environment variable: + +- APCu: set `ENABLE_APCU` to `true`. + + APCu is an in-memory key-value store for PHP. Keys are of type string and values can be any PHP variables. + +- Elastic APM Agent: set `ENABLE_ELASTIC_APM_AGENT` to `true` (default if `ELASTIC_APM_SERVER_URL` is defined). + + Elastic APM agent is Elastic's APM agent extension for PHP. The PHP agent enables you to trace the execution of operations + in your application, sending performance metrics and errors to the Elastic APM server. + **Warning**: This extension is available starting PHP 7.2. + +- Event: set `ENABLE_EVENT` to `true`. + + Event is an extension to schedule I/O, time and signal based events. + +- Excimer: set `ENABLE_EXCIMER` to `true`. + + Excimer is an extension that provides a low-overhead interrupting timer and sampling profiler. + +- GEOS: set `ENABLE_GEOS` to `true`. + + GEOS (Geometry Engine - Open Source) is a C++ port of the Java Topology Suite (JTS). + +- GnuPG: set `ENABLE_GNUPG` to `true`. + + GnuPG is an extension that provides methods to interact with GNU Privacy Guard (OpenPGP implementation). + +- gRPC: set `ENABLE_GRPC` to `true`. + + gRPC is an extension for the high performance, open source, general RPC framework layered over HTTP/2. + +- IonCube: set `ENABLE_IONCUBE` to `true`. + + IonCube is a tool to obfuscate PHP code. It's often used by paying Prestashop and WordPress plugins. + +- IMAP (only for PHP 8.4+): set `ENABLE_IMAP` to `true`. + + IMAP is an extension to operate with the IMAP protocol, as well as the NNTP, POP3, and local mailbox access methods. + +- Mailparse: set `ENABLE_MAILPARSE` to `true`. + + Mailparse is an extension for parsing and working with email messages. It can deal with RFC 822 and RFC 2045 (MIME) compliant messages. + +- MaxMind DB: set `ENABLE_MAXMINDDB` to `true`. + + Extension for reading MaxMind DB files. MaxMind DB is a binary file format that stores data indexed by IP address subnets (IPv4 or IPv6). + +- Mongo: set `ENABLE_MONGO` to `true`. + + MongoDB is a NoSQL Database. This extension allows to use it from PHP. + **Warning**: this extension is now superseded by the `mongodb` extension. It is provided for backward compatibility. + +- NewRelic: set `ENABLE_NEWRELIC` to `true`. + + Newrelic Agent for PHP. Newrelic is a software analytics tool. + +- OAuth: set `ENABLE_OAUTH` to `true`. + + OAuth consumer extension. OAuth is an authorization protocol built on top of HTTP. + +- OpenTelemetry: set `ENABLE_OPENTELEMETRY` to `true`. + + OpenTelemetry is an extension to facilitate the generation, export, collection of telemetry data such as traces, metrics, and logs. + +- PCS: set `ENABLE_PCS` to `true`. + + PCS provides a fast and easy way to mix C and PHP code in your PHP extension. + +- PDFlib: set `ENABLE_PDFlib` to `true`. + + PDFlib is a commercial library for generating PDF files. It provides a PHP extension to create and manipulate PDF documents. + +- Protobuf: set `ENABLE_PROTOBUF` to `true`. + + Protobuf is an extension for the language-neutral, platform-neutral extensible mechanism for serializing structured data. + +- Pspell: set `ENABLE_PSPELL` to `true`. + + Pspell is an extension to check the spelling of words and offer suggestions. + +- Rdkafka: set `ENABLE_RDKAFKA` to `true`. + + PHP-rdkafka is a thin librdkafka binding providing a working PHP 5 / PHP 7 Kafka client. + +- Scout APM: set `ENABLE_SCOUTAPM` to `true`. + + The Scout APM extension to provide additional capabilities to application monitoring over just using the base PHP userland library. + +- SQL Server: set `ENABLE_SQLSRV` or `ENABLE_PDO_SQLSRV` to `true`. + + These extensions enable drivers that rely on the Microsoft ODBC Driver to handle the low-level communication with SQL Server. The `SQLSRV` extension provides a procedural interface while the `PDO_SQLSRV` extension implements PDO for accessing data in all editions of SQL Server 2012 and later (including Azure SQL DB). + +- Sqreen: The Sqreen agent is started automatically after adding the environment variables (`SQREEN_API_APP_NAME` and `SQREEN_API_TOKEN`). + +- Tideways: set `ENABLE_TIDEWAYS` to `true`. + + Tideways is an extension that provides profiling and monitoring capabilities for PHP applications. + +- Uopz: set `ENABLE_UOPZ` to `true`. + + The uopz extension is focused on providing utilities to aid with unit testing PHP code. + +- Uploadprogress: set `ENABLE_UPLOADPROGRESS` to `true`. + + The uploadprogress extension is used to track the progress of a file download. + +- XDebug: set `ENABLE_XDEBUG` to `true`. + + XDebug is a debugger and profiler tool for PHP. + +- XML RPC: set `ENABLE_XMLRPC` to `true`. + + XML-RPC is an extension for server and client bindings + +- YAML: set `ENABLE_YAML` to `true`. + + YAML is an extension providing a YAML-1.1 parser and emitter + +## Disable extensions + +You can use `DISABLE_=true` in your [environment variables](/doc/reference/reference-environment-variables/) to disable an extension. diff --git a/content/doc/applications/php/sessions-emails.md b/content/doc/applications/php/sessions-emails.md new file mode 100644 index 000000000..2e7654939 --- /dev/null +++ b/content/doc/applications/php/sessions-emails.md @@ -0,0 +1,64 @@ +--- +type: docs +linkTitle: Sessions and Emails +title: PHP sessions and email configuration +description: Configure PHP session storage with FS Buckets or Redis, and SMTP email sending on Clever Cloud +keywords: +- php sessions +- fs bucket +- redis sessions +- materia kv +- smtp +- email sending +--- + +## Configure the session storage + +By default, an [FS Bucket](/doc/addons/fs-bucket/) is created for each PHP applications, so that session data is available on each instance. This FS Bucket is also used to store TMP files by default. You can change this behavior by setting the `TMPDIR` environment variable. You can set it to `/tmp` for example. + +> [!NOTE] FS Buckets are not available in HDS regions +> To deploy a PHP application on an HDS region, set [`CC_PHP_DISABLE_APP_BUCKET=true`](#speed-up-or-disable-the-session-fs-bucket). Consider using Redis to manage PHP sessions. + +### Speed up or disable the session FS Bucket + +You can set the following environment variables: + +- `CC_PHP_ASYNC_APP_BUCKET=async` to mount the session FS Bucket with the `async` option. + It speeds up the FS Bucket usage, but it can corrupt files in case of a network outage. +- `CC_PHP_DISABLE_APP_BUCKET=(true|yes|disable)` to entirely prevent the session FS Bucket + from being mounted. + Use this if you don't use the default PHP session library. + It will speed up your application but users might lose their session across instances + and deployments. + +### Use Materia KV or Redis to store PHP Sessions + +Clever Cloud allows to store PHP sessions easily in a [Materia KV](/doc/addons/materia-kv) or [Redis](/doc/addons/redis) add-on to improve performance/reliability. + +To enable this feature, you need to: + +- Set `ENABLE_REDIS=true` as [environment variable](/doc/develop/env-variables) in the PHP application +- Set `SESSION_TYPE=redis` as [environment variable](/doc/develop/env-variables) in the PHP application +- Create and link a Materia KV or Redis add-on to the PHP application + +## Sending emails + +The PHP language has the `mail` function to directly send emails. While no SMTP server is provided (needed to send the emails), you can configure one through environment variables. + +Mailpace add-on can send emails through PHP `mail()` function. You have to turn TLS on with port 465 (environment variable `CC_MTA_SERVER_USE_TLS=true`) to make Mailpace working. + +[Mailgun](https://www.mailgun.com/) or [Mailjet](https://www.mailjet.com/) are also recommended if your project supports it. These services already have everything you need to send emails from your code. + +### Configure the SMTP server + +Services like [Mailgun](https://www.mailgun.com/) or [Mailjet](https://www.mailjet.com/) provide SMTP servers. If your application has no other way but to use the `mail` function of PHP to send emails, you have to configure a SMTP server. This can be done through environment variables: + +| Name | Description | Default | +|------|-------------|---------| +| `CC_MTA_SERVER_HOST` | Host of the SMTP server | | +| `CC_MTA_SERVER_PORT` | Port of the SMTP server | `465` | +| `CC_MTA_AUTH_USER` | User to authenticate to the SMTP server | | +| `CC_MTA_AUTH_PASSWORD` | Password to authenticate to the SMTP server | | +| `CC_MTA_SERVER_USE_TLS` | Enable or disable TLS | `true` | +| `CC_MTA_SERVER_STARTTLS` | Enable or disable STARTTLS | `false` | +| `CC_MTA_SERVER_AUTH_METHOD` | Enable or disable authentication | `on` | diff --git a/content/doc/applications/python.md b/content/doc/applications/python.md deleted file mode 100644 index 90aa3989f..000000000 --- a/content/doc/applications/python.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -type: docs -linkTitle: Python -title: Python -description: Deploy Python 2 and 3 applications with uv support, Django, Flask, various frameworks, and configurable runtime settings -keywords: -- django -- fastapi -- flask -- pip -- python app hosting -- python cloud -- uv deployment -- uv native support -aliases: -- /applications/python -- /deploy/application/python/python_apps -- /doc/applications/python -- /doc/deploy/application/python -- /doc/deploy/application/python/python_apps -- /doc/en/python-hosting -- /doc/getting-started/by-language/python -- /doc/partials/language-specific-deploy/python -- /doc/python -- /doc/python/python_apps -- /doc/python-hosting -- /doc/reference/python -- /python -- /python/python_apps ---- - -## Overview - -Python is a programming language that lets you work more quickly and integrate your systems more efficiently. - -### Supported Versions - -The default version of Python on Clever Cloud is the latest we support from branch `3.x`. If you want to use Python `2.x`, create an [environment variable](#setting-up-environment-variables-on-clever-cloud) `CC_PYTHON_VERSION` set to `2`, it will default to Python 2.7. Other supported values are : - -{{< runtimes_versions python >}} - -{{% content "create-application" %}} - -{{% content "set-env-vars" %}} - -## Configure your Python application - -### General configuration - -Python apps can be launched in a variety of ways. You can specify how to start your application (for instance which module to run) by setting [environment variables](#setting-up-environment-variables-on-clever-cloud). - -To select which module you want to start, use the `CC_PYTHON_MODULE` environment variable. - -```bash -CC_PYTHON_MODULE="mymodule:app" -``` - -The module (without .py) must be importable, i.e. be in `PYTHONPATH`. Basically, you should just point to a WSGI capable object. - -For example with *Flask*, it's gonna be the name of your main server file, followed by your Flask object: `server:app` for instance if you have a `server.py` file at the root of your project with a Flask `app` object inside. - -You can also use `CC_RUN_COMMAND` to launch Python application your way. In such case, it must listen on port `9000`. - -### Use uv as a package manager - -Built in Rust, `uv` is a modern package and project manager for Python. It's fast to install dependencies, can be used as a drop-in replacement for `pip` and to sideload unsupported versions of Python. For example to use it with a `app.py` file, you just need to set `CC_RUN_COMMAND="uv run app.py"`. If your application listens on port `9000` with `0.0.0.0` as host, it will work fine on Clever Cloud. - -* [Learn more about uv](https://github.com/astral-sh/uv) - -{{< callout type="info" >}} - `uv` is part of our Enthusiast tools initiative, it's included and can be used, but there is no active support for it yet. -{{< /callout >}} - -### Select the python backend - -Currently, we support `daphne`, `gunicorn`, `uvicorn` and `uwsgi` for Python backends. If not specified, the default backend is `uwsgi`. - -To select one, set the `CC_PYTHON_BACKEND` [environment variable](#setting-up-environment-variables-on-clever-cloud) with either `daphne`, `gunicorn`, `uvicorn` or `uwsgi`. - -Please contact the support if you need another backend. - -### Dependencies - -If you do not have a `requirements.txt` file to commit you can obtain it via the command `pip freeze > requirements.txt` (or `pip3 freeze > requirements.txt` if you use Python 3.x) at the root of your project folder in your terminal. - -For example to install *PostgreSQL* and don't want to use the `pip freeze` command above you have to create a file `requirements.txt` at the root of your application folder: - -```txt -psycopg2>=2.7 --no-binary psycopg2 -``` - -**Note**: We recommend using `psycopg2>=2.7 --no-binary psycopg2` to avoid wsgi issues. - -You can define a custom `requirements.txt` file with the environnement variable `CC_PIP_REQUIREMENTS_FILE` for example: `CC_PIP_REQUIREMENTS_FILE=config/production.txt`. - -{{% content "cached-dependencies" %}} - -### Use setup.py - -We support execution of a single `setup.py` goal. Usually, this would be to execute custom tasks after the installation of dependencies. - -The goal will be launched after the dependencies from `requirements.txt` have been installed. - -To execute a goal, you can define the [environment variable](#setting-up-environment-variables-on-clever-cloud) `PYTHON_SETUP_PY_GOAL=""`. - - {{% content "env-injection" %}} - -To access [environment variables](#setting-up-environment-variables-on-clever-cloud) from your code, just get them from the environment with: - -```python -import os -os.getenv("MY_VARIABLE") -``` - -### Manage your static files - -To enable Nginx to serve your static resources, you have to set two [environment variables](#setting-up-environment-variables-on-clever-cloud). - -`STATIC_FILES_PATH`: should point to a directory where your static files are stored. - -`STATIC_URL_PREFIX`: the URL path under which you want to serve static files (e.g. `/public`). - -Also, you are able to use a Filesystem Bucket to store your static files. Please refer to the [File System Buckets](/doc/addons/fs-bucket) section. - -**Note**: the path of your folder must be absolute regarding the root of your application. - -**Note**: setting the `STATIC_URL_PREFIX` to `/` will cause the deployment failure. - -#### Static files example - -Here is how to serve static files, the `test.png` being the static file you want to serve: - -```txt -├── -│   ├── flask-app.py -│   ├── static -│   │   └── test.png -│   └── requirements.txt -``` - -Using the environment variables `STATIC_FILES_PATH=static/` and `STATIC_URL_PREFIX=/public` the `test.png` file will be accessed under: `https:///public/test.png`. - -### uWSGI, Gunicorn and Nginx configuration - -uWSGI, gunicorn and nginx settings can be configured by setting [environment variables](#setting-up-environment-variables-on-clever-cloud): - -#### uWSGI - -- `HARAKIRI`: timeout (in seconds) after which an unresponding process is killed. (Default: 180) -- `WSGI_BUFFER_SIZE`: maximal size (in bytes) for the headers of a request. (Default: 4096) -- `WSGI_POST_BUFFERING`: buffer size (in bytes) for uploads. (Default: 4096) -- `WSGI_WORKERS`: number of workers. (Default: depends on the scaler) -- `WSGI_THREADS`: number of threads per worker. (Default: depends on the scaler) - -##### uWSGI asynchronous/non-blocking modes - -To enable [uWSGI asynchronous](https://uwsgi-docs.readthedocs.io/en/latest/Async.html) mode, you can use these two environment variables: - -- `UWSGI_ASYNC`: [number of cores](https://uwsgi-docs.readthedocs.io/en/latest/Async.html#async-switches) to use for uWSGI asynchronous/non-blocking modes. -- `UWSGI_ASYNC_ENGINE`: select the [asynchronous engine for uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/Async.html#suspend-resume-engines) (optional). - -#### Gunicorn - -- `GUNICORN_WORKER_CLASS`: type of worker to use. Default to `sync`. [Available workers](https://docs.gunicorn.org/en/stable/settings.html#worker-class) -- `CC_GUNICORN_TIMEOUT`: gunicorn timeout. Defaults to `30` - -#### Nginx - -- `NGINX_READ_TIMEOUT`: a bit like `HARAKIRI`, the response timeout in seconds. (Default: 300) -- `ENABLE_GZIP_COMPRESSION`: "on|yes|true" gzip-compress the output. -- `GZIP_TYPES`: the mime types to gzip. Defaults to `text/plain text/css text/xml text/javascript application/json application/xml application/javascript image/svg+xml`. - -##### Basic authentication - -If you need basic authentication, you can enable it using [environment variables](/doc/reference/reference-environment-variables#python). You will need to set `CC_HTTP_BASIC_AUTH` variable to your own `login:password` pair. If you need to allow access to multiple users, you can create additional environment `CC_HTTP_BASIC_AUTH_n` (where `n` is a number) variables. - -#### Nginx optional configuration with `clevercloud/http.json` - -Nginx settings can be configured further in `clevercloud/http.json`. All its fields are optional. - -- `languages`: configure a default language and redirections -- `error_pages`: configure custom files for error pages -- `force_https`: automatically redirect HTTP traffic to HTTPS -- `aliases`: set up redirections -- `charset`: force a specific charset - -```json -{ - "languages": { - "default": {"rewrite": "en"}, - "fr": {"rewrite": "en"} - }, - "error_pages": { - "404": "path/to/page" - }, - "force_https": true, - "aliases": { - "/path": "redirection" - }, - "charset": "latin-1" -} -``` - -### Using the Gevent loop engine - -Whether you use uwsgi or gunicorn, you can enable the Gevent loop engine. - -To do so, add the `CC_PYTHON_USE_GEVENT` [environment variable](#setting-up-environment-variables-on-clever-cloud) to your application, with the `true` value. - - {{% content "new-relic" %}} - -## Celery apps - -**Note**: Please note that Celery support is not available yet for `gunicorn`. - -We also support celery apps out of the box. To deploy a celery app, use the `CC_PYTHON_CELERY_MODULE` [environment variable](#setting-up-environment-variables-on-clever-cloud): - -```bash -CC_PYTHON_CELERY_MODULE="mymodule" -``` - -{{< callout type="warning" >}} -Celery needs to be defined as a dependency in your requirements.txt. Otherwise the deployment will be aborted if Celery support is enabled. -{{< /callout >}} - -You can also activate beat with `CC_PYTHON_CELERY_USE_BEAT=true` and provide a given log dir for celery with `CC_PYTHON_CELERY_LOGFILE="/path/to/logdir"`. - -The `CC_PYTHON_CELERY_LOGFILE` path is relative to the application's path. - -{{< callout type="warning" >}} -There is a bug in versions <4.2 of Celery. You need to add the `CELERY_TIMEZONE = 'UTC'` environment variable. The bug is documented here: [https://github.com/celery/celery/issues/4184](https://github.com/celery/celery/issues/4184). -{{< /callout >}} - -{{% content "deploy-git" %}} - -{{% content "link-addon" %}} - -{{% content "more-config" %}} - -{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/python/_index.md b/content/doc/applications/python/_index.md new file mode 100644 index 000000000..f51f87279 --- /dev/null +++ b/content/doc/applications/python/_index.md @@ -0,0 +1,141 @@ +--- +type: docs +linkTitle: Python +title: Python application runtime +description: Deploy Python 2 and 3 applications with uv support, Django, Flask, various frameworks, and configurable runtime settings +keywords: +- django +- fastapi +- flask +- pip +- python app hosting +- python cloud +- uv deployment +- uv native support +aliases: +- /applications/python +- /deploy/application/python/python_apps +- /doc/applications/python +- /doc/deploy/application/python +- /doc/deploy/application/python/python_apps +- /doc/en/python-hosting +- /doc/getting-started/by-language/python +- /doc/partials/language-specific-deploy/python +- /doc/python +- /doc/python/python_apps +- /doc/python-hosting +- /doc/reference/python +- /python +- /python/python_apps +--- + +## Overview + +Python is a programming language that lets you work more quickly and integrate your systems more efficiently. + +## Create your Python application + +To create a new Python application, use the [Clever Cloud Console](https://console.clever-cloud.com) or [Clever Tools](https://github.com/CleverCloud/clever-tools): + +```bash +clever create --type python +``` +- [Learn more about Clever Tools](/doc/cli/) +- [Learn more about Clever Cloud application deployment](/doc/quickstart/#create-an-application-step-by-step) + +## Configure your Python application + +### Mandatory needs + +Python apps can be launched in a variety of ways. To select which module you want to start, use the `CC_PYTHON_MODULE` environment variable. + +```bash +CC_PYTHON_MODULE="mymodule:app" +``` + +The module (without .py) must be importable, i.e. be in `PYTHONPATH`. Basically, you should just point to a WSGI capable object. + +For example with *Flask*, it's gonna be the name of your main server file, followed by your Flask object: `server:app` for instance if you have a `server.py` file at the root of your project with a Flask `app` object inside. + +You can also use `CC_RUN_COMMAND` to launch a Python application your way. In such case, it must listen on port `9000`. + +- [Learn more about environment variables on Clever Cloud](/doc/reference/reference-environment-variables/) + +### Python version + +The default version of Python on Clever Cloud is the latest supported from branch `3.x`. If you want to use Python `2.x`, set `CC_PYTHON_VERSION` to `2`, it will default to Python 2.7. Other supported values are: + +{{< runtimes_versions python >}} + +### Build phase + +#### Dependencies + +If you do not have a `requirements.txt` file to commit you can obtain it via the command `pip freeze > requirements.txt` (or `pip3 freeze > requirements.txt` if you use Python 3.x) at the root of your project folder in your terminal. + +For example, if you want to install *PostgreSQL* without using the `pip freeze` command above, create a `requirements.txt` file at the root of your application folder: + +```txt +psycopg2>=2.7 --no-binary psycopg2 +``` + +> [!NOTE] +> Using `psycopg2>=2.7 --no-binary psycopg2` is recommended to avoid wsgi issues. + +You can define a custom `requirements.txt` file with the environment variable `CC_PIP_REQUIREMENTS_FILE` for example: `CC_PIP_REQUIREMENTS_FILE=config/production.txt`. + +{{% content "cached-dependencies" %}} + +#### Use setup.py + +Execution of a single `setup.py` goal is supported. Usually, this would be to execute custom tasks after the installation of dependencies. + +The goal will be launched after the dependencies from `requirements.txt` have been installed. + +To execute a goal, define the environment variable `PYTHON_SETUP_PY_GOAL=""`. + +- [Learn more about Deployment hooks](/doc/develop/build-hooks/) + +### Select the Python backend + +Currently, `daphne`, `gunicorn`, `uvicorn` and `uwsgi` are supported for Python backends. If not specified, the default backend is `uwsgi`. + +To select one, set the `CC_PYTHON_BACKEND` environment variable with either `daphne`, `gunicorn`, `uvicorn` or `uwsgi`. + +Contact the support if you need another backend. + +> [!NOTE] +> Backend selection only applies to the legacy deployment mode (without `uv.lock`). [Native uv deployments](/doc/applications/python/uv/) manage their own HTTP server. + +### Using the Gevent loop engine + +Whether you use uwsgi or gunicorn, you can enable the Gevent loop engine. + +To do so, add the `CC_PYTHON_USE_GEVENT` environment variable to your application, with the `true` value. + +## Celery apps + +> [!NOTE] +> Celery support is not available yet for `gunicorn`. + +Celery apps are supported out of the box. To deploy a celery app, use the `CC_PYTHON_CELERY_MODULE` environment variable: + +```bash +CC_PYTHON_CELERY_MODULE="mymodule" +``` + +> [!WARNING] +> Celery needs to be defined as a dependency in your requirements.txt. Otherwise the deployment will be aborted if Celery support is enabled. + +You can also activate beat with `CC_PYTHON_CELERY_USE_BEAT=true` and provide a given log dir for celery with `CC_PYTHON_CELERY_LOGFILE="/path/to/logdir"`. + +The `CC_PYTHON_CELERY_LOGFILE` path is relative to the application's path. + +> [!WARNING] +> There is a bug in versions <4.2 of Celery. You need to add the `CELERY_TIMEZONE = 'UTC'` environment variable. The bug is documented here: [https://github.com/celery/celery/issues/4184](https://github.com/celery/celery/issues/4184). + +{{% content "new-relic" %}} + +{{% content "url_healthcheck" %}} +{{% content "redirectionio" %}} +{{% content "varnish" %}} diff --git a/content/doc/applications/python/servers.md b/content/doc/applications/python/servers.md new file mode 100644 index 000000000..6d7f87826 --- /dev/null +++ b/content/doc/applications/python/servers.md @@ -0,0 +1,110 @@ +--- +type: docs +linkTitle: Servers +title: Python servers configuration +description: Configure uWSGI, Gunicorn, and Nginx settings for Python applications on Clever Cloud including static files, HTTPS, and basic authentication +keywords: +- uwsgi +- gunicorn +- nginx +- python server +- static files +--- + +## uWSGI, Gunicorn and Nginx configuration + +> [!NOTE] +> This page applies to the legacy Python deployment mode (without `uv.lock`). [Native uv deployments](/doc/applications/python/uv/) manage their own HTTP server and do not use uWSGI, Gunicorn, or Nginx. + +uWSGI, Gunicorn and Nginx settings can be configured by setting environment variables. + +### uWSGI + +| Name | Description | Default | +|------|-------------|---------| +| `HARAKIRI` | Timeout (in seconds) after which an unresponding process is killed | `180` | +| `WSGI_BUFFER_SIZE` | Maximal size (in bytes) for the headers of a request | `4096` | +| `WSGI_POST_BUFFERING` | Buffer size (in bytes) for uploads | `4096` | +| `WSGI_WORKERS` | Number of workers | depends on the scaler | +| `WSGI_THREADS` | Number of threads per worker | depends on the scaler | + +#### uWSGI asynchronous/non-blocking modes + +To enable [uWSGI asynchronous](https://uwsgi-docs.readthedocs.io/en/latest/Async.html) mode, you can use these two environment variables: + +- `UWSGI_ASYNC`: [number of cores](https://uwsgi-docs.readthedocs.io/en/latest/Async.html#async-switches) to use for uWSGI asynchronous/non-blocking modes. +- `UWSGI_ASYNC_ENGINE`: select the [asynchronous engine for uWSGI](https://uwsgi-docs.readthedocs.io/en/latest/Async.html#suspend-resume-engines) (optional). + +### Gunicorn + +| Name | Description | Default | +|------|-------------|---------| +| `GUNICORN_WORKER_CLASS` | Type of worker to use. [Available workers](https://docs.gunicorn.org/en/stable/settings.html#worker-class) | `sync` | +| `CC_GUNICORN_TIMEOUT` | Gunicorn timeout | `30` | + +### Nginx + +| Name | Description | Default | +|------|-------------|---------| +| `NGINX_READ_TIMEOUT` | Response timeout in seconds (similar to `HARAKIRI`) | `300` | +| `ENABLE_GZIP_COMPRESSION` | Enable gzip compression (`on`, `yes`, or `true`) | | +| `GZIP_TYPES` | The mime types to gzip | `text/plain text/css text/xml text/javascript application/json application/xml application/javascript image/svg+xml` | + +#### Basic authentication + +If you need basic authentication, you can enable it using [environment variables](/doc/reference/reference-environment-variables#python). Set `CC_HTTP_BASIC_AUTH` variable to your own `login:password` pair. If you need to allow access to multiple users, you can create additional environment `CC_HTTP_BASIC_AUTH_n` (where `n` is a number) variables. + +#### Nginx optional configuration with `clevercloud/http.json` + +Nginx settings can be configured further in `clevercloud/http.json`. All its fields are optional. + +- `languages`: configure a default language and redirections +- `error_pages`: configure custom files for error pages +- `force_https`: automatically redirect HTTP traffic to HTTPS +- `aliases`: set up redirections +- `charset`: force a specific charset + +```json +{ + "languages": { + "default": {"rewrite": "en"}, + "fr": {"rewrite": "en"} + }, + "error_pages": { + "404": "path/to/page" + }, + "force_https": true, + "aliases": { + "/path": "redirection" + }, + "charset": "latin-1" +} +``` + +## Manage static files + +To enable Nginx to serve your static resources, you have to set two environment variables. + +| Name | Description | +|------|-------------| +| `STATIC_FILES_PATH` | Directory where your static files are stored (absolute path relative to the application root) | +| `STATIC_URL_PREFIX` | URL path under which you want to serve static files (e.g. `/public`) | + +You can also use a [Filesystem Bucket](/doc/addons/fs-bucket) to store your static files. + +> [!WARNING] +> Setting the `STATIC_URL_PREFIX` to `/` will cause the deployment failure. + +### Static files example + +Here is how to serve static files, the `test.png` being the static file you want to serve: + +```txt +├── +│ ├── flask-app.py +│ ├── static +│ │ └── test.png +│ └── requirements.txt +``` + +Using the environment variables `STATIC_FILES_PATH=static/` and `STATIC_URL_PREFIX=/public` the `test.png` file will be accessed under: `https:///public/test.png`. diff --git a/content/doc/applications/python/uv.md b/content/doc/applications/python/uv.md new file mode 100644 index 000000000..6a9a2f923 --- /dev/null +++ b/content/doc/applications/python/uv.md @@ -0,0 +1,66 @@ +--- +type: docs +linkTitle: Deploy with uv +title: Deploy Python with uv +description: Deploy Python applications with native uv support on Clever Cloud, using uv.lock for dependency management and direct HTTP server binding +keywords: +- uv +- python uv +- uv deployment +- uv sync +- astral +--- + +## Overview + +[uv](https://docs.astral.sh/uv/) is a modern package and project manager for Python, built in Rust. Clever Cloud provides native uv deployment support as an alternative to the legacy WSGI-based deployment (uWSGI/Gunicorn + Nginx). With uv, your application manages its own HTTP server and listens directly on port `8080`. + +## Activation + +Native uv deployment activates when both conditions are met: + +- A `uv.lock` file exists at the root of your project +- The `CC_PYTHON_UV_RUN_COMMAND` environment variable is set to a valid command + +If either condition is missing, the application deploys with the [legacy Python backend](/doc/applications/python/#select-the-python-backend). + +## Build phase + +During the build phase, dependencies are installed with: + +```bash +uv sync --locked --no-progress --no-dev +``` + +To install development dependencies, set `ENVIRONMENT=development`. The `--no-dev` flag is then removed. + +The uv cache (`~/.cache/uv`) is included in the build cache to speed up subsequent deployments. + +- [Learn more about Deployment hooks](/doc/develop/build-hooks/) + +## Run phase + +The application starts with the command defined in `CC_PYTHON_UV_RUN_COMMAND`. It must start an HTTP server listening on `0.0.0.0:8080`. + +`CC_RUN_COMMAND` takes precedence over `CC_PYTHON_UV_RUN_COMMAND` if both are set. + +| Name | Description | Required | +|------|-------------|----------| +| `CC_PYTHON_UV_RUN_COMMAND` | Command to start the application (e.g. `uv run python app.py`) | Yes | +| `CC_RUN_COMMAND` | Overrides `CC_PYTHON_UV_RUN_COMMAND` if set | No | +| `ENVIRONMENT` | Set to `development` to include dev dependencies during build | No | + +## Differences with legacy Python deployment + +With native uv deployment: + +- No Nginx, uWSGI, or Gunicorn is involved +- Your application listens on port `8080` (not `9000`) +- `CC_PYTHON_MODULE` and `CC_PYTHON_BACKEND` are ignored +- [Redirection.io, Varnish and custom proxies](/doc/develop/request-flow/) are configured through Request Flow, not Nginx +- [Server configuration](/doc/applications/python/servers/) settings do not apply + +- [Learn more about uv](https://docs.astral.sh/uv/) + +{{% content "url_healthcheck" %}} +{{% content "request-flow" %}}