diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 000000000..162dbad03 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,291 @@ +# AI Content Creation Rules for Clever Cloud Documentation + +This document provides comprehensive guidance for AI systems on creating high-quality content for Clever Cloud's documentation platform, including technical documentation, guides, and changelog entries. + +## Development Environment + +This is a Hugo-based documentation site using the Hextra theme. + +### Hugo Development Commands +- **Build and serve locally**: `hugo server` (site available at http://localhost:1313) +- **Build for production**: `hugo` (outputs to `public/developers/`) +- **Preview with drafts**: `hugo server --buildDrafts` +- **Generate new content**: + - `hugo new content guides/.md` + - `hugo new content/doc/administrate/.md` + - `hugo new content --kind applications doc/applications/.md` +- **Update CLI reference**: `./update-cli-reference.sh` + +### Project Structure +- **Content organization**: `/content/` contains all documentation: + - `doc/` - Main documentation (applications, addons, CLI, etc.) + - `guides/` - Framework-specific tutorials and guides + - `changelog/` - Platform updates and announcements + - `api/` - API documentation + - `postmortem/` - Incident reports +- **Shared content**: `/shared/` contains reusable content blocks +- **Data files**: `/data/` contains structured data (runtime versions, tooltips, etc.) +- **Static assets**: `/static/` for images, fonts, and other assets + +### Content Management System +- Uses Hugo front matter with fields: `type`, `weight`, `linkTitle`, `description`, `excludeSearch`, `aliases`, `draft`, `tags`, `authors` +- New pages have `draft: true` by default - change to `false` to publish +- Tooltips defined in `data/tooltips.toml` and auto-display on hover +- **Quality enforcement**: + - Markdown linting via markdownlint-cli2 (config: `.markdownlintignore`, `.markdownlint.jsonc`) + - Editorial checks via Vale.sh (config: `.vale.ini`) + - Vocabulary in `.github/styles/config/vocabularies/Doc/accept.txt` + +## Content Types Overview + +### 1. Technical Documentation (`/content/doc/`) +Formal reference material for platform features, APIs, and configurations. +- **Style**: Professional, precise, instructional +- **Structure**: Hierarchical with clear sections +- **Purpose**: Enable users to accomplish specific tasks + +### 2. Guides & Tutorials (`/content/guides/`) +Step-by-step instructions for implementing specific technologies or frameworks. +- **Style**: Educational, conversational but focused +- **Structure**: Progressive steps with examples +- **Purpose**: Guide users through complete implementation + +### 3. Changelog Entries (`/content/changelog/`) +Technical blog-style posts announcing platform updates and new features. +- **Style**: Engaging, informative, personality allowed +- **Structure**: Context → announcement → practical examples → links +- **Purpose**: Inform users about platform evolution + +## Writing Style Guidelines + +### Universal Rules (All Content Types) + +#### Language Standards +- Use **second person** ("you") to address readers directly +- Write in **active voice** - avoid passive constructions +- Use **British spelling** for "organisation" not "organization" +- **Avoid first-person pronouns**: I, me, my, we, us, our, let's +- Keep sentences **short and clear** (max 25 words when possible) +- **No jargon** - explain technical terms when first introduced + +#### Prohibited Phrases +- Placeholder phrases: "please note", "at this time", "it should be noted" +- Overconfident claims: "simply", "just", "easily", "quickly", "obviously" +- Time-dependent promises: "soon", "in the future", "coming next month" +- Over-politeness: excessive use of "please" + +#### Required Elements +- **Don't assume prior knowledge** - over-explain rather than under-explain +- Address the reader's **specific use case** and context +- Provide **concrete examples** with real commands, code, or configurations +- Include **relevant links** to related documentation + +### Documentation-Specific Rules + +#### Structure Requirements +```yaml +--- +type: docs +linkTitle: Short Title +title: Full Page Title +description: SEO-friendly description explaining what users will learn +aliases: +- /old/url/path +--- +``` + +#### Content Organization +- **Overview section** - Brief explanation of what the technology/feature is +- **Create/Setup section** - How to get started +- **Configure section** - Detailed configuration options +- **Advanced features** - Optional capabilities +- **Examples and references** - Practical implementations + +#### Technical Specifications +- Always specify **current versions** of software/tools +- Include **environment variables** with exact names and examples +- Provide **command-line examples** with proper syntax +- Use **callouts for important information**: + ```markdown + > [!NOTE] Context about new features + > [!TIP] Helpful suggestions + > [!WARNING] Important considerations + ``` + +### Guide-Specific Rules + +#### Engaging Introduction +- Start with **hero subtitle shortcode** explaining the framework/tool benefits +- Use **hextra shortcodes** for enhanced presentation: + ```markdown + {{< hextra/hero-subtitle >}} + Brief engaging description of what users will build + {{< /hextra/hero-subtitle >}} + ``` + +#### Step-by-Step Structure +- Use **steps shortcode** for sequential instructions: + ```markdown + {{% steps %}} + ### Step Title + Content and commands + {{% /steps %}} + ``` + +- Include **tab groups** for different package managers/approaches: + ```markdown + {{< tabs items="npm,yarn,pnpm" >}} + {{< tab >}}Content for npm{{< /tab >}} + {{< tab >}}Content for yarn{{< /tab >}} + {{< /tabs >}} + ``` + +#### Learning Resources +- End with **cards section** linking to related documentation: + ```markdown + {{< cards >}} + {{< card link="/path" title="Title" subtitle="Description" icon="icon-name" >}} + {{< /cards >}} + ``` + +### Changelog-Specific Rules + +#### Front Matter Format +```yaml +--- +title: Descriptive title about the update/feature +description: Brief one-line summary +date: YYYY-MM-DD +tags: + - relevant-product-tags +authors: + - name: Full Name + link: https://github.com/username + image: https://github.com/username.png?size=40 +excludeSearch: true +--- +``` + +#### Writing Style for Changelog +- **More personality allowed** - can be engaging and slightly conversational +- **Lead with impact** - explain why this matters to users +- **Provide context** - link to upstream releases, related changes +- **Include practical examples** - show users exactly how to use new features +- **Multiple entries per day acceptable** - don't batch unrelated updates + +#### Content Flow Pattern +1. **Context paragraph** - What changed and why it matters +2. **Technical details** - Versions, new features, improvements +3. **Implementation examples** - Concrete commands or configuration +4. **Related links** - Documentation, examples, community resources + +#### Command Examples in Changelog +Always show **complete command sequences**: +```bash +# Enable the feature +clever features enable operators + +# Check current version +clever keycloak version check yourKeycloakNameOrId + +# Update to latest +clever keycloak version update yourKeycloakNameOrId +``` + +## Technical Implementation Standards + +### Code Examples +- **Always complete and runnable** - no placeholder variables without explanation +- **Include setup context** - show what directory, prerequisites needed +- **Use realistic names** - avoid "foo", "bar", "example" +- **Show expected output** when helpful + +### Environment Variables +- **Exact variable names** with proper casing: `CC_NODE_BUILD_TOOL` +- **Show complete examples**: + ```bash + CC_WEBROOT="public" + CC_RUN_COMMAND="npm start" + ``` +- **Explain the impact** of each variable + +### File References +- **Absolute paths** when referencing project structure +- **Relative paths** when showing user actions: `./package.json` +- **Proper syntax highlighting** for code blocks + +## Content Quality Checklist + +### Before Publishing Documentation +- [ ] All commands tested and work as shown +- [ ] Environment variables verified with exact syntax +- [ ] Links point to correct, existing pages +- [ ] Examples use realistic project names and values +- [ ] No first-person pronouns (I, we, us, our) +- [ ] Short, clear sentences under 25 words +- [ ] Proper callouts for important information + +### Before Publishing Changelog +- [ ] Clear benefit/impact stated upfront +- [ ] Version numbers and dates accurate +- [ ] Complete command examples provided +- [ ] Author information included with GitHub avatar +- [ ] Tags relevant to affected products +- [ ] Links to documentation and examples working + +### Before Publishing Guides +- [ ] Step-by-step flow tested end-to-end +- [ ] All code examples complete and functional +- [ ] Prerequisites clearly stated +- [ ] Expected outcomes explained +- [ ] Hextra shortcodes used appropriately +- [ ] Learning resources section included + +## Shared Content Usage + +### Including Reusable Blocks +- Use `{{% content "filename" %}}` for basic shared content +- Use `{{% content-raw "filename" %}}` for content containing shortcodes +- Available shared blocks in `/shared/` directory include common procedures + +### Creating New Shared Content +- Extract **commonly repeated information** into `/shared/filename.md` +- **No headings** in shared content (breaks table of contents) +- Focus on **procedural steps** rather than context + +## Maintenance and Updates + +### Keeping Content Current +- **Version numbers** should reflect current platform state +- **Screenshots and UI references** need regular updates +- **External links** should be verified periodically +- **Deprecated features** should be clearly marked + +### Community Integration +- **Link to community discussions** for new features +- **Reference GitHub examples** when available +- **Encourage feedback** on experimental features +- **Update based on user reports** and common issues + +## Deployment Configuration + +The site is designed for Clever Cloud hosting with these environment variables: +- `CC_WEBROOT="public"` +- `CC_STATIC_AUTOBUILD_OUTDIR="public/developers"` +- `SERVER_ERROR_PAGE_404="developers/404.html"` +- Optional: `CC_HUGO_VERSION` to specify Hugo version + +## Quality Assurance Requirements + +### Build Verification +Always test changes with the `hugo` command before committing to ensure the build is functional. Fix any build errors immediately as they prevent deployment. Verify that all links, references, image paths, and shortcode syntax work correctly in the generated output. + +### Content Quality Standards +Minimise the use of bullet points and lists. Use them only when essential for clarity or information efficiency. +Structure each section with 2-4 well-developed paragraphs. Avoid single text blocks or overly fragmented content. +Aim for paragraphs of 3-6 lines for optimal readability. Each paragraph should contain a complete thought or concept. +Use descriptive section titles. Titles should create useful table of contents entries. +Organise information logically so each section forms a coherent, useful unit. +Ensure all necessary information is included in readable prose, not fragmented lists. + +This document ensures consistent, high-quality content across all Clever Cloud documentation while respecting the different styles appropriate for technical docs, educational guides, and announcement posts. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..3ba13e0ce --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/new-content-form.yaml b/.github/ISSUE_TEMPLATE/new-content-form.yaml new file mode 100644 index 000000000..c2c0fe911 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new-content-form.yaml @@ -0,0 +1,26 @@ +name: Suggest a new page or section +description: Suggest new content for the documentation +title: "Doc: " +labels: ["documentation"] +projects: "CleverCloud/10" +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this new content form! + - type: checkboxes + id: existing-issue + attributes: + label: Checking for existing issue + description: Have you checked your request hasn't been already addressed in another issue? + options: + - label: I have checked for existing [issues](https://github.com/CleverCloud/documentation/issues) + required: true + - type: textarea + id: describe-content + attributes: + label: "Describe the content you'd like to see" + description: "A clear and concise description of what you want to happen." + placeholder: "I'd like to have a new page/section about…" + validations: + required: true diff --git a/.github/external-doc-issue.yml b/.github/external-doc-issue.yml new file mode 100644 index 000000000..b22601341 --- /dev/null +++ b/.github/external-doc-issue.yml @@ -0,0 +1,18 @@ +--- +title: External doc update from PR {{ env.PR_NUMBER }} +labels: documentation +--- + +## External documentation update needed + +Update the external documentation: + +- Author: @{{ payload.sender.login }} +- PR: {{ env.PR_URL }} +- Modified files: {{ env.CHANGED_FILES }} + +Make a PR on one of these repositories: + +- [Astro](https://github.com/withastro/docs) + + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..b7a13e767 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,14 @@ +## Describe your PR + +_Summarize your changes here : explain what, how, and why. Be as explicict as you can on why your changes are needed and avoid implicit reasoning._ + + +## Checklist + +- [ ] My PR is related to an opened issue : # +- [ ] I've read the [contributing guidelines](/CleverCloud/documentation/blob/main/CONTRIBUTING.md) + + +## Reviewers +_Who should review these changes?_ @CleverCloud/reviewers + diff --git a/.github/styles/.vale-config/0-Hugo.ini b/.github/styles/.vale-config/0-Hugo.ini new file mode 100644 index 000000000..4347ca9e9 --- /dev/null +++ b/.github/styles/.vale-config/0-Hugo.ini @@ -0,0 +1,10 @@ +[*.md] +# Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}}) +TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \ +(\[.+\]\({{< .+ >}}\)), \ +[^\S\r\n]({{[%<] \w+ .+ [%>]}})\s, \ +[^\S\r\n]({{[%<](?:/\*) .* (?:\*/)[%>]}})\s + +# Exclude `{{< myshortcode `This is some HTML, ... >}}` +BlockIgnores = (?sm)^({{[%<] \w+ [^{]*?\s[%>]}})\n$, \ +(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}) diff --git a/.github/styles/Clever/ellipsis.yml b/.github/styles/Clever/ellipsis.yml new file mode 100644 index 000000000..df50ec781 --- /dev/null +++ b/.github/styles/Clever/ellipsis.yml @@ -0,0 +1,8 @@ +extends: substitution +message: "Use '…' (ellipsis character) instead of '%s'" +level: warning +ignorecase: false + +# Replace three consecutive periods with proper ellipsis +swap: + '\.\.\.': '…' diff --git a/.github/styles/Clever/hyphens.yml b/.github/styles/Clever/hyphens.yml new file mode 100644 index 000000000..740979078 --- /dev/null +++ b/.github/styles/Clever/hyphens.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Write '%s' with hyphens when used as an adjective before a noun, but as separate words when it appears as a noun phrase or after a verb" +level: suggestion +ignorecase: true +tokens: + - 'up-to-date' + - 'up to date' + - 'end-of-life' + - 'end of life' diff --git a/.github/styles/Clever/organisation.yml b/.github/styles/Clever/organisation.yml new file mode 100644 index 000000000..08265c8dd --- /dev/null +++ b/.github/styles/Clever/organisation.yml @@ -0,0 +1,8 @@ +extends: substitution +message: "Use 'organisation' instead of 'organization'" +level: error +ignorecase: true + +swap: + organization: organisation + organizations: organisations diff --git a/.github/styles/Google/AMPM.yml b/.github/styles/Google/AMPM.yml new file mode 100644 index 000000000..37b49edf8 --- /dev/null +++ b/.github/styles/Google/AMPM.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Use 'AM' or 'PM' (preceded by a space)." +link: "https://developers.google.com/style/word-list" +level: error +nonword: true +tokens: + - '\d{1,2}[AP]M\b' + - '\d{1,2} ?[ap]m\b' + - '\d{1,2} ?[aApP]\.[mM]\.' diff --git a/.github/styles/Google/Acronyms.yml b/.github/styles/Google/Acronyms.yml new file mode 100644 index 000000000..f41af0189 --- /dev/null +++ b/.github/styles/Google/Acronyms.yml @@ -0,0 +1,64 @@ +extends: conditional +message: "Spell out '%s', if it's unfamiliar to the audience." +link: 'https://developers.google.com/style/abbreviations' +level: suggestion +ignorecase: false +# Ensures that the existence of 'first' implies the existence of 'second'. +first: '\b([A-Z]{3,5})\b' +second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' +# ... with the exception of these: +exceptions: + - API + - ASP + - CLI + - CPU + - CSS + - CSV + - DEBUG + - DOM + - DPI + - FAQ + - GCC + - GDB + - GET + - GPU + - GTK + - GUI + - HTML + - HTTP + - HTTPS + - IDE + - JAR + - JSON + - JSX + - LESS + - LLDB + - NET + - NOTE + - NVDA + - OSS + - PATH + - PDF + - PHP + - POST + - RAM + - REPL + - RSA + - SCM + - SCSS + - SDK + - SQL + - SSH + - SSL + - SVG + - TBD + - TCP + - TODO + - URI + - URL + - USB + - UTF + - XML + - XSS + - YAML + - ZIP diff --git a/.github/styles/Google/Colons.yml b/.github/styles/Google/Colons.yml new file mode 100644 index 000000000..4a027c307 --- /dev/null +++ b/.github/styles/Google/Colons.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' should be in lowercase." +link: 'https://developers.google.com/style/colons' +nonword: true +level: warning +scope: sentence +tokens: + - '(?=1.0.0" +} diff --git a/.github/styles/Google/vocab.txt b/.github/styles/Google/vocab.txt new file mode 100644 index 000000000..e69de29bb diff --git a/.github/styles/Guides/ellipsis.yml b/.github/styles/Guides/ellipsis.yml new file mode 100644 index 000000000..305d64fb4 --- /dev/null +++ b/.github/styles/Guides/ellipsis.yml @@ -0,0 +1,10 @@ +extends: existence +message: "Include the framework in the title!" +nonword: true +level: error +scope: heading +action: + name: remove +tokens: + - '\[\.\.\.\]' + diff --git a/.github/styles/config/vocabularies/Doc/accept.txt b/.github/styles/config/vocabularies/Doc/accept.txt new file mode 100644 index 000000000..39bcc595f --- /dev/null +++ b/.github/styles/config/vocabularies/Doc/accept.txt @@ -0,0 +1,108 @@ +add-on +ant +ANSI +APIs +application +app_id +Astro +Astrowind +Azimutt +Blackfire +boto +Caddy +Caddyfile +callout +CDN +CDNs +charset +checkMe +Clever Cloud +CLI +Cloud +config +Coraza +Corepack +CORS +CRDs +cron +Cyberduck +Deno +DNS +Dockerfile +downtimes +eg +EOL +failover +Filestash +Filezilla +FPM +FrankenPHP +FSBucket +Gemfile +Glassfish +Gradle +gradle +Grafana +healthcheck +Heptapod +Hextra +hostname +jarName +Jboss +Keycloak +Kubectl +Laravel +Let's Encrypt +LLM +LLMs +Lume +LTS +Matomo +maven +Metabase +monolog +monorepo +monorepository +Moodle +namespace +namespaces +nano +nmap +npm +Nuxt +OAuth +Otoroshi +packageManager +Payara +Percona +Pgpool +pico +pnpm +proxyhugo +psql +rackup +rclone +Redict +redirections +RSS +runtimes +sbt +scalers +SCMs +serverless +Servlet +shortcode +Sidekiq +Symfony +syslog +TLS +toolchain +tooltip +tooltips +URIs +VSCode +WAF +webroot +Wildfly +yjs +Zooper diff --git a/.github/styles/config/vocabularies/Doc/reject.txt b/.github/styles/config/vocabularies/Doc/reject.txt new file mode 100644 index 000000000..2cbb58169 --- /dev/null +++ b/.github/styles/config/vocabularies/Doc/reject.txt @@ -0,0 +1,6 @@ +addon +addons +plug-in +plug-ins +e-mail +e-mails diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 000000000..05216bc33 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,68 @@ +name: Deploy + +on: + pull_request_target: + types: [closed, opened, reopened, synchronize] + branches: [ main ] + +concurrency: + group: deploy-${{ github.head_ref || github.ref }} + cancel-in-progress: true + +env: + DOMAIN: ${{ github.event.pull_request.base.repo.name }}-PR-${{ github.event.number }}.cleverapps.io/developers + +jobs: + review-app: + name: Review application + runs-on: ubuntu-latest + permissions: + contents: read + issues: write + pull-requests: write + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + ref: ${{ github.event.pull_request.head.sha }} + + - name: Deploy on Clever Cloud + uses: CleverCloud/clever-cloud-review-app@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + CLEVER_SECRET: ${{ secrets.CLEVER_SECRET }} + CLEVER_TOKEN: ${{ secrets.CLEVER_TOKEN }} + ORGA_ID: ${{ secrets.ORGA_ID }} + GH_CC_HUGO_VERSION: 0.148 + GH_CC_STATIC_AUTOBUILD_OUTDIR: public/developers + GH_CC_WEBROOT: public + GH_SERVER_ERROR_PAGE_404: developers/404.html + with: + comment: true + set-env: true + type: static + domain: ${{ env.DOMAIN }} + + check-links: + name: Check links + runs-on: ubuntu-latest + needs: review-app + if: github.event.action != 'closed' + permissions: + contents: read + + steps: + - name: Check links + run: | + pipx run linkchecker \ + --no-warnings \ + --no-status \ + --check-extern \ + --user-agent 'Mozilla/5.0 (X11; Linux i686; rv:137.0) Gecko/20100101 Firefox/137.0' \ + --ignore-url 'https://crates.io/crates' \ + --ignore-url 'https://new.drupal.org' \ + --ignore-url 'https://static-web-server.net' \ + --ignore-url 'https://www.clevercloudstatus.com' \ + 'https://${{ env.DOMAIN }}' || echo "::warning title=Broken Links::Some links are broken. Check the logs for details" diff --git a/.github/workflows/external-doc-update.yml b/.github/workflows/external-doc-update.yml new file mode 100644 index 000000000..8038ed2fe --- /dev/null +++ b/.github/workflows/external-doc-update.yml @@ -0,0 +1,67 @@ +name: Update external doc? + +on: + pull_request: + types: [opened, synchronize] + branches: [ main ] + +jobs: + changed_files: + runs-on: ubuntu-latest + name: Test changed-files + environment: update doc + # Needed to post comments and create issues + permissions: + issues: write + pull-requests: write + contents: read + steps: + - uses: actions/checkout@v4 + if: ${{ github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'synchronize' }} + with: + repository: ${{ github.event.pull_request.head.repo.full_name }} + ref: ${{ github.event.pull_request.head.ref }} + token: ${{ secrets.GITHUB_TOKEN }} + fetch-depth: 0 + + # Check if any external doc needs an update + - name: Get files linked to external doc + id: changed-files-specific + uses: tj-actions/changed-files@v45 + with: + files: | + content/guides/astro.md + context/guides/nuxt.md + + # Create issue and assign PR author + - name: Create issue + id: create-issue + if: steps.changed-files-specific.outputs.any_changed == 'true' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_URL: ${{ github.event.pull_request.html_url }} + PR_NUMBER: ${{ github.event.number }} + CHANGED_FILES: ${{ steps.changed-files-specific.outputs.all_changed_files }} + uses: JasonEtco/create-an-issue@v2 + with: + filename: .github/external-doc-issue.yml + assignees: ${{ github.event.pull_request.user.login }} + update_existing: true + search_existing: all + + # Post a single comment with auto-updating body + #- name: Create or update a comment + # env: + # CHANGED_FILES: ${{ steps.changed-files-specific.outputs.all_changed_files }} + # uses: taoliujun/action-unique-comment@v1 + # with: + # uniqueIdentifier: ${{ github.workflow }} + # body: | + # You updated ${{ env.CHANGED_FILES }}. This content is also listed on external doc. Issue number ${{ steps.create-issue.outputs.number }} has been created and assigned to you 🫵👁️👄👁️ + # + # See it or modify it here: + # * ${{ steps.create-issue.outputs.url }} + # + # _This unique comment uses the very cool [taoliujun/action-unique-comment](https://github.com/marketplace/actions/unique-comment). Thank you <3_ + + diff --git a/.github/workflows/styles-review.yml b/.github/workflows/styles-review.yml new file mode 100644 index 000000000..7e8a4c182 --- /dev/null +++ b/.github/workflows/styles-review.yml @@ -0,0 +1,15 @@ +name: Check editorial style +on: [pull_request] + +jobs: + vale: + name: Run Vale Linter + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: errata-ai/vale-action@reviewdog + with: + reporter: github-pr-check # How results are reported + filter_mode: added # Consider only changes in the modified or added lines + fail_on_error: false # Fail the action if errors are found + token: ${{ secrets.GITHUB_TOKEN }} # Post review diff --git a/.gitignore b/.gitignore index e43b0f988..895caa6b2 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,17 @@ +# System files +**/.DS_Store .DS_Store +Thumbs.db + +# Configuration files +.clever.json +.vale.ini + +# Build/cache files/folders +/.hugo_build.lock +/public/ +/resources/ + +# IDEs/Editors +/.idea/ +.vscode/ diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 000000000..c2c88abe7 --- /dev/null +++ b/.gitlab-ci.yml @@ -0,0 +1,7 @@ +include: + - component: $CI_SERVER_HOST/pipelines/clever-cloud-pipeline/deploy-to-prod@~latest + inputs: + stage: deploy + when: always + + diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc new file mode 100644 index 000000000..22de7da50 --- /dev/null +++ b/.markdownlint.jsonc @@ -0,0 +1,16 @@ +{ + "MD041": false, + "MD013": false, + "MD051": false, + "MD029": false, + // MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.32.1/doc/md033.md + "MD033": { + // Allowed elements + "allowed_elements": [ + "br", + "cc-smart-container", + "cc-pricing-product", + "cite" + ] + } +} \ No newline at end of file diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 000000000..ab4b6d49a --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,2 @@ +/public/* +/resources diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 000000000..ebc876a2e --- /dev/null +++ b/.vale.ini @@ -0,0 +1,17 @@ +StylesPath = .github/styles + +Vocab = Doc + +MinAlertLevel = suggestion + +Packages = Hugo, Google + +[*.md] +BasedOnStyles = Clever, Vale, Google, Guides +Google.Headings = NO +Vale.Terms = NO +Google.Parens = NO +Google.Ellipses = NO + +[*.xml] +Transform = docbook-xsl-snapshot/html/docbook.xsl \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..71c384682 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,83 @@ + +# Contributing guidelines + +This document provides explicit standards expected in Clever Cloud documentation. Inspiration and research for this document comes from the incredible [Awesome Code Review](https://github.com/joho/awesome-code-review) project. You'll find instructions for AI tools and LLMs: + +- [AI tools and LLMs instructions](./.cursorrules) + +## Standards + +Those are general standards to fulfill for every modification in this repository. + +### 🏯 Structure + +The structure of this docs aims to be as clear as possible for Clever Cloud users. Submitted changes can be merged as long as they respect these standards: + +- Readers know where to go or where to click to find an information +- Readers know why they're on a specific page +- The site keeps a coherent and [intuitive design](https://www.figma.com/fr/resource-library/ui-design-principles/) + +Follow the established structure in this doc. If you wish to propose changes to the structure, open an issue first to discuss it, or post it in the forum. + +### ✒️ Content + +Follow these guidelines while writing new content. The goal is to help you write in a **clear, precise, and unambiguous language**. They're not meant to be a burden, but to help you deliver the best content possible. + +Sources for quality content are currently being updated. + +#### 👍 Do + +- **Don't assume the user "knows better":** if you think something is obvious, it's not. Better over-explain than under-explain. +- **Use active voice:** passive voice can make it harder for the readers to figure out who's supposed to do something. +- **Use second person:** address the reader directly. +- **Keep it simple:** avoid jargon, complex sentences, and jokes. +- **Keep it short:** keep the sentences short. Titles should be short and to the point. Keep longer content for the description metadata or the card subtitle. + +#### 👎 Don't + +- Placeholder phrases like _please note_ and _at this time_. +- Words and phrases that make promises or project plans and strategies: See [Writing timeless documentation](https://developers.google.com/style/timeless-documentation). +- Using phrases like _simply_, _It's that simple_, _It's easy_, or _quickly_ in a procedure. +- Over-politeness with the use of _please_: go straight to the point. + +#### 💡 Shortcodes + +This doc uses Hugo with [Hextra theme](https://imfing.github.io/hextra/), which provides a variety of [shortcodes](https://imfing.github.io/hextra/docs/guide/shortcodes/) to enhance it and improve its readability. +For example : + +- [Steps](https://imfing.github.io/hextra/docs/guide/shortcodes/steps/) are well suited for the `/guides/` section, or for any tutorial. +- [Callouts](https://imfing.github.io/hextra/docs/guide/shortcodes/callout/) draw attention to an important information in the page. However, don't overuse them, as too many callouts can miss their point and make the page crowded. Limit callouts to one or two per page. + +### 💅 Style guide + +- Don't override global styles for font type, size, or color +- Comment your code if you add any custom CSS +- When importing from an external CSS tool, import the relevant classes only rather than the whole file +- Opt for self hosting over CDN: When used in ``, it can impact site's performance. Using CDN for test purposes when submitting your PR and deploying a review app is totally fine, however. + +## 🫶 Pull requests + +These are the guidelines when submitting or reviewing a PR in this repository. The better you follow them, the faster the is the review process. + +### 🚨 Priority + +Priority goes to PRs that reference a problem addressed in an issue fitting the current milestone, or that fix a bug. But that doesn't mean that you can't submit or review a PR that doesn't fit those criteria if you think it's important. If you think it's important, it probably is. + +### 🫡 When submitting a PR + +- **Keep it small:** The quality of the review is inversely proportional to the size of the PR. Smaller PRs simplify the reviewing process and increase the chances of getting constructive feedback. +- **Accept the feedback:** If reviewers ask you to make changes, do it. If you disagree, explain why. If you aren't sure, ask for clarification. Don't nitpick on the feedback, and don't take it personally. + +### 🥸 When reviewing a PR + +- **Latency:** Long PR review latency can be disappointing for the authors, and make merge conflicts arise in their branch. Long latency kills productivity and morale, so make sure to review PRs in a timely manner. +- **Don't nitpick:** If the PR respects the preceding standards and provide updated content, don't ask for changes just for the sake of it. If you think something isn't perfect, but it's not a big deal, don't ask for changes. +- **Provide alternatives:** If you think the author needs to change something, provide an example to illustrate your point. Use the `suggestion` feature on GitHub so the author can commit it directly if they agree with it. +- **It's OK to make mistakes:** Explain what's wrong, why, and how to improve. If someone is violating a standard, refer to this doc to explain. + +## 💡☁️ Contributing as a Clever Cloud employee + +If you are a member of Clever Cloud, act like you were submitting a PR and receiving feedback in any other Open Source project. This means: + +- **Don't bring internal company debates into the PR Discussion:** If conflict arises, take it to a private channel or in-person discussion. Pair-programming is a great way to solve conflicts together, consider it. +- **Don't use authority or seniority to push your PRs:** If you are a senior, your PRs aren't more important than others. If you are a junior, your PRs aren't less important than others. No one cares who you are, just the work you've done on this PR, and the fact you are willing to contribute to this doc is already highly appreciated. diff --git a/README.md b/README.md index 529353d00..a260b9747 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,204 @@ # Clever Cloud Documentation -In this repo you will find all the content from the [Clever Cloud Doc](https://www.clever-cloud.com/doc/). +This project is based on [Hugo](https://gohugo.io/) and uses [Hextra](https://imfing.github.io/hextra/) theme. It provides a great design, a responsive layout, dark mode support, full-text search. It's lightweight, fast, and SEO-ready, with many built-in features: -As this documentation is open for content contribution, any helpful pull-request will be merged. +- [Complete Markdown support](https://imfing.github.io/hextra/docs/guide/markdown/) +- [Complete shortcodes set](https://imfing.github.io/hextra/docs/guide/shortcodes/) +- [Diagrams](https://imfing.github.io/hextra/docs/guide/diagrams/) +- [LaTeX math formulae](https://imfing.github.io/hextra/docs/guide/latex/) +- [Syntax highlighting](https://imfing.github.io/hextra/docs/guide/syntax-highlighting/) -## Example of Relevant Topics +## See deployed Documentation -1. Text of schematic content improvements -2. Grammar or orthograph improvements -3. Any revelant pieces of infos from our mail support -4. Tutorials to setup a supported technology/framework. +- [Home page](https://www.clever.cloud/developers/) +- [Documentation](https://www.clever.cloud/developers/doc/) +- [API Documentation](https://www.clever.cloud/developers/api/) +- [Guides and Tutorials](https://www.clever.cloud/developers/guides/) +- [Reference Clever Tools CLI](https://www.clever.cloud/developers/doc/reference/cli/) +- [Reference Environment Variables](https://www.clever.cloud/developers/doc/reference/reference-environment-variables/) +- [Clever Cloud Platform Changelog](https://www.clever.cloud/developers/changelog/) -## Contributing Process +## Quickstart -You can either make a [pull-request](https://github.com/CleverCloud/doc.clever-cloud.com/pulls) OR submit a content via the **Contribute** button here: https://www.clever-cloud.com/doc +### Install Hugo -## Licence +To begin your journey with the Clever Cloud Documentation, you need Hugo. You can: +- [Install it](https://gohugo.io/installation/) globally on your system +- Get its [binary](https://github.com/gohugoio/hugo/releases) and put it in the project's root -Clever Cloud Doc by Clever Cloud is licensed under a Creative Commons Attribution 4.0 International License. -Based on a work at [https://www.clever-cloud.com/doc](https://www.clever-cloud.com/doc/). +### Clone the project, preview locally -Creative Commons License \ No newline at end of file +Once your system is set up, clone this repository: + +```bash +git clone https://github.com/CleverCloud/documentation +``` + +Then: + +1. Go to the documentation folder: `cd documentation` +2. Run `hugo server` to build and start the local server + +Local site is available on , it refreshes as you modify the files, you can keep the server running with no need to restart. +Find `server` command options in the [Hugo documentation](https://gohugo.io/commands/hugo_server/#options). + +## Deploying on Clever Cloud + +As Clever Cloud [natively detects and build Hugo sites](https://www.clever.cloud/developers/doc/applications/static/), you just need some configuration to deploy this project: + +```bash +# Declare what's the web server root, where to build the documentation +# You must have a `/developers` at the end of your application's route +CC_WEBROOT="public" +CC_STATIC_AUTOBUILD_OUTDIR="public/developers" + +# Declare the location of the 404 custom page +SERVER_ERROR_PAGE_404="developers/404.html" +``` + +> [!TIP] +> You can set the Hugo version with `CC_HUGO_VERSION` with a value like `0.148` + +## Contributing + +You can contribute by [creating an issue](https://github.com/CleverCloud/documentation/issues) or [submitting a pull request](https://github.com/CleverCloud/documentation/pulls). If you use AI tools or LLMs, you'll find specific instructions for them: + +- [Contributing guidelines](./CONTRIBUTING.md) +- [AI tools and LLMs instructions](./.cursorrules) + +Clever Cloud documentation is also available following the [llms.txt specification](https://www.clever.cloud/developers/llms.txt). + +## Adding a new page or guide + +To generates a file from a template (in `/archetypes`), run one of the following Hugo commands: + +```bash +hugo new content guides/.md +hugo new content/doc/administrate/.md +hugo new content --kind applications doc/applications/.md +``` + +In new page/guide front matter, `draft` is set to `true` to prevent it from being mistakenly published. + +> [!TIP] +> Use `hugo server --buildDrafts` command to preview drafts locally + +### Adding a changelog entry (internal only) + +For any significant change to the platform (updates, new features, etc.) a new entry is created in the `content/changelog` folder. + +Several entries can be made per day, it's not a problem. Each entry should provide clear, straightforward information on the essentials. If you find yourself writing an enormous amount of content, this may not be the right approach. However, you can always add a little charm to your changelog, but it's a tricky business, requiring careful, well-placed word choice. + +The filename format is a markdown file with a `.md` extension: + +``` +yyyy-mm-dd-your-title.md +``` + +### Front matter configuration + +Hugo uses front matter to enrich posts with metadata. Front matter allows you to keep metadata attached to an instance of a content type—i.e., embedded inside a content file. We use the following Front matter variables: + +- [`type`](https://gohugo.io/methods/page/type/) (optional) + - The type of content layout to apply. The value is a ``, set it to `docs` except in changelog. + +- [`weight`](https://gohugo.io/methods/page/weight/) (optional) + - The weight of the content, used to order the sidebar. The value is an ``, default is `0`. + +- [`linkTitle`](https://gohugo.io/methods/page/linktitle/) (optional) + - The title of the content displayed in the sidebar. The value is a ``, default is the `title` value. + +- [`title`](https://gohugo.io/methods/page/title/) (required) + - The title displayed in the main heading. The value is a ``. + +- [`description`](https://gohugo.io/methods/page/description/) (recommended) + - The description displayed in meta-description for SEO purposes. The value is a ``. + +- [`excludeSearch`](https://imfing.github.io/hextra/docs/guide/configuration/#search-index) (optional) + - Indicates whether the page should be indexed in search. Default is `false`, we recommend setting it to `true` for changelog entries. + +- [aliases](https://gohugo.io/methods/page/aliases) (optional) + - Aliases redirects the user to the right page. The value is a list of ``, each string being a path to redirect from, relative to the base URL (without the `/developer`, for example: `/doc/docker`). + +- [comments](https://gohugo.io/content-management/comments/) (optional) + - Whether to show the feedback block or not. The value is a ``, default is `true`. + +- [`draft`](https://gohugo.io/methods/page/draft/) (optional) + - Whether the page is a draft or not. The value is a ``, default is `false`. If set to `true`, the page is not built except if you use the `--buildDrafts` flag. + +- [`tags`](https://gohugo.io/content-management/taxonomies/#default-taxonomies) (recommended) + - Tags are recommended for easy product identification. They are written in lowercase and, if possible, use the same spelling throughout the posts. The value is a ``. + +- [`authors`](https://gohugo.io/content-management/taxonomies/#default-taxonomies) (mostly used in changelog) + - Can be set to showcase the people behind the product. Authors are defined with a `name`, `link` for their Github or any other social network, and an `image` for the profile picture. The profile picture can be set with the GitHub avatar with a link like `https://github.com/BlackYoup.png` and the parameter `?size=40` for reducing the image size (recommended for performance). The values are all of `` type. + +- [`category`](https://gohugo.io/content-management/taxonomies/#default-taxonomies) (optional) + - The category is used here to add a "new" label on the changelog homepage when a specific entry is a new feature that should be highlighted visually. The value must be `new`, and nothing else. + +- [`date`](https://gohugo.io/methods/page/date/) (mostly used in changelog) + - The date that will be displayed in the post. The value is a string in ISO 8601 like `yyyy-mm-dd`. + +For example, a changelog entry front matter could look like this: + +```yaml +--- +title: Redis updated to v7.2.4 +description: Redis has been updated to v7.2.4 mostly to prevent security issues +date: 2024-01-11 +tags: + - redis +authors: + - name: BlackYoup + link: https://github.com/BlackYoup + image: https://github.com/BlackYoup.png?size=40 +excludeSearch: true +--- +``` + +### Adding an image + +Adding an image can be useful to highlight an interface change, for example. Use such markdown syntax for that: + +```markdown +![Alt text](/images/your-image.jpg "Title of the image") +``` + +If needed, you can also use [the `figure` shortcode](https://gohugo.io/shortcodes/figure/) to add attributes such as a width limit: + +```markdown +{{< figure src="/developers/images/your-image.jpg" alt="Alt text" title="Title of the image" width="800px">}} +``` + +- [Learn more about Hugo shortcodes](https://gohugo.io/shortcodes/) + +### Adding a new shared content + +You can include shared content in several pages. To use this feature: + +1. Create a new markdown file in `/shared` +2. Add it to the relevant pages with: `{{% content "your-partial" %}}` + +> [!TIP] +> If you need to include a shared content including shortcodes, use `{{% content-raw "your-partial" %}}` instead. Don't include headings (starting with `#`) in it as they won't be rendered in the page Table of Contents (ToC). + +## Tooltips + +Tooltips are useful to provide additional information on terms or acronyms that may not be familiar to all readers. They help improve the accessibility and comprehension of your documentation without cluttering the main text. + +To create a tooltip, add the term and its associated tooltip definition in the [`data/tooltips.toml`](./data/tooltips.toml) file. Once defined, tooltips automatically display when users hover over associated terms in the documentation. + +## Markdown Linting + +Hugo uses [Goldmark](https://github.com/yuin/goldmark), a Markdown parser written in Go, compliant with [CommonMark 0.30](https://spec.commonmark.org/). Therefore, for better readability and maintainability, all markdown files for this project are linted with [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2). We strongly recommend that you follow the validation rules described [here](https://github.com/DavidAnson/markdownlint#rules--aliases). + +This linter can be downloaded and run locally, or used via Visual Studio Code: + +- for Visual Studio Code +- as a `npm` package + +**Ignored markdown files** are listed in the `.markdownlintignore`. +**Ignored specifications**, such as some HTML tag of Web Components, are configured in the `.markdownlint.jsonc` + +## Editorial checks + +This project uses [Vale.sh](https://vale.sh) to run editorial checks on the documentation. Install Vale on your machine or as an IDE extension if you want to run checks. This project is already configured to use it on pull requests. diff --git a/archetypes/applications.md b/archetypes/applications.md new file mode 100644 index 000000000..56d4b605f --- /dev/null +++ b/archetypes/applications.md @@ -0,0 +1,49 @@ +--- +type: docs +title: '{{ replace .File.ContentBaseName "-" " " | title }}' +linkTitle: +description: +tags: +keywords: +draft: true +--- + +## Overview + +## Create your XXX application + +To create a new XXX application, use the [Clever Cloud Console](https://console.clever-cloud.com) or [Clever Tools](https://github.com/CleverCloud/clever-tools): + +```bash +clever create --type XXX +``` +* [Learn more about Clever Tools](/developers/doc/cli/) +* [Learn more about Clever Cloud application deployment](/developers/doc/quickstart/#create-an-application-step-by-step) + +## Configure your XXX application + +### Mandatory needs + +XXX runtime only requires a working application listening on `0.0.0.0:8080`. + +* [Learn more about environment variables on Clever Cloud](/developers/doc/reference/reference-environment-variables/) + +### Build phase + +During the build phase, + +- [Learn more about Deployment hooks](/developers/doc/develop/build-hooks/) + +### XXX version + + + +## Clever Tasks + + +```bash +clever create --type XXX --task "XXX" +clever deploy # or clever restart if there is no code change +``` + +- [Learn more about Clever Tasks](/developers/doc/develop/tasks/) diff --git a/archetypes/default.md b/archetypes/default.md new file mode 100644 index 000000000..2cee817ec --- /dev/null +++ b/archetypes/default.md @@ -0,0 +1,13 @@ +--- +type: docs +title: '{{ replace .File.ContentBaseName "-" " " | title }}' +linkTitle: +description: +tags: +keywords: +draft: true +--- + +{{< hextra/hero-subtitle >}} + Page short description. +{{< /hextra/hero-subtitle >}} diff --git a/archetypes/guides.md b/archetypes/guides.md new file mode 100644 index 000000000..9cc1ecef5 --- /dev/null +++ b/archetypes/guides.md @@ -0,0 +1,31 @@ +--- +type: docs +title: '{{ replace .File.ContentBaseName "-" " " | title }}' +linkTitle: +description: +tags: +- guides +keywords: +- +draft: true +--- + +{{< hextra/hero-subtitle >}} + Framework short description. +{{< /hextra/hero-subtitle >}} + +## How to Configure and Deploy [...] on Clever Cloud + +{{% steps %}} + +### + +### + +{{% /steps %}} + +## 🎓 Further Help + +{{< cards >}} + {{< card link="/developers/guides/" title="Card title" subtitle="Card subtiltle" icon="adjustments-horizontal" >}} +{{< /cards >}} \ No newline at end of file diff --git a/assets/css/custom.css b/assets/css/custom.css new file mode 100644 index 000000000..ebdefdcac --- /dev/null +++ b/assets/css/custom.css @@ -0,0 +1,241 @@ +/* ----------------------------------------------- + This code is overriding default theme + configuration and classes +-------------------------------------------------*/ + +/* ----------------------------------------- + Fonts and typography +------------------------------------------*/ +@font-face { + font-family: 'Plus Jakarta Sans'; + font-weight: 700; + src: url('/developers/fonts/plus-jakarta-sans-v8-latin-700.woff2') format('woff2'), /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */ + url('/developers/fonts/plus-jakarta-sans-v8-latin-700.ttf') format('truetype'); /* Chrome 4+, Firefox 3.5+, IE 9+, Safari 3.1+, iOS 4.2+, Android Browser 2.2+ */ +} + +:root { + --red-color: rgb(203, 28, 66); + --blue-color: rgb(0, 172, 230); + --purple-color: rgb(58, 56, 113); + --dark-background-color: rgba(227, 210, 210, 0); +} + +h1, .content h1, +.content h2, +.content h3, +.content h3 { + font-family: 'Plus Jakarta Sans', sans-serif; +} + +.highlight .chroma .err { + color: var(--red-color); + background-color: var(--dark-background-color); +} + +html:not([class~="dark"]) .sidebar-active-item { + background-color: rgb(224, 227, 255) !important; + color: rgb(0, 14, 163) !important; +} + +/* Override border-radius class to fit Clever's theme */ +.btn-secondary, +.btn-primary, +.chroma .lntable, +.content img, +.hx-rounded-xl, +.hx-rounded-3xl { + border-radius: 0rem; +} + +/* ----------------------------- + Shortcodes +----------------------------- */ + +/* Hero buttons on home page */ +.btn-primary { + background-color: var(--purple-color); + text-decoration: none; +} + +.btn-primary:hover, .btn-secondary:hover { + background-color: var(--red-color); + color: white; +} + +/* Steps +Allow inserting "steps" shortcode with h4 */ +.steps h4 { + counter-increment: step; +} + +.steps h4:before,.steps h3:before { + position: absolute; + height: 33px; + width: 33px; + border-width: 4px; + --tw-border-opacity: 1; + border-radius: 9999px; + border-color: var(--purple-color); + background-color: var(--purple-color); + text-align: center; + font-size: 1rem; + font-weight:700; + --tw-text-opacity: 1; + color: white; + margin-top: -1px; + margin-left: -41px; + content: counter(step); + } + + .steps h3:before{ + margin-top:2px + } + +.steps h4,.steps h3{ + font-family: inherit; +} + +:is(html[class~="dark"] .steps h4):before,:is(html[class~="dark"] .steps h3):before { + --tw-border-opacity: 1; + border-color: rgb(38 38 38 / var(--tw-border-opacity)); + --tw-bg-opacity: 1; + background-color: rgb(38 38 38 / var(--tw-bg-opacity)); +} + +/* -------------- + Links +--------------- */ + +/* Custom link color. +This will be applied also to code (except in tables): +selectors in css can't be grained to target Markdown syntax +(for now) */ +html[class~="dark"] .content p a, +html[class~="dark"] article .content p a, +html[class~="dark"] article .content div a:not(.hextra-feature-card) , +html[class~="dark"] article .content li a { + color: var(--blue-color); + text-decoration-style: dotted; +} + +html[class~="dark"] button[data-state="selected"], +html[class~="dark"] .sidebar-active-item { + color: var(--blue-color) !important; +} + +article .content a:hover:not(.hextra-feature-card), +article main h4 a:hover { + color: var(--red-color) !important; + text-decoration-style: dotted; +} + +/* Don't change the style for an inline code within a link +Mostly used in environment variables table */ +.content a:has(code){ + text-decoration: none; + color: inherit; +} + +/* Display an arrow at the end of the linked inline code */ +.content a:not(.code-block code) code::after { + content: "\00a0↗"; + color: tomato; + font-size: 1rem; + bottom: -2px; + position: relative; + left: 4px; + width: 14px; + display: inline-block; + height: 14px; + line-height: 0.35em; +} + +/* --------------- + Tables +--------------- */ + +/* Table headers formatting */ +.content table:not(.code-block table) th { + border-right-width: 0px; + border-left-width: 0px; + border-top: none; + text-transform: uppercase; + color: rgba(115, 115, 142, 1); +} + +/* Table headers formatting for dark mode */ +html[class~="dark"] .content table:not(.code-block table) th { + color: rgb(193, 193, 196); +} + +/* Remove most of the borders */ +.content table:not(.code-block table) td { + margin: 0px; + border-width: 0px; + --tw-border-opacity: 0; +} + +/* Text in cells */ +.content table:not(.code-block table) tr { + font-size: 0.9rem; + border-width: 0px; +} + +/* --------------------------------------- + Animation for 404 page +--------------------------------------- */ +.animate__headShake { + -webkit-animation-timing-function: ease-in-out; + animation-timing-function: ease-in-out; + -webkit-animation-name: headShake; + animation-name:headShake +} +.animate__animated { + -webkit-animation-duration: 1s; + animation-duration: 1s; + -webkit-animation-duration: 1s; + animation-duration: 1s; + -webkit-animation-fill-mode: both; + animation-fill-mode: both; +} + +@keyframes headShake { + 0% { + -webkit-transform: translateX(0); + transform:translateX(0) + } + + 6.5% { + -webkit-transform: translateX(-6px) rotateY(-9deg); + transform:translateX(-6px) rotateY(-9deg) + } + + 18.5% { + -webkit-transform: translateX(5px) rotateY(7deg); + transform:translateX(5px) rotateY(7deg) + } + + 31.5% { + -webkit-transform: translateX(-3px) rotateY(-5deg); + transform:translateX(-3px) rotateY(-5deg) + } + + 43.5% { + -webkit-transform: translateX(2px) rotateY(3deg); + transform:translateX(2px) rotateY(3deg) + } + + 50% { + -webkit-transform: translateX(0); + transform:translateX(0) + } +} + +/* ------------------------- + Changelog +------------------------- */ + +/* Entries listing--*/ +.hx-pl-5 { + padding-left: 1.25rem; +} diff --git a/assets/css/docsearch.css b/assets/css/docsearch.css new file mode 100644 index 000000000..d09d77659 --- /dev/null +++ b/assets/css/docsearch.css @@ -0,0 +1,548 @@ +/* Algolia DocSearch integration with Clever Cloud theme consistency */ + +/* Hide theme's built-in search UI content and show DocSearch in its place */ +.search-wrapper input, +.search-wrapper form, +.search-wrapper .hextra-search, +.search-wrapper .flexsearch-wrapper { + display: none !important; +} + +.search-wrapper { + position: relative; +} + +#docsearch { + position: static; + width: auto; + height: auto; + overflow: visible; + display: inline-block; +} + +/* DocSearch button styling using Hextra theme variables */ +#docsearch .DocSearch-Button { + opacity: 1; + pointer-events: auto; + border-radius: var(--hx-radius-md); /* Use theme's radius */ + padding: calc(var(--hx-spacing) * 2) calc(var(--hx-spacing) * 3); + line-height: var(--hx-leading-tight); + font-family: var(--hx-default-font-family); + font-size: var(--hx-text-sm); + font-weight: var(--hx-font-weight-medium); + transition: all var(--hx-default-transition-duration) var(--hx-default-transition-timing-function); + min-width: 200px; + justify-content: flex-start; +} + +/* Light theme styling - better contrast */ +:root:not(.dark) #docsearch .DocSearch-Button { + background-color: var(--hx-color-white); + color: var(--hx-color-gray-700); + border: 1px solid var(--hx-color-gray-300); + box-shadow: var(--hx-shadow-sm); +} + +/* Dark theme styling */ +.dark #docsearch .DocSearch-Button { + background-color: var(--hx-color-neutral-800); + color: var(--hx-color-gray-300); + border: 1px solid var(--hx-color-neutral-600); + box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.3); +} + +/* Focus states */ +#docsearch .DocSearch-Button:focus { + outline: none; + ring: 2px solid var(--hx-color-primary-500); +} + +:root:not(.dark) #docsearch .DocSearch-Button:focus { + border-color: var(--hx-color-primary-500); + box-shadow: 0 0 0 3px var(--hx-color-primary-100); +} + +.dark #docsearch .DocSearch-Button:focus { + border-color: var(--hx-color-primary-400); + box-shadow: 0 0 0 3px var(--hx-color-primary-900); +} + +/* Hover states */ +:root:not(.dark) #docsearch .DocSearch-Button:hover { + background-color: var(--hx-color-gray-50); + border-color: var(--hx-color-gray-400); + box-shadow: var(--hx-shadow-md); +} + +.dark #docsearch .DocSearch-Button:hover { + background-color: var(--hx-color-neutral-700); + border-color: var(--hx-color-neutral-500); +} + +/* Button placeholder text */ +.DocSearch-Button-Placeholder { + opacity: .7; + font-family: var(--hx-default-font-family); + font-size: var(--hx-text-sm); +} + +/* Search icon styling */ +#docsearch .DocSearch-Search-Icon { + width: 16px; + height: 16px; + color: var(--hx-color-gray-500); +} + +.dark #docsearch .DocSearch-Search-Icon { + color: var(--hx-color-gray-400); +} + +/* Keyboard shortcut styling */ +#docsearch .DocSearch-Button-Keys { + display: flex; + gap: 2px; +} + +#docsearch .DocSearch-Button-Key { + background: var(--hx-color-gray-100); + border: 1px solid var(--hx-color-gray-300); + border-radius: var(--hx-radius-sm); + color: var(--hx-color-gray-600); + font-size: 11px; + padding: 2px 6px; + font-family: var(--hx-font-mono); +} + +.dark #docsearch .DocSearch-Button-Key { + background: var(--hx-color-neutral-700); + border-color: var(--hx-color-neutral-600); + color: var(--hx-color-gray-300); +} + +/* Modal styling with Hextra theme consistency - Reduced size */ +.DocSearch-Container { + z-index: 200; /* Ensure it appears above everything */ +} + +.DocSearch-Container .DocSearch-Modal { + max-width: 600px; /* Reduced from 6xl to a more manageable size */ + width: 90vw; + max-height: 70vh; /* Limit height to prevent taking too much space */ + background-color: var(--hx-color-white); + border: 1px solid var(--hx-color-gray-200); + box-shadow: var(--hx-shadow-xl); + border-radius: var(--hx-radius-lg); + margin: 10vh auto; /* Center with reasonable top margin */ +} + +.dark .DocSearch-Container .DocSearch-Modal { + background-color: var(--hx-color-neutral-900); + border-color: var(--hx-color-neutral-700); + box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.5); +} + +@media (max-width: 768px) { + .DocSearch-Container .DocSearch-Modal { + max-width: 95vw; + max-height: 80vh; + margin: 5vh auto; + } +} + +/* Form elements with Hextra styling */ +.DocSearch-Form { + border: 1px solid var(--hx-color-gray-300); + border-radius: var(--hx-radius-md); + background-color: var(--hx-color-white); + box-shadow: none; +} + +.dark .DocSearch-Form { + border-color: var(--hx-color-neutral-600); + background-color: var(--hx-color-neutral-800); +} + +.DocSearch-Input { + color: var(--hx-color-gray-900); + font-size: var(--hx-text-base); + font-family: var(--hx-default-font-family); + background: transparent; +} + +.dark .DocSearch-Input { + color: var(--hx-color-gray-100); +} + +.DocSearch-Input::placeholder { + color: var(--hx-color-gray-500); +} + +.dark .DocSearch-Input::placeholder { + color: var(--hx-color-gray-400); +} + + +/* Search results container - pure white/black backgrounds by theme */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown { + max-height: 400px !important; /* Limit results height */ + overflow-y: auto !important; + background-color: white !important; + border-radius: var(--hx-radius-md) !important; + padding: 0 !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown { + background-color: black !important; +} + +/* Individual search result styling - pure white/black backgrounds */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown .DocSearch-Hits .DocSearch-Hit { + border-radius: var(--hx-radius-sm) !important; + margin-bottom: 1px !important; + background-color: white !important; + border: none !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown .DocSearch-Hits .DocSearch-Hit { + background-color: black !important; +} + +.DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown .DocSearch-Hits .DocSearch-Hit a { + padding: 12px 16px !important; + border-radius: var(--hx-radius-sm) !important; + color: black !important; + background-color: white !important; + display: block !important; + text-decoration: none !important; + transition: all var(--hx-default-transition-duration) var(--hx-default-transition-timing-function) !important; + border: none !important; + box-shadow: none !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown .DocSearch-Hits .DocSearch-Hit a { + color: white !important; + background-color: black !important; +} + +/* Hover state for results - Better contrast */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown .DocSearch-Hits .DocSearch-Hit a:hover { + background-color: var(--hx-color-gray-50) !important; + color: var(--hx-color-gray-900) !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown .DocSearch-Hits .DocSearch-Hit a:hover { + background-color: var(--hx-color-neutral-700) !important; + color: var(--hx-color-gray-50) !important; +} + +/* Selected/highlighted result - Better contrast */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown .DocSearch-Hits .DocSearch-Hit[aria-selected="true"] a { + background-color: var(--hx-color-primary-50) !important; + color: var(--hx-color-primary-900) !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown .DocSearch-Hits .DocSearch-Hit[aria-selected="true"] a { + background-color: var(--hx-color-primary-800) !important; + color: var(--hx-color-primary-50) !important; +} + +/* Result content wrapper - Force inheritance */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Hit-Container { + background-color: inherit !important; +} + +/* Result titles and text - pure black/white text */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Hit-Title { + color: black !important; + font-weight: var(--hx-font-weight-medium) !important; + font-family: var(--hx-default-font-family) !important; + margin-bottom: 4px !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Hit-Title { + color: white !important; +} + +.DocSearch-Container .DocSearch-Modal .DocSearch-Hit-Path { + color: #666666 !important; + font-size: var(--hx-text-sm) !important; + font-family: var(--hx-default-font-family) !important; + opacity: 1 !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Hit-Path { + color: #cccccc !important; +} + +.DocSearch-Container .DocSearch-Modal .DocSearch-Hit-Text { + color: #333333 !important; + font-size: var(--hx-text-sm) !important; + font-family: var(--hx-default-font-family) !important; + line-height: 1.4 !important; + margin-top: 4px !important; + opacity: 1 !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Hit-Text { + color: #dddddd !important; +} + +/* Search term highlights - Force styling */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Hit mark { + background-color: var(--hx-color-yellow-100) !important; + color: var(--hx-color-yellow-900) !important; + font-weight: var(--hx-font-weight-semibold) !important; + padding: 1px 2px !important; + border-radius: 2px !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Hit mark { + background-color: var(--hx-color-yellow-700) !important; + color: var(--hx-color-yellow-200) !important; +} + + +/* Hit icons */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Hit-icon { + color: var(--hx-color-gray-500) !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Hit-icon { + color: var(--hx-color-gray-400) !important; +} + +/* Hit action (tree/hierarchy indicator) */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Hit-action { + color: var(--hx-color-gray-400) !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Hit-action { + color: var(--hx-color-gray-500) !important; +} + +/* Results list container - pure white/black backgrounds */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown .DocSearch-Hits { + background-color: white !important; + padding: 4px !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Dropdown .DocSearch-Hits { + background-color: black !important; +} + +/* Section headers spacing - Better visual separation */ +.DocSearch-Container .DocSearch-Modal .DocSearch-Hit-source { + background-color: var(--hx-color-gray-50) !important; + color: var(--hx-color-gray-800) !important; + font-size: var(--hx-text-xs) !important; + font-weight: var(--hx-font-weight-semibold) !important; + text-transform: uppercase !important; + letter-spacing: 0.05em !important; + padding: 6px 16px !important; + border-radius: 0 !important; + margin: 8px 0 4px 0 !important; + font-family: var(--hx-default-font-family) !important; + border-bottom: 1px solid var(--hx-color-gray-200) !important; +} + +.dark .DocSearch-Container .DocSearch-Modal .DocSearch-Hit-source { + background-color: var(--hx-color-neutral-700) !important; + color: var(--hx-color-gray-100) !important; + border-bottom-color: var(--hx-color-neutral-600) !important; +} + +/* Remove Algolia branding elements */ +.DocSearch-Footer, +.DocSearch-Logo { + display: none; +} + +/* Action buttons styling */ +.DocSearch-Commands { + border-top: 1px solid var(--hx-color-gray-200); + background-color: var(--hx-color-gray-50); +} + +.dark .DocSearch-Commands { + border-top-color: var(--hx-color-neutral-700); + background-color: var(--hx-color-neutral-800); +} + +/* Cancel/reset button styling */ +.DocSearch-Cancel, +.DocSearch-Reset { + color: var(--hx-color-gray-600); + font-family: var(--hx-default-font-family); + border-radius: var(--hx-radius-sm); + padding: 4px 8px; +} + +.dark .DocSearch-Cancel, +.dark .DocSearch-Reset { + color: var(--hx-color-gray-400); +} + +.DocSearch-Reset:hover, +.DocSearch-Cancel:hover { + color: var(--hx-color-gray-900); + background-color: var(--hx-color-gray-100); +} + +.dark .DocSearch-Reset:hover, +.dark .DocSearch-Cancel:hover { + color: var(--hx-color-gray-100); + background-color: var(--hx-color-neutral-700); +} + +/* No results state */ +.DocSearch-NoResults { + text-align: center; + padding: 32px 16px; + color: var(--hx-color-gray-600); +} + +.dark .DocSearch-NoResults { + color: var(--hx-color-gray-400); +} + +/* Search icon in modal */ +.DocSearch-MagnifierLabel { + color: var(--hx-color-gray-500); +} + +.dark .DocSearch-MagnifierLabel { + color: var(--hx-color-gray-400); +} + +/* Scrollbar styling for dropdown */ +.DocSearch-Dropdown::-webkit-scrollbar { + width: 6px; +} + +.DocSearch-Dropdown::-webkit-scrollbar-track { + background: transparent; +} + +.DocSearch-Dropdown::-webkit-scrollbar-thumb { + background: var(--hx-color-gray-300); + border-radius: 3px; +} + +.dark .DocSearch-Dropdown::-webkit-scrollbar-thumb { + background: var(--hx-color-neutral-600); +} + +/* Additional fixes for remaining transparent/default elements */ + +/* Start screen / empty state */ +.DocSearch-StartScreen, +.DocSearch-EmptyResults { + background-color: var(--hx-color-white); + color: var(--hx-color-gray-700); + padding: 32px 16px; + text-align: center; +} + +.dark .DocSearch-StartScreen, +.dark .DocSearch-EmptyResults { + background-color: var(--hx-color-neutral-900); + color: var(--hx-color-gray-300); +} + +/* Error states */ +.DocSearch-ErrorScreen { + background-color: var(--hx-color-white); + color: var(--hx-color-red-600); + padding: 32px 16px; + text-align: center; +} + +.dark .DocSearch-ErrorScreen { + background-color: var(--hx-color-neutral-900); + color: var(--hx-color-red-400); +} + +/* Loading state */ +.DocSearch-LoadingIndicator { + color: var(--hx-color-primary-600) !important; +} + +.dark .DocSearch-LoadingIndicator { + color: var(--hx-color-primary-400) !important; +} + +/* Suggestion links in start screen */ +.DocSearch-Help { + color: var(--hx-color-gray-600) !important; + font-size: var(--hx-text-sm); + background-color: var(--hx-color-white); + padding: 16px; +} + +.dark .DocSearch-Help { + color: var(--hx-color-gray-400) !important; + background-color: var(--hx-color-neutral-900); +} + +/* Recent searches */ +.DocSearch-Title { + color: var(--hx-color-gray-900) !important; + font-weight: var(--hx-font-weight-medium); + font-family: var(--hx-default-font-family); +} + +.dark .DocSearch-Title { + color: var(--hx-color-gray-100) !important; +} + +/* Hit content wrapper - force inheritance */ +.DocSearch-Hit-Container, +.DocSearch-Hit-content { + background-color: inherit !important; +} + +/* Force all text elements to use theme colors */ +.DocSearch-Hit-Tree { + color: var(--hx-color-gray-500) !important; +} + +.dark .DocSearch-Hit-Tree { + color: var(--hx-color-gray-400) !important; +} + +/* Result separators */ +.DocSearch-Dropdown-Container::before { + background: var(--hx-color-gray-200); +} + +.dark .DocSearch-Dropdown-Container::before { + background: var(--hx-color-neutral-700); +} + +/* Override any remaining Algolia defaults that might cause transparency issues */ +.DocSearch-Container * { + box-sizing: border-box; +} + +/* Ensure proper background for all interactive elements */ +.DocSearch-Button-Container, +.DocSearch-Modal-Container { + background-color: inherit; +} + +/* Footer commands - ensure proper styling */ +.DocSearch-Commands-Key { + background-color: var(--hx-color-gray-100) !important; + border: 1px solid var(--hx-color-gray-300) !important; + color: var(--hx-color-gray-700) !important; + border-radius: var(--hx-radius-sm); + padding: 2px 6px; + font-family: var(--hx-font-mono); + font-size: 11px; +} + +.dark .DocSearch-Commands-Key { + background-color: var(--hx-color-neutral-700) !important; + border-color: var(--hx-color-neutral-600) !important; + color: var(--hx-color-gray-300) !important; +} \ No newline at end of file diff --git a/assets/js/docsearch.js b/assets/js/docsearch.js new file mode 100644 index 000000000..9c33f4ca5 --- /dev/null +++ b/assets/js/docsearch.js @@ -0,0 +1,241 @@ +(function() { + 'use strict'; + + function ready(fn) { + if (document.readyState !== 'loading') { + fn(); + } else { + document.addEventListener('DOMContentLoaded', fn); + } + } + + ready(function() { + // Ensure DocSearch container exists and place it inside the theme search wrapper + var containerId = 'docsearch'; + var container = document.getElementById(containerId); + if (!container) { + container = document.createElement('div'); + container.id = containerId; + var themeWrapper = document.querySelector('.search-wrapper'); + if (themeWrapper) { + // Place DocSearch inside the search wrapper + themeWrapper.appendChild(container); + } else { + // Fallback + var header = document.querySelector('header'); + if (header) { + header.appendChild(container); + } else { + document.body.appendChild(container); + } + } + } + + // Initialize DocSearch (wait if script not loaded yet) + var openDocSearch; + var initDocSearch = function() { + if (!window.docsearch) return false; + try { + var docSearchConfig = window.docSearchConfig || {}; + window.docsearch({ + appId: docSearchConfig.appId || '', + apiKey: docSearchConfig.apiKey || '', + indexName: docSearchConfig.indexName || '', + container: '#docsearch', + debug: false + }); + openDocSearch = function() { + var btn = document.querySelector('#docsearch .DocSearch-Button'); + if (btn) { + btn.click(); + } + }; + return true; + } catch (e) { + console.error('DocSearch initialization error:', e); + return false; + } + }; + + if (!initDocSearch()) { + var tries = 0; + (function waitForDocSearch(){ + if (initDocSearch()) return; + if (tries++ < 30) setTimeout(waitForDocSearch, 100); + })(); + } + + // Hook the existing theme Search input/button to open DocSearch with prefill + var tryAttach = function() { + var header = document.querySelector('header'); + var found = false; + + // 1) Buttons or anchors acting as search triggers + var btns = header ? header.querySelectorAll([ + 'button[aria-label="Search"]', + 'button[aria-label*="search" i]', + 'a[aria-label*="search" i]', + '.hx-search', + 'button[class*="search" i]', + 'a[class*="search" i]', + 'a[href="#search"]', + '[role="search"] button', + '[data-testid*="search" i]', + '[data-track*="search" i]' + ].join(',')) : []; + + btns.forEach(function(el){ + if (el.__ccDocSearchBound) return; + el.__ccDocSearchBound = true; + found = true; + el.addEventListener('click', function(ev){ + ev.preventDefault(); + if (openDocSearch) openDocSearch(); + }); + el.addEventListener('keydown', function(ev){ + if (ev.key === 'Enter' || ev.key === ' ') { + ev.preventDefault(); + if (openDocSearch) openDocSearch(); + } + }); + }); + + // 2) The actual input/form used by the theme + var input = header ? header.querySelector('input[type="search"], input[placeholder*="search" i], .hx-search input, [role="search"] input') + : document.querySelector('input.search-input'); + var form = input ? input.closest('form') : (header ? header.querySelector('form[role="search"], form.hx-search, .hx-search form') : null); + + var ensureOpen = function(cb){ + if (openDocSearch) { + cb(); + return; + } + var t = 0; + var tick = function(){ + if (openDocSearch) { + cb(); + return; + } + if (t++ < 30) setTimeout(tick, 100); + }; + tick(); + }; + + var openWithPrefill = function(extraChar) { + var prefill = ''; + if (input) prefill = (input.value || ''); + if (extraChar && extraChar.length === 1) prefill += extraChar; + ensureOpen(function(){ + openDocSearch(); + }); + // After modal mounts, set its input value and propagate event + setTimeout(function(){ + var modalInput = document.querySelector('.DocSearch-Input'); + if (modalInput) { + modalInput.value = prefill; + var evt = new Event('input', { bubbles: true }); + modalInput.dispatchEvent(evt); + modalInput.focus(); + // Move caret to end + try { + modalInput.setSelectionRange(modalInput.value.length, modalInput.value.length); + } catch (e) {} + } + }, 20); + }; + + if (input && !input.__ccDocSearchBound) { + input.__ccDocSearchBound = true; + found = true; + // Prevent typing into the old input; route into DocSearch + input.addEventListener('focus', function(e){ + e.preventDefault(); + openWithPrefill(); + input.blur(); + }); + input.addEventListener('keydown', function(e){ + // Allow Tab to move focus + if (e.key === 'Tab') return; + e.preventDefault(); + var ch = (e.key && e.key.length === 1) ? e.key : ''; + if (e.key === 'Backspace') { + if (openDocSearch) openWithPrefill(''); + return; + } + openWithPrefill(ch); + }); + } + + if (form && !form.__ccDocSearchBound) { + form.__ccDocSearchBound = true; + found = true; + form.addEventListener('submit', function(e){ + e.preventDefault(); + openWithPrefill(); + }); + } + + // Overlay approach: add a transparent clickable layer above the input + var wrapper = (input && input.closest('.search-wrapper')) || document.querySelector('.search-wrapper'); + if (wrapper && !wrapper.querySelector('.cc-docsearch-overlay')) { + found = true; + var overlay = document.createElement('button'); + overlay.type = 'button'; + overlay.className = 'cc-docsearch-overlay'; + overlay.setAttribute('aria-label', 'Open search'); + overlay.style.position = 'absolute'; + overlay.style.inset = '0'; + overlay.style.background = 'transparent'; + overlay.style.cursor = 'text'; + overlay.style.zIndex = '5'; + overlay.style.border = '0'; + overlay.style.padding = '0'; + overlay.style.margin = '0'; + // Let the kbd hint remain clickable-less + var kbd = wrapper.querySelector('kbd'); + if (kbd) { + kbd.style.pointerEvents = 'none'; + } + overlay.addEventListener('click', function(e){ + e.preventDefault(); + openWithPrefill(); + }); + overlay.addEventListener('keydown', function(e){ + if (e.key === 'Tab') return; + e.preventDefault(); + var ch = (e.key && e.key.length === 1) ? e.key : ''; + openWithPrefill(ch); + }); + wrapper.style.position = wrapper.style.position || 'relative'; + wrapper.appendChild(overlay); + } + + return found; + }; + + if (!tryAttach()) { + // Retry shortly after to give the theme time to render header + setTimeout(tryAttach, 200); + setTimeout(tryAttach, 500); + // Observe header mutations to rebind when menu/header changes (e.g., responsive) + var header = document.querySelector('header'); + if (header && !header.__ccDocSearchObserved) { + header.__ccDocSearchObserved = true; + var mo = new MutationObserver(function(){ + tryAttach(); + }); + mo.observe(header, { childList: true, subtree: true }); + } + } + + // Global keyboard shortcuts to match common UX: '/' and Cmd/Ctrl+K + window.addEventListener('keydown', function(e){ + var activeTag = (document.activeElement && document.activeElement.tagName) || ''; + var typingInInput = /INPUT|TEXTAREA|SELECT/.test(activeTag); + if (!typingInInput && (e.key === '/' || (e.key.toLowerCase() === 'k' && (e.metaKey || e.ctrlKey)))) { + e.preventDefault(); + if (openDocSearch) openDocSearch(); + } + }); + }); +})(); \ No newline at end of file diff --git a/commons/addons/cellar.md b/commons/addons/cellar.md deleted file mode 100644 index c8dd7174f..000000000 --- a/commons/addons/cellar.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Cellar add-on -position: 3 -shortdesc: Cellar is a Amazon S3-compatible file storage system created and hosted by Clever Cloud. -tags: -- addons -keywords: -- S3 -- amazon -- Storage -- file -- files ---- - -# Cellar: a S3-like object storage service - -Cellar is S3-compatible online file storage web service. You can use it with -your favorite S3 client. - -To manually manage the files, you can use [s3cmd](http://s3tools.org/s3cmd). -You can download a s3cmd configuration file from the add-on configuration -page. - -## Clever Cloud Cellar plans - - - - - - - - - - - - - - - - - - - - - - -
Cellar storage plans
StoragePrice / GB / moPrice / TB / mo
First 1 TB€ 0.02€ 20.48
Till 25 TB0.015€15.36€
Till 50 TB0.01€10.24€
- - - - - - - - - - - - - - - - - -
Cellar trafic usage plans
Traffic (outbound)Price / GB / moPrice / TB / mo
till 10TB 0.09€92.16€
Till 40 TB0.07€71.68€
- -## Creating a bucket - -In Cellar, files are stored in buckets. When you create a Cellar addon, no -bucket is created yet. - -To create a bucket, you can use s3cmd: - -```bash - s3cmd mb s3://bucket-name -``` -You can list files - -```bash - s3cmd ls s3://bucket-name -``` - -You can upload files (`--acl-public` makes the file readable by everyone). - -```bash - s3cmd put --acl-public image.jpg s3://bucket-name -``` - -
-
-

S3 signature algorithm

-
-
- Cellar doesn't support the `v4` signature algorithm from S3. Please make sure - your client is configured to use the `v2` signature algorithm. The - s3cmd configuration file provided on the add-on configuration page already has it. -
-
\ No newline at end of file diff --git a/commons/addons/clever-cloud-addons.md b/commons/addons/clever-cloud-addons.md deleted file mode 100644 index 3ecbb11ee..000000000 --- a/commons/addons/clever-cloud-addons.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Clever Cloud Add-ons -position: 2 -shortdesc: 'This article introduces the add-ons: a way to add services to your application on Clever Cloud.' -tags: -- addons -keywords: -- addons -- addon ---- - -# Introduction to Add-ons - -Add-ons are a way to add services to your application, for example a database or a caching system, to enrich its -features. - -An add-on can be shared by different applications to share data between them. It can be a database shared by two or -three applications of your infrastructure for example, or they can be independent. - -The add-ons offer different plan to adapt to your needs. You can find details about them on the documentation page of -the add-on. - -## Available add-ons - -Clever Cloud provides multiple add-ons to work with your applications: - -* [MySQL](/doc/addons/mysql) -* [PostgreSQL](/doc/addons/postgresql) -* [MongoDB](/doc/addons/mongodb) -* [FS buckets](/doc/addons/fs_buckets) -* [Cellar](/doc/addons/cellar) -* [Redis](/doc/addons/redis) -* [Redsmin](/doc/addons/redsmin) - -## Create an add-on for your application - -In order to create an add-on for your application, go to the [Clever Cloud Console](https://console.clever-cloud.com/). -When you are in the main page of the console, go to the organisation in which you wan to create the add-on, -for example your [personal space](https://console.clever-cloud.com/users/me). - -When you are in the organisation, click on **Add an add-on**. This space let you create and configure the -add-on to follow your needs. - -First, choose which *type* of add-on you want to create. See above to have a list of available add-ons and the -corresponding pages for a description and information. - -Now, select the plan you need for you add-on. You can find details about the pricing, the capacity of the add-on, ... -on this page or in the corresponding documentation page. - -The third step offers you to choose with which application you want to link you add-on. Linking an add-on to an -application will provide configuration to the application through [environment variables](/admin-console/environment-variables). -This environment variables must be used in your application to, for example, provide the credentials and the -localization of the database provided by the add-on. - -The last step lets you choose the name of the add-on (for example "My database") and the region where the add-on is -hosted. Click on the **Create** button and the add-on will now be available in your organisation, and corresponding -environment variables will be available for the applications linked to the add-on you just created. - -## Managing your add-on - -Once an add-on is created, two tabs are available: - -* the Information tab -* the Configuration tab - - -### Link an add-on to your application - -To link an add-on with your application, just follow the following steps: - -1. Go in the organisation of your application and click on the name of the application you want to link with your add-on. -2. Go in the **Add-ons** section. -3. Click on the **Link** button of the add-on you want to link to your application. - - -### Information screen - -This screen sums-up the characteristics of the selected add-on. -Features and environment variables (if applicable) are shown. - -
- - - -
- Example of the information tab of an add-on -
-
- - -### Configuration screen - -Add-ons can be managed from the Configuration tab. -This screen is managed directly by the provider of the add-on. - -
- - - -
- Example of the configuration tab of an add-on -
-
- - -## Delete an add-on - -To delete an add-on, go to the *Configuration* page of the add-on, and click on *Remove add-on*. -Warning: After deletion of the add-on, all associated data will be removed. diff --git a/commons/addons/fs_buckets.md b/commons/addons/fs_buckets.md deleted file mode 100644 index 17d5312da..000000000 --- a/commons/addons/fs_buckets.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: FS Buckets add-on -title: FS Buckets add-on -position: 4 -shortdesc: This add-on allows applications to use a persistent file system, as git-based apps don't have one. -tags: -- addons -keywords: -- nfs -- file system -- buckets -- fs buckets ---- - -# FS Buckets: file system with persistence - -When you deploy an application on any PaaS, a new virtual machine is created, the previous one is deleted. -If your application generates data, for example if you let users upload pictures and you do not store it on external -services like S3, you will loose anything stored on the disk. - -The Git deployment does not allow you to keep generated data files between deployments. To avoid the loss of your data, -you have to mount a persistent filesystem. This is why we created File System Buckets. - -You will be able to retrieve generated data between two deployments. - -## FS Buckets plans - - - - - - - - - - - - - - - - - - - - -
FS Buckets pricing plans
NameDiskMountsPrice /Go
DEV100 MBUNLIMITEDFree
SUNLIMITEDUNLIMITED1.50€
- -## Configuring your application - -To configure your application to use buckets, use the -`clevercloud/buckets.json` file. - -The `clevercloud` folder must be located at the root of your application. - -The `buckets.json` file must contain the following structure: - -```javascript -[ - { - "bucket" : "bucketId", - "folder" : "/myFolder", - "apps" : ["app_id"] - - }, - { - "bucket_host" : "bucket-c65762b6-4086-4c99-84b0-23eb85695809-fsbucket.services.clever-cloud.com", - "folder" : "/myotherFolder", - "apps" : ["app_id_2"] - } -] -``` - -
-
-

Getting a pre-filled conf file.

-
-
- You can find a pre-filled json object to copy in the dashboard of your FSBucket add-on, in the "Dashboard configuration" tab -
-
- -It's a json array containing objects with at least two fields: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
UsageFieldDescription
RequiredbucketThe bucket id you can find in the console. It begins with `bucket_`. This is for -"old-style" buckets (created before the 7 december 2015)
Requiredbucket_hostThe bucket host you can find in the console. It begins with `bucket-` and ends with -`services.clever-cloud.com`. This is for "new-style" buckets.
RequiredfolderThe folder you want the bucket to be mount in. Should start with `/`. Using the example -*myFolder*, you can access your bucket via the *myFolder* folder at -the root of your application or via */app/myFolder*
OptionalappsWhitelist of the applications allowed to mount this bucket. It's helpful if you need -to deploy a *preprod* app and a *prod* app using the exact same codebase but different -buckets
- -
-
-

Important note about target folder

-
-
-

- The folder must not exist in your repository (or it needs to be empty). Otherwise, the mount of your bucket will be ignored. -

-

- You can mount the same bucket in different folders, but they will share the same - content, so it's not the solution. You should prefer to mount the bucket in only one - folder and then manage multiple subfolders in it. -

-
-
- -
-
-

Important notes

-
-
-

- You cannot mount two buckets in the same folder for the same app. -

-

- If you put the same "folder" value for two entries in the *buckets.json* array, **you better - make sure** that the "apps" fields make the two buckets mutually exclusive upon deployment! -

-
-
- -## Accessing your data inside the FS Bucket - -### From the addon dashboard - -The "File explorer" tab of the addon dashboard gives you access to your files -in the FS bucket. - -### From your favourite FTP client - -The "Addon information" tab of your FS Bucket add-on displays the information -you need to connect to your bucket using FTP. diff --git a/commons/addons/mongodb.md b/commons/addons/mongodb.md deleted file mode 100644 index 43cbf9d95..000000000 --- a/commons/addons/mongodb.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: MongoDB add-on -position: 5 -shortdesc: MongoDB is a noSQL and document-oriented database, operated by Clever Cloud. -tags: -- addons -keywords: -- mongo -- mongodb -- document -- nosql -- database ---- - -# MongoDB - -MongoDB is an open source NoSQL document-oriented database. - -## MongoDB plans - - - - - - - - - - - - - - - - - - - - - - - - - - -
MongoDB pricing plans
NameDiskCache (Memory)Price /mo
S500 MBSHAREDFree
SM30 GB2 GB75.00€
M100 GB4 GB150.00€
diff --git a/commons/addons/mysql.md b/commons/addons/mysql.md deleted file mode 100644 index b5a5e5d25..000000000 --- a/commons/addons/mysql.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: MySQL add-on -position: 6 -shortdesc: MySQL is an open-source relational database management system (RDBMS). -tags: -- addons -keywords: -- sql -- mysql -- mariadb -- RDBMS ---- - -# MySQL - -MySQL is an open-source relational database management system (RDBMS). - -## MySQL plans - -
-
-

Note for Shared databases

-
-
- As Shared databases (DEV and S plans) are shared between multiple applications and delays could appear in case of - an high demand.
- If this delays create problems in your application or are problematcs, we recommend you to use a dedicated database - (M plans and above). -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MySQL pricing plans
NameCache (Memory)DiskConn. limitPrice /mo
DEVSHARED10 MB5Free
SSHARED256 MB1015 €
M1 GB10 GB7545 €
L2 GB200 GB500300 €
- -### Migrating from an old database - -Some applications require a populated database to run properly. -If you want to import your **SQL** dump, you can use several methods: - -1. [Our WebGUI (PHP My Admin)](https://dbms-pma.clever-cloud.com/). -2. Command line tool for MySQL administration. -3. Any MySQL client such as [MySQL Workbench](https://www.mysql.fr/products/workbench/). - -If you need to import a very large dump, please send an email to . diff --git a/commons/addons/postgresql.md b/commons/addons/postgresql.md deleted file mode 100644 index 391a7f132..000000000 --- a/commons/addons/postgresql.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: PostgreSQL add-on -position: 7 -shortdesc: PostgreSQL is an open-source relational database management system (RDBMS). -tags: -- addons -keywords: -- sql -- postgresql -- pg -- pgsql -- mariadb ---- - -# PostgreSQL - -PostgreSQL is an object-relational database management system (ORDBMS) with an emphasis on extensibility -and on standards-compliance. - -## PostgreSQL version - -The version currently installed by the add-on is : - -- on shared plans (DEV and S) : PostgreSQL 9.2.8 -- on newly created dedicated databases (plans M and above) : Postgresql 9.3.4 - -Note that PostgreSQL 9.4 branch (or 9.5 branch when the final version will be released) will be rolled out as soon as possible on the dedicated databases plans. - -## PostgreSQL plans - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PostgreSQL pricing plans
NameMemoryDB sizeConn. limitPrice /mo
DEVSHARED256 MB5Free
SSHARED1 GB1010 €
M1 GB100 GB7530 €
L8 GB450 GB500240 €
XL32 GB600 GB1000700 €
- -## Migrating from an old database - -Some applications require a populated database to run properly. -If you want to import your **SQL** dump, you can use several methods: - -1. [Our WebGUI (Adminer)](https://dbms-adminer.clever-cloud.com/adminer/). -2. Command line tool for PostgreSQL administration like `psql`. -3. Any PostgreSQL client such as [pgAdmin](http://www.pgadmin.org/). diff --git a/commons/addons/redis.md b/commons/addons/redis.md deleted file mode 100644 index 60956f292..000000000 --- a/commons/addons/redis.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Redis add-on -position: 8 -shortdesc: Redis is an open source, in-memory data structure store, used as database, cache and message broker. -tags: -- addons -keywords: -- key -- value -- key value -- key-value -- in-memory ---- - -# Redis - -Redis is an open source, in-memory data structure store, used as database, cache and message broker. - -## Redis plans - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Redis pricing plans
NameDATABASESDiskConn. limitPrice /mo
DEV10010 MB10Free
S100100 MB1008,67 €
M100250 MB25013,34 €
L100500 MB50043,38 €
XL100100 MB50078,08 €
XXL1002500 MB500190,71 €
diff --git a/commons/addons/redsmin.md b/commons/addons/redsmin.md deleted file mode 100644 index 7496f32c5..000000000 --- a/commons/addons/redsmin.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Redsmin add-on -position: 9 -shortdesc: Redsmin is a GUI to help developers monitor their Redis systems. -tags: -- addons -keywords: -- redis -- redsmin -- key-value -- dashboard ---- - -# Redsmin - -
-
-

Redis + Redsmin

-
-
- Clever Cloud now provides a Redis add-on, that comes with Redsmin.
- Read [this blog post](https://www.clever-cloud.com/blog/features/2015/08/26/introducing-redis-by-clever-cloud/) to - know more about it. -
-
- -Redsmin is a GUI to help developers monitor their Redis systems. - -## Redsmin plans - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Redsmin pricing plans
NameConn. Redis InstancesServeursPrice /mo
DEV110,00 €
S115,99 €
Medium2219,99 €
Large3324,00 €
XL4429,99 €
diff --git a/commons/admin-console/analytics-consumption.md b/commons/admin-console/analytics-consumption.md deleted file mode 100644 index 1ffa43c46..000000000 --- a/commons/admin-console/analytics-consumption.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Analytics and consumption -position: 6 -shortdesc: Redis is an open source, in-memory data structure store, used as database, cache and message broker. -tags: -- billing -keywords: -- billing -- consumption ---- - -# Analytics and consumption - -You only pay what you consume. It means that every 10 minutes, we check your applications consumption and affect it to your credits account. - -The following charts on the dashboard main page presents daily credits consumption: - -
-
diff --git a/commons/admin-console/apps-management.md b/commons/admin-console/apps-management.md deleted file mode 100644 index 8fa51c3ad..000000000 --- a/commons/admin-console/apps-management.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Apps Management -position: 7 -shortdesc: Starting, stopping and loggins for application -tags: -- dashboard-setup -keywords: -- stop -- deploy -- restart -- logs ---- - -# Managing Application Lifecycle and Informations - -## Start, restart and stop - -You can start, restart, and stop your application in the associated configuration panel. - -Stop functionality is usefull during the development of the application to limits its credit consumption. - -
- -
-
Manage your application
- -## Edit and delete - -You can edit your application in the information panel. You can rename, change region, delete and change some properties. - -
- -
-
Edit your application
- -## Logs - -The Clever Cloud dashboard gives you the ability to retrieve your application logs. - -To get them, just click on *Logs* in the left navbar. diff --git a/commons/admin-console/authentification.md b/commons/admin-console/authentification.md deleted file mode 100644 index 525c06762..000000000 --- a/commons/admin-console/authentification.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Authentication -position: 1 -shortdesc: How to be authenticated on Clever Cloud -tags: -- account-setup -keywords: -- auth -- authentication -- github ---- - -# Authentication On Clever Cloud - -The API of Clever Cloud uses oAuth 2 to perform authentication actions. This is the same for signup an login. -There is two ways to signup to Clever Cloud: email or GitHub login. - - -## Email Authentication - -This kind of auth requires a valid and non-temporary disposable e-mail, and a password having at least 6 characters. - -## Github Authentication - -The GitHub signup allow you to create an account, or link your existing one to GitHub, in one click. -This process ask the following permsissions:  - -* Read your Public Key -* Read User Repositories - -The "repository permission" is used to deploy your GitHub apps directly to Clever Cloud, with a simple step. \ No newline at end of file diff --git a/commons/admin-console/custom-domain-names.md b/commons/admin-console/custom-domain-names.md deleted file mode 100644 index cec0127f0..000000000 --- a/commons/admin-console/custom-domain-names.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Custom domain names -position: 3 -shortdesc: How to setup and configure domains names for your apps -tags: -- dashboard-setup -- developer -keywords: -- DNS -- domain -- URL ---- - -# Managing Domain Names - -When creating an application, you have two (non exclusive) choices for domain names: - -* Using a personal domain name -* Using a ***.cleverapps.io** free domain, with built-in SSL - -## Linking your Domain Name to your Application - -You can link one or several domain names in the console. - -Add it in the application configuration: in the console, click on your **application name** in the first panel, then choose **domain names**. You'll have to choose to add a custom domain name or use a sub-domain under ``*.cleverapps.io`` - -There is a default entry configured by default for every new app: ``yourAppID.cleverapps.io``. -In your application's domain section, just enter ``example.cleverapps.io``. You have to choose a unique one. Trusted SSL is available on every sub-domains. - -If you need to configure a custom domain name, see the steps below. - -## Personal Domain Names - -### Your Application Runs in the Europe/Paris ('PAR') Zone - - - - - - - - - - - - - - -
Record Type
Value
CNAME
Recommended
``domain.par.clever-cloud.com``
A
Only if CNAME is not available
Two records on ``62.210.112.171`` and ``62.210.92.244``
- - -### Your Application Runs in the North-America/Montreal ('MTL') Zone - - - - - - - - - - - - - - -
Record Type
Value
CNAME
Recommended
``domain.mtl.clever-cloud.com``
A
Only if CNAME is not available
Two records on ``68.71.34.21`` and ``68.71.34.20``
- - -
- -You can point your domain name to clever cloud either with a CNAME record or with A records. **The use of a CNAME record is highly recommended.** With a CNAME record, your DNS configuration is always up-to-date. Using A records will require you to keep the DNS configuration up-to-date manually. Domain names linked to clever cloud applications are monitored, so we will send you an email if your DNS configuration is obsolete or incorrect. - - -
-
-

Warning on CNAME Availability

-
-
- You cannot use a CNAME on a top-level domain, or on a subdomain which already has DNS records. -
-
- -If you want to make your application available from a domain name which does not support CNAME records (eg example.com in addition to ``www.example.com``), check if your registrar provides a web redirection service. This way, you only have to make ``www.example.com`` point to Clever Cloud. Please note that web redirection provided by registrars only work over HTTP. - -Remember that DNS changes may take time to propagate (usually a few hours, sometimes up to a day or more). It depends on the TTL setting of your DNS configuration. For faster changes, you can lower the TTL value in advance, and rise it again afterwards. - -Before changing your domain name configuration, you can lower the TTL of your domain name one day before the migration (like 3min). Any changes on your DNS configuration will be applied faster. Then, when everything is configured properly, you can put the default TTL value. - - -
-
-

Note on using a domain wildcard

-
-
-
- ``*.example.com`` will match e.g. ``blog.example.com`` or ``www.example.com``. -
-
But for the raw domain ``example.com``, you will have to add both ``*.example.com`` and example.com to your application.
-
-
-
-### Contextual Example - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Domain Name Use Case CNAME config record A config Web redirections
``www.example.com``
``example.com``		 point ``www.example.com`` to ``domain.par/mtl.clever-cloud.com.``No A record neededRedirect ``example.com`` to ``www.example.com``
``www.example.com`` point ``www.example.com`` to ``domain.par/mtl.clever-cloud.com.``No A record neededNo redirect needed
``example.com``No CNAME record neededpoint ``example.com`` to the two IP adresses of the selected regionNo redirect needed
\ No newline at end of file diff --git a/commons/admin-console/environment-variables.md b/commons/admin-console/environment-variables.md deleted file mode 100644 index 9f4ef1a2a..000000000 --- a/commons/admin-console/environment-variables.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Environment variables -position: 8 -shortdesc: How to setup and configure environnement variables for apps and add-ons -tags: -- dashboard-setup -- developer -keywords: -- env -- variables -- environment variables ---- -## Configuring Environment variables - -Clever Cloud allows you to define environment variables that will be -injected in your application's environment. - -### How variables are defined? - -Variables are defined on a per-application basis. They are defined by three ways: - - * By provisionned add-ons linked to applications. The variables names - are listed in the add-on's information panel - - * By adding variables yourself in the "Environment variables" panel of - your application. - - * Some special environment variables are added automatically for each application. - -Please note that if you define or modify environment variables, you will -need to redeploy you application to make it use the variables. - -### Special environment variables - -Some variables are injected to the environment of your application when you deploy it, -to inform you about the current context of your application and about the application itself. - -They can be accessed as classics environment variables and can be used in your application to -give you information about the current context of the application. - - * `APP_ID` : the ID of the application. Each application has a unique identifier used to - identify it in our system. This ID is the same than the one you can find in the information - section of your application. - - * `INSTANCE_ID` : the ID of the current instance of your application. It's unique for each - instance of your application and change every time you deploy it. - - * `COMMIT_ID` : the commit ID used as a base to deploy your application. As we remove - the `.git` directory before the deployment (to avoid security problems), it can be used - to know which version of your application is running on the server. - - * `APP_HOME` : The absolute path of your application on the server. Can be used to - create absolute link in you application (ex : ${APP_HOME}/foo/bar). - - * `INSTANCE_NUMBER` - -#### What is the `INSTANCE_NUMBER` variable used for? - -This variable allows your application to differentiate each running node on the applicative level. - -It will contain a different number for each instance of your application. - -For example, if three instances are running, it will contain `0` for the first, `1` -for the second and `2` for the third. - -### Variable definition constraints - -For the second way, please note that *spaces are not allowed* in the -name of the variables. - -As written in the previous section: please note that if you define or modify -environment variables, you will need to redeploy you application to make it use the variables. - -### How do I use these variables? - -Depending on the type of your application, you will need to use -different ways. You can find the various ways in the specific instances -documentations. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
languageuse case
Node.js process.env["MY_VAR"]
Java WAR System.getProperties().getProperty("MY_VAR")
Play! Framework 1 -& Play! Framework 2System.getenv("MY\_VAR") or \${MY_VAR} in application.conf
Scala System.getenv("MY\_VAR")
PHPgetenv("MY_VAR")
Pythonos.getenv("MY_VAR")
Rubyenv[“my_var”]
- -Please note that the variables are available at build-time, for -runtimes that support build-time instructions, such as -Java WAR, -Play! Framework 1, -Play! Framework 2 -or Scala. diff --git a/commons/admin-console/invoices-payments.md b/commons/admin-console/invoices-payments.md deleted file mode 100644 index ad455f512..000000000 --- a/commons/admin-console/invoices-payments.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Payments & invoicing -position: 5 -shortdesc: Managing invoices and payment on Clever Cloud -tags: -- billing -keywords: -- invoices -- tax -- pricing ---- -# Payments & invoicing - -## Make a payment - -From the *Credit Manager* section, there are three alternatives to buy credit for your applications: - -* Credit card -* Paypal -* Bank transfer: we accept international bank transfers. Send an email to if you want to use it. This method is usefull to make automatic payments. - - -## Invoices - -Invoices are available in the *Invoices* tab of the *Credits Manager* section. It lists all the payments made. - -## Change Billing Information - -* for personal account: available in *Profile > Informations* - -* for organization: available in *Configuration > Informations and Advanced Configuration* - -
- -
Organization information
-
diff --git a/commons/admin-console/organizations.md b/commons/admin-console/organizations.md deleted file mode 100644 index 8265d54a0..000000000 --- a/commons/admin-console/organizations.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Roles and Organizations -position: 4 -shortdesc: Managing users and roles in organizations -tags: -- dashboard-setup -keyworkds: -- roles -- users -- accounts -- organisations -- organizations -- collaboration ---- -# Organizations - -In order to improve team collaboration between developers, accountants, managers and admins, we have introduced organizations. - -Once you create an organization, you can add collaborators and assign them [roles](#roles-and-privileges) which give them rights. - - -## Add an organization - -Organization names are uniques. It means that you cannot use an organization name that is already used. - -In order to add an organization, just click on "Add an organization" in the top left dropdown menu: - -
- -
-Access to your organizations via the red sidebar -
-
- - -
- -
-An organization can represent an enterprise, for an easier invoicing process -
-
- - -## Roles and privileges - -The table below describes rights assigned to roles: - -
- -
- Rights assigned by role -
-
diff --git a/commons/admin-console/ssh-keys.md b/commons/admin-console/ssh-keys.md deleted file mode 100644 index 5ac79306b..000000000 --- a/commons/admin-console/ssh-keys.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: SSH Keys -position: 2 -shortdesc: Add and manage SSH keys for push and deployments -tags: -- account-setup -keywords: -- git -- deploy -- deployment -- push -- ssh -- sshkeys ---- - -# SSH keys - -SSH keys are used to establish a secure connection between your computer and Clever Cloud. -You need to add a SSH key to your Clever Cloud's account to deploy via Git. -A user can have multiple SSH keys. - -
-

Warning:

-

A SSH key can be used with only one account. A SSH key is used to identify the actions made by a user and must be -associated with only one account.
-If a key is used by more than one account, a warning will be displayed in the console.

-
- -How to add your SSH key on Clever Cloud? - -### Github account and SSH key on Clever Cloud - -If your account is linked to GitHub, a new panel with your GitHub SSH key will appear in the "SSH Key" menu. -So you can add every key via a simple click and you don't have to add it manually. - -## Find your SSH key - -You can already have an SSH key and so do not need to generate a new one. To check if you have one, follow the steps: - -### Linux and Mac - -1. Wether you use Mac or Linux, open your Terminal application. -2. Run `$ cd ~/.ssh/` in your Terminal. -3. If the folder exists, run `$ ls` and check if a pair of key exists : *id_rsa* and *id_rsa.pub*. - If you can find them, you do not need to generate a new one, simply go to the following - "Add you key on Clever Cloud" part! - -
- -### Windows - -1. If you don't have it, download [Git for Windows](https://git-for-windows.github.io/) and install it. -2. Run **Git Bash** (from the *Start Menu* or from the *Explorer* with the contextual menu (right click)). -3. Run `$ cd ~/.ssh/` in your Terminal. -4. If the folder exists, run `$ ls` and check if a pair of key exists : *id_rsa* and *id_rsa.pub*. - If you can find them, you do not need to generate a new one, simply go to the following - "Add you key on Clever Cloud" part! - -## Create your SSH key - -If you read the previous section, you should have a Terminal open. - -1. In your Terminal, enter the following bash line: - - ```bash - $ ssh-keygen -t rsa -C "your_email@youremail.com" - ``` - This command creates a new ssh key using the provided email, so that the owner of the key can be identified. - -2. When asked, enter a passphrase: - - ```bash - Generating public/private rsa key pair. - Enter file in which to save the key (/your_home_path/.ssh/id_rsa): - # Now you should enter a passphrase. - Enter passphrase (empty for no passphrase): [Type a passphrase] - Enter same passphrase again: [Type passphrase again] - ``` - - Which should give you something like this: - - ```bash - Your identification has been saved in /your_home_path/.ssh/id_rsa. - Your public key has been saved in /your_home_path/.ssh/id_rsa.pub. - The key fingerprint is: - 01:0e:e5:2d:ab:98:d6:17:a1:6d:f0:68:9f:d0:a2:db your_email@youremail.com - ``` - -## Add your SSH key on Clever Cloud - -To declare your **public SSH Key** on Clever Cloud, in the left navigation bar, go in "Profile" and in the "SSH Keys" tab. - -Add the key by entering a name and the public SSH key. The key is the entire content of the **id_rsa.pub** file. - -
-
-The SSH Key manager. -
- -In this tab, you can list all your *SSH Keys* available on Clever Cloud and delete them if necessary. -
-

Remember

-

Your public SSH key must be associated with only one account.

- -If you see "*access denied*" or "*password:*" when you -[push on Clever Cloud](https://www.clever-cloud.com/doc/clever-cloud-overview/add-application/#git-deployment), -your SSH Keys may be invalid or not available on Clever cloud. Please check that you SSH Key is present and valid in -your profile. - - **Need help about SSH keys?** -Contact us at or you can -[read more about SSH Keys](http://git-scm.com/book/en/Git-on-the-Server-Generating-Your-SSH-Public-Key). - -## Check your ssh configuration - -To check if your ssh key is correctly configured, you can try to run: - -```bash - ssh git@push.clever-cloud.com -``` - -The first time, you may have to type "yes" to continue. - -If you see "Permission denied (publickey).", something went wrong, feel free to contact the support, otherwise everything should be fine. diff --git a/commons/clever-cloud-apis/add-ons-api.md b/commons/clever-cloud-apis/add-ons-api.md deleted file mode 100644 index ae4911f2a..000000000 --- a/commons/clever-cloud-apis/add-ons-api.md +++ /dev/null @@ -1,463 +0,0 @@ ---- -title: Add-on API -position: 2 -shortdesc: How to integrate your own service as an add-on on Clever Cloud -tags: -- developer ---- -# Clever Cloud add-on API - -Clever Cloud offers you to sell your service as an add-on through the dashboard. -This article will document how you can technically plug into the platform to provide add-on provision, deprovision, and configuration via the dashboard. - -There are two faces here: - -* [The add-on provider API](#add-on-provider-api) - The API *you* need to provide and document to allow the Clever Cloud's backend to request provision and deprovision of add-ons. - -* [The add-on infos API](#add-on-infos-api) - The API Clever Cloud provides to allow you to get informations about provisioned add-ons and their owners. - -## Preamble - -In the PaaS world, an add-on system is preceding the others, therefore is well known by a lot of developers: the Heroku one. To ease up the transition between Heroku and Clever Cloud, we decided to support (then iterate over) the Heroku standard for add-on provisioning API. - -So, if you already have been integrated as an add-on provider for the Heroku platform, you will have no trouble integrating in the Clever Cloud's add-on platform. This explains why we handle "heroku\_id" fields instead of "clevercloud\_id" or equivalent. - -## Add-on Provider API - -This is the API *you* need to provide to allow Clever Cloud to provision an add-on for a customer. - -### How it works - -When a Clever Cloud customer uses the marketplace to provision an add-on, Clever Cloud sends a request to your service which provides a new add-on for this app. - -### Build an add-on - -To become an add-on provider, you need to provide the provisioning API -as defined below. You can implement your API in any language. The -[Sample Code](#sample-code) section will show you examples in various -languages / frameworks. - -To document your API, and start the process of becoming an add-on -provider, you need to send to a manifest -file. This file contains a JSON that describes your add-on. - -#### Example manifest - -Here is what the manifest JSON must look like: - -```json -{ - "id": "addon-name", - "name": "Addon Name", - "api": { - "config_vars": [ "ADDON_NAME_MY_VAR" ], - "regions": [ "eu" ], - "password": "44ca82ddf8d4e74d52494ce2895152ee", - "sso_salt": "fcb5b3add85d65e1dddda87a115b429f", - "production": { - "base_url": "https://yourservice.com/clevercloud/resources", - "sso_url": "https://yourservice.com/clevercloud/sso/login" - }, - "test": { - "base_url": "http://localhost:9000/clevercloud/resources", - "sso_url": "http://localhost:9000/clevercloud/sso/login" - } - } -} -``` - -Fields - -* `id` - An id for your add-on. All lower case, no spaces or punctuation. Underscores and dashes are allowed. This can’t be changed after the first push. It is also used for HTTP basic auth when making provisioning calls. - -* `name` (Optional) - A human readable name for your add-on. You will be able to change it later in the dashboard, so you don't even have to provide it right now. - -* `api/config_vars` - A list of config vars that will be returned on provisioning calls. Each config_var name *MUST* start with the capitalized, underscorized add-on id, as in the example. - -* `api/password` - Password that Clever Cloud will send in HTTP basic auth when making provisioning calls. You should generate a long random string for that field. - -* `api/sso_salt` - Shared secret used in single sign-on between the Clever Cloud admin panel and your service’s admin panel. You should generate a long random string for that field. - -* `api/regions` - The list of geographical zones supported by your add-on. It cannot be empty. As for now, it *MUST* contain the element "eu". More will be supported. - -* `api/production/base_url` - The production endpoint for Clever Cloud api actions (provision, deprovision, and plan change). - -* `api/production/sso_url` - The production endpoint for single sign-on. - -* `api/test/base_url` - The test endpoint for Clever Cloud api actions. Used to test your service on your own machine. You can skip this field. - -* `api/test/sso_url` - The test endpoint for single sign-on. Used to test your service on your own machine. You can skip this field. - -### Authentication - -To secure the calls between your Clever Cloud and API, please provide a -HTTPS connection. The second step to secure the calls is to use a Basic -authentication. The username must be your provider id (in our example, -it is 'addon-name'), and the password must be the the `password` field -set in your manifest. - -So your provider API must check that all calls to it are authenticated -with these user and password. - -#### Sample with Flask in Python - -```python -from functools import wraps -from flask import request, Response - - -def check_auth(username, password): - """This function is called to check if a username / - password combination is valid. - """ - return password == '44ca82ddf8d4e74d52494ce2895152ee' - -def authenticate(): - """Sends a 401 response that enables basic auth""" - return Response( - 'Could not verify your access level for that URL.\n' - 'You have to login with proper credentials', 401, - {'WWW-Authenticate': 'Basic realm="Poney required"'}) - -def requires_auth(f): - @wraps(f) - def decorated(*args, **kwargs): - auth = request.authorization - if not auth or not check_auth(auth.username, auth.password): - return authenticate() - return f(*args, **kwargs) - return decorated -``` - - -### Provisioning - -When a customer installs your add-on, Clever Cloud issues a POST request to your service to provision a ressource for his app. - -The request will be the following: - -```json -Request: POST {base_url} -Request Body: { - "heroku_id": "addon_xxx", - "plan": "basic", - "region": "EU", - "callback_url": "https://api.clever-cloud.com/v2/vendor/apps/addon_xxx", - "logplex_token": "logtoken_yyy", - "options": {} -} -Response Body: { - "id": "myaddon_id", - "config": { - "ADDON_NAME_MY_VAR": "some value" - }, - "message": "Some provisioning message" -} -``` - -The request body contains the following fields: - -* `heroku_id` - The id we give to your add-on to identify it on our side. - -* `plan` - The slug field for the plan the user chose. You can create -plans in the dashboard once your add-on manifest has been uploaded to -the Clever Cloud's platform. We send you the slug of the given plan, -not its name. - -* `region` - The region to provision the add-on. As for now, only "EU" will be sent. - -* `callback_url` - The URL you can use to get informations about the add-on and the user. This URL is available as soon as the provisioning is done. You can't use this URL during the POST call. - -* `logplex_token` - Token used to identify what you send to our log collector. The log collector API doc is here: [/clever-cloud-addons-api/add-ons-log-collector/](/doc/clever-cloud-addons-api/add-ons-log-collector/) - -* `options` - String -> String map with options. We don't currently support this, so it will be empty for now. - -The response body contains the following fields: - -* `id` - The add-on id as seen from your side. The difference with the heroku api is that the id *MUST* be a String. - -* `config` (Optional) - A String -> String map with value for each config\_var defined in your manifest. A key that is not in your config\_vars will be ignored. - -* `message` (Optional) - A creation message we will display in the dashboard. - -### Deprovisioning - -When a customer deletes your add-on, Clever Cloud issues a DELETE request to your service to deprovision a ressource for his app. - -The request will be the following: - -```json -Request: DELETE {base_url}/{addon_id} -Request Body: none -Response Status: 200 -``` - -* `addon_id` - This is the same as the `id` field set in the response to the provisioning call. - -### Plan change - -When a customer wants to change it's add-on's plan, Clever Cloud issues a PUT request to your service. - -The request will be the following: - -```json -Request: PUT {base_url}/{addon_id} -Request Body: { - "heroku_id": "addon_xxx", - "plan": "premium" -} -Response Body: { - "config": { ... }, - "message": "your message here" -} -``` - -* `addon_id` - This is the same as the `id` field set in the response to the provisioning call. - -The request body contains: - -* `heroku_id` - The add-on's id as seen from our side. - -* `plan` - The name of the new plan. - -The response body contains: - -* `config` - The value for the new config map. Same constraints as in the provisioning response. - -* `message` - A message displayed in our dashboard. - -### SSO - -Your service probably has a web UI admin panel that your users log into to manage and view their resources. - -Clever Cloud customers will be able to access the admin panel for their resource if you implement single sign-on. - -Clever Cloud will generate a single sign-on token by combining the salt (a shared secret), timestamp, and resource ID. The user’s browser will be redirected to your site with this token. Your site can confirm the authenticity of the token, then set a cookie for the user session and redirect them to the admin panel for their resource. - -When the user clicks your add-on in their add-on menu, they will be directed via HTTP POST to a URL defined in your manifest. - -```http -POST -Request Body: id=&token=×tamp=&nav-data=&email= -``` - -* The hostname or sso_url comes from your add-on manifest. -* The id is the ID for the previously provisioned resource. -* The timestamp is a millisecond timestamp. You *SHOULD* verify that the timestamp is not older than 15 minutes. -* the token is computed using the formula below. -* Nav data contains information like the current app name and installed add-ons for Clever Cloud Dashboard. - -#### Token - -The token field in the sso call, is created as follow: - -```javascript -sha1sum(id + ':' + sso_salt + ':' + timestamp) -``` - -Where: - -* `id` - The id of the connecting add-on. This is the id you returned on -the provision call. - -* `sso_salt` - The sso_salt field defined in your manifest. - -* `timestamp` - The timestamp field of the sso request. - -#### Sample in Python - -```python -from hashlib import sha1 -import time - -id = "1234" -salt = "fcb5b3add85d65e1dddda87a115b429f" -timestamp = str(time.time()) -token = sha1(id + ':' + salt + ':' + timestamp).hexdigest() -print token -``` - -This will return: - -``` -'aca601ba464437cbaa12b2fedd7db755c32ddb5e' -``` - -## Add-on Infos API - -This API is part of the Clever Cloud API. The base URL for the Clever Cloud API is: - -```http -https://api.clever-cloud.com/v2 -``` - -You should prefix your calls by this base URL. - -### Authentication - -To secure the calls between your API and Clever Cloud, The Clever Cloud -API is behind a HTTPS connection. The second step to secure your calls is to use a Basic -authentication. The username must be your provider id (in our example, -it is 'addon-name'), and the password must be the `password` field -set in your manifest. - -#### Example call to Clever Cloud add-on infos API - -```bash -$ curl -XGET https://api.clever-cloud.com/v2/vendor/apps -u addon-name:44ca82ddf8d4e74d52494ce2895152ee -``` - -### Endpoints - -#### List all add-ons provided by you - -```json -GET /vendor/apps -Response Body: [ - { - "provider_id": "addon-name", - "heroku_id": "addon_xxx", - "callback_url": "https://api.clever-cloud.com/v2/vendor/apps/addon_xxx", - "plan": "test", - "owner_id": "user_foobar" - }, { - "provider_id": "addon-name", - "heroku_id": "addon_yyy", - "callback_url": "https://api.clever-cloud.com/v2/vendor/apps/addon_yyy", - "plan": "premium", - "owner_id": "orga_baz" - } -] -``` - -* `provider_id` - Should be the same as the "id" field of your uploaded manifest. - -* `heroku_id` - The add-on's id from Clever Cloud's POV. - -* `callback_url` - URL to call to get more informations about this add-on. - -* `plan` - The current plan of this add-on. - -* `owner_id` - The id of the owner that provisioned the add-on. This should never change. - - -#### Get informations about a specific add-on - -**Caution**: this endpoint is **not** available during the provisioning call. If you want -informations, you need to reply to the provisioning call, **then** you can call this -endpoint. - -```json -GET /vendor/apps/{addonId} -Response Body: { - "id": "addon_xxx", - "name": "My addon-name instance", - "config": {"MYADDON_URL": "http://myaddon.com/52e82f5d73"}, - "callback_url": "https://api.clever-cloud.com/v2/vendor/apps/addon_xxx", - "owner_email": "user@example.com", - "owner_id": "orga_baz", - "owner_emails": ["user@example.com", "foobar@baz.com"], - "region": "eu", - "domains": [] -} -``` - -This endpoint gives you more informations about a provisioned add-on. - -* `id` - The add-on id from Clever Cloud's POV. - -* `name` - The name the user gave to this add-on in the Clever Cloud's dashboard. - -* `config` - Config vars as you defined during the provision call. - -* `callback_url` - The URL you just called. - -* `owner_email` - One of the owner's email address. - -* `owner_emails` - All the owner's email addresses. This is not in the Heroku specification. - -* `owner_id` - The id of the owner that provisioned the add-on. This should never change. - -* `region` - The region this add-on is located in. As for now, we only support "eu". - -* `domains` - Originally the domains names for the application owning the add-on. We return an empty list. - -#### Update the config vars for an add-on - -**Caution**: this endpoint is **not** available during the provisioning call. If you want -informations, you need to reply to the provisioning call, **then** you can call this -endpoint. - -```json -PUT /vendor/apps/{addonId} -Request Body: { - "config": { - "ADDON_NAME_URL": "http://myaddon.com/ABC123" - } -} -Response Status: 200 OK -``` -The object should only contain the `config` object your API returned -during the provisioning. - -## Sample code - -### Add-on Skeleton in Python - -```python -#!/usr/bin/env/python -# -*- coding:utf-8 -*- - -""" -api.py -""" -from flask import Flask, redirect, Response, jsonify, request -import auth -import provision - -app = Flask(__name__) - -@app.route('/') -def index(): - """ - Render the home template - """ - return redirect("https://google.com/") - - -@app.route('/clevercloud/resources', methods=['POST']) -@auth.requires_auth -def clevercloud_create_resource(): - data = request.json - msg = provision.add(**data) - return jsonify(msg) - - -@app.route('/clevercloud/resources/', methods=['DELETE','PUT']) -@auth.requires_auth -def clevercloud_action_resource(id): - data = request.json - if request.method == 'POST': - msg = provision.del(id,**data) - - if request.method == 'PUT': - msg = provision.update(id,**data) - - return jsonify(msg) - -@app.route('/clevercloud/sso/login') -def clevercloud_sso_login(): - return Response(status=200) - - -if __name__ == "__main__": - app.run(host='0.0.0.0',port=9000,debug=True) -``` - -### Add-on API template using scala and Play! framework 2. - -[https://github.com/CleverCloud/addon-provider-template](https://github.com/CleverCloud/addon-provider-template) - -### Add-on API template using NodeJS - -[https://github.com/Redsmin/passport-clevercloud](https://github.com/Redsmin/passport-clevercloud) \ No newline at end of file diff --git a/commons/clever-cloud-apis/add-ons-log-collector.md b/commons/clever-cloud-apis/add-ons-log-collector.md deleted file mode 100644 index 1e6901631..000000000 --- a/commons/clever-cloud-apis/add-ons-log-collector.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Add-on Log Collector -position: 3 -shortdesc: This article targets the add-on providers who want to integrate logs from their add-ons to the Clever Cloud's logging system -tags: -- developer ---- -# Add-on Log Collector - -This article targets the add-on providers who want to integrate logs -from their add-ons to the Clever Cloud's logging system. Doing this -allows the users to get their add-on's logs in the Clever Cloud's -dashboard. - -Note that, for the same reasons as the one mentioned in [Add-on API](/doc/clever-cloud-addons-api/add-ons-api) article, which you should have read if your reading these lines, if you already are a Heroku add-on provider, you should not be lost using this log collector API. - -## Send a line of log - -Log lines must be sent via https. See the following example with the `curl` command: - -```bash -$ curl -X POST "https://logs.cleverapps.io/logs" \ - --user "token:logtoken_foobar" \ - -d "72 <190>1 2013-03-27T20:02:24+00:00 hostname logtoken_foobar procid - - foo72 <190>1 2013-03-27T20:02:24+00:00 hostname logtoken_foobar procid - - bar" \ - -H "Content-Length: 150" \ - -H "Content-Type: application/logplex-1" -``` - -Let's explain this request: - -* `-X POST` - This request is obvioulsy a POST one, since you need to send new data. - -* `--user token:logtoken_foobar` - This is the basic authentication content. The user must be the string 'token', and the password must be your log token, as sent on a provisioning call. - -* `Content-Length: 150` - Length of the body. Must be set. - -* `Content-Type: application/logplex-1` - This is the expected content type. - -* `72 <190>1 2013-03-27T20:02:24+00:00 hostname logtoken_foobar procid - - foo` - This a a log line. It is expected to respect the RFC 5424 notation. You can send multiple log lines in one request. Here is the log line decrypted: - -```bash -length version time hostname logtoken procid msgid structured-data msg -``` - -This message format is documented by the [RFC 5424](http://tools.ietf.org/html/rfc5424). - -* `length` - 72 in the example. It is the length *in bytes* of the encoded log line minus the length field and the following space. It *is not* the number of chars. In our example, this is how it could be done in java: -```text -("<190>1 2013-03-27T20:02:24+00:00 " + -"hostname logtoken_foobar procid - - foo").getBytes().length -``` - -* `prival` - The priority value of the message. Here `190` means "local7.info". ([More doc](http://tools.ietf.org/html/rfc5424#section-6.2.1)) - -* `version` - The syslog protocol version. Use `1` here. ([More doc](http://tools.ietf.org/html/rfc5424#section-6.2.2)) - -* `time` - The time the log line was created. The format must follow the [RFC 3339](http://tools.ietf.org/html/rfc3339). ([More doc](http://tools.ietf.org/html/rfc5424#section-6.2.3)) - -* `hostname` - Make it your add-on id. - -* `logtoken` - The same token as in the Basic authentication password. - -* `procid` - Id of the process emitting the log. Not really used by the log collector since it's more relevant for you to use in your own log system to debug processes. - -* `msgid` - Not used, should be `-`. - -* `structured-data` - Not used, should be `-`. diff --git a/commons/clever-cloud-apis/cc-api.md b/commons/clever-cloud-apis/cc-api.md deleted file mode 100644 index 74f790bc7..000000000 --- a/commons/clever-cloud-apis/cc-api.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Clever Cloud API -position: 1 -shortdesc: Getting started with the Clever Cloud API -tags: -- developer ---- -# Clever Cloud API - -The Clever Cloud console is built on top of an API that allow you to manage your -account and products. This article will explain how to connect to this API and -use it. - -## HTTP calls - -### **Authentication** - -Clever Cloud API works with an OAuth1 based authentication. - -There are 2 supported methods for the signature: PLAINTEXT and HMAC-SHA1. -While PLAINTEXT is way easier for testing, you **should** use HMAC-SHA1 -when it comes to production. This ensures that the request is totaly verified. - -We have a [client for javascript on Github](https://github.com/CleverCloud/clever-client.js) -where you can find a lot of informations. -Especially in the [src/session.js file](https://github.com/CleverCloud/clever-client.js/blob/master/src/session.js) - -This client is being used by the Console. Also, the Console gives you a lot -of informations in the "network" panel of the devtools. If you're stuck, this -is one way for debugging. - -For the Authorization header, make sure to have something like: -```bash - Authorization: OAuth key="value", key2="value2" -``` -The ``OAuth`` and doubles quotes around values are mandatory -#### **Create consumers tokens** - -You need to create an oauth consumer token in the Clever Cloud console. -A link "Create an oauth consumer" is available under your organisation's -addons list. All created consumers will appear below that link, like your -applications and addons. - -These consumers allow you to register an application. By creating a consumer, -users will be able to grant (or decline) privileges for your application. -For example, the Clever Cloud Console is using an oauth consumer. -You (most of the time) give it full access to manage your account. - -You need to set a callback URL, this is the url your user will be redirected -after he has been authenticated. - -#### **Get a request token** - -You have to make a `POST`request to get a -[request token](https://www.clever-cloud.com/doc/api/#!/oauth/oauth_request_token_post) -to the API. - -#### **Get the authorisation URL** - -Ask the API for the [authorisation URL](https://www.clever-cloud.com/doc/api/#!/oauth/oauth_authorize_get) -and go to this URL with a browser. Log in with your account and it will send you -to the callback URL. - -#### **Get the verifier token** - -In the callback URL you have the verifier token : - -`http://www.example.com/callback?oauth_verifier=` - -Where `` is your token. - -#### **Get the access token** -Make a `POST` request to get the -[access token](https://www.clever-cloud.com/doc/api/#!/oauth/oauth_access_token_post) - with your request token and the verifier. -You can use this access token to make OAuth1 signed requests. - -More information about [OAuth dance](http://oauth.net/core/1.0/#anchor9). - -### **API request links** - -All the API links are referenced in a swagger documentation. - - * [https://www.clever-cloud.com/doc/api/](https://www.clever-cloud.com/doc/api/) - -The base URL for the API is : - - * `https://api.clever-cloud.com/v2/` - -## WebSocket API requests - -### **Connection protocol** - -Clever Cloud API can handle WebSocket-Security requests for the logs or events. -To connect to a WebSocket API URL follow this guide. - - * Take a URL in the API for the WebSocket. - * Ex : `https://api.clever-cloud.com/v2/events/event-socket` - * Sign the OAuth request with this URL. - * Replace `https://` by `wss://` - * `wss://api.clever-cloud.com/v2/events/event-socket` - * Connect to this URL in WebSocket - * When the WebSocket connection is opened, you need to send the OAuth1 header in -this format : -```json -{ - "message_type": "oauth", - "authorization": "" -} -``` -You need to replace `` by the signed OAuth1 header. - -### **Available WebSocket endpoints** - -#### **Logs-Socket** - -[This endpoint](https://www.clever-cloud.com/doc/api/#!/logs/logs_logs-socket_appId_get) -allow you to receive real-time logs of an application via WebSocket. - -#### **Events** -[This endpoint](https://www.clever-cloud.com/doc/api/#!/events/events_event-socket_get) -allow you to receive a stream of events emitted on your account. -Events like git push, add or remove an application / addon, deployments success / failed -are available. diff --git a/commons/clever-cloud-overview/add-application.md b/commons/clever-cloud-overview/add-application.md deleted file mode 100644 index 508217693..000000000 --- a/commons/clever-cloud-overview/add-application.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Deploying an application -position: 4 -shortdesc: Step by step guide to deploy an application on Clever Cloud. -tags: -- dashboard-setup ---- - -# Deploying an application - -There are two steps in this section: application creation (requiring actions from -dashboard) and application deployment (requiring actions from git for your FTP access). - -## Create an application - - 1. First, select the proper organization you want to add to application to. Then, - click on the **Add an application** button, in the **Organization Manager** panel. - This starts the application creation wizard. If your account has been linked to - GitHub, you can select a repository from your GitHub account. - - 2. Then select the language or the framework you need: -
- - 3. *Optional:* in case of PHP or static applications, you can choose between FTP - and Git deployment. - - 4. In the next step, you will be prompted to select your scaling configuration. - If you need help to configure your scaling options, please refer to - [the dedicated section](/doc/clever-cloud-overview/scaling/). - -
- -
- - 5. Enter the name and description of you app. - - 6. *Optional*: [add an add-on](/doc/addons/clever-cloud-addons/) to your app. - -## Git Deployment - -*To deploy via Git, you need it installed on your machine. You can find more -information on Git website: [git-scm.com](http://git-scm.com)* - -*Note:* During the deployment, the .git folder is automatically deleted to avoid security problems. If you need to know -which version is used on the server please use the `COMMIT_ID` [environment variable](/doc/admin-console/environment-variables/). - -Follow these steps to deploy your application: - - 1. Get the git deployment url in the application information page, who looks like: - ``git+ssh://git@push..clever-cloud.com/.git``. - - 2. In your terminal, go to your application repository. If you do not already track your app with git, start by typing: - - ```bash - $ git init - $ git add . - $ git commit -m "first commit" - ``` - - 3. Then, link your local repository to Clever Cloud by providing the Git remote url: - - ```bash - $ git remote add - ``` - - 4. Push your application to Clever Cloud: - - ```bash - $ git push :master - ``` - -
-

Warning:

-

You can only push to the master branch for deployment. - Trying to push to another branch will trigger an error.

-

In order to push to master from a non-master local branch, use this syntax:

- 
git push <remote> <your branch>:master
-
- - Checkout your application **logs** in the dashboard to **monitor the deployment**. - -
-

Troubleshooting:

-

If the remote asks you for a password right after a git push attempt, this is may be due to a SSH Key misconfiguration. -
Add your SSH key to your profile here: - https://console.clever-cloud.com/users/me/ssh-keys

-

The full tutorial about adding SSH key is here: Adding SSH keys

-
- -### Automatic Deployment with GitHub - -If you want to enable automatic deployment, follow these easy steps: in your application -information tab, if you have created your application from GitHub, you will -see a new field: a secret for your GitHub application’s settings. Here are the -steps to trigger a deploy on Clever Cloud from a push to GitHub: - - 1. Grab this secret and go to the GitHub repository settings. - - 2. Click on “add a service” and select “Clever Cloud” from the list. - - 3. Paste the secret - -From now on, a push to your GitHub repo will also trigger a Clever Cloud deployment. - -Note that only a push on master will trigger the deployment. - -
-

Warning:

-

You can't directly push to an application created on Clever Cloud as a Github app : in this case, only the automatic deployment from Github is henceforth allowed.

-

If you try to push to Clever Cloud, as you would do for a non-github app, you will get the following error :

- 
fatal: '/data/repositories/<app_id>.git' does not appear to be a git repository
-

Indeed, no git repository is created on Clever Cloud because the application is directly cloned from Github.

-

If you have to push directly to a repo in order to deploy an application (eg if you deploy from a CI), then create a non-github app.

-
- -Private GitHub repositories are also supported: you only have to add the CleverCloudDeployer user as a collaborator to your private repository. Note that read only access is sufficient. - -Caution: in Github, private repositories in an ordinary user account are an all-or-nothing deal: either someone has full read/write access (i.e., they're a collaborator) or they have no access. However, if you set up an organization, create the repo under the aegis of the organization, and then add the collaborator, you have much more fine-grained control (including giving read-only access to a private repository). - -## FTP Deployment - -It is possible to deploy via FTP with PHP and static applications. - -To deploy via FTP, you need an FTP software installed on your machine. [Filezilla](https://filezilla-project.org/) is -one of them. - -When you have chosen to deploy your application via FTP, a [FS Bucket](/doc/addons/fs_buckets/) has been created with an ID -matching your application's ID. You will find the FTP credentials in the configuration tab of this particular FS Bucket. - -[More documentation about Filezilla.](https://wiki.filezilla-project.org/FileZilla_Client_Tutorial_%28en%29) - - -
-

Warning:

-

An FTP application is automatically started once the application is created, even if no code has been sent.

-
- - -
-

Our advice

-

FTP deployment is ok for small websites but not for large ones. We strongly -recommend you to use Git deployment for large PHP websites.

-
diff --git a/commons/clever-cloud-overview/common-application-configuration.md b/commons/clever-cloud-overview/common-application-configuration.md deleted file mode 100644 index 2f2e5acb2..000000000 --- a/commons/clever-cloud-overview/common-application-configuration.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Common apps configuration -position: 5 -shortdesc: Learn how to do some basic steup configuration to get started -tags: -- dashboard-setup ---- - -# Configuration items available on every instance type. - -Each instance type (php,java,python,go,ruby…) has its own configuration. However, some of -these configuration items can be applied to any instance. - -## Private SSH key - -If your company manages its own artifacts in a private repository (like, you can only -access them via git+ssh or sftp), and you need a private key to connect to the server, you -can commit them in your application's Clever Cloud repository and then add the -`clevercloud/ssh.json`. - -The content of this file is pretty straight-forward: - -```javascript -{ - "privateKeyFile": "path/to/file" -} -``` - -The `privateKeyFile` field must be a path to a SSH private key. The path must be relative -to the root of your repository. e.g. if your private key file is in the `clevercloud` -folder and is named `my_key`, the `privateKeyFile` field will be `"clevercloud/my_key"`. - -That key will be installed as `~/.ssh/id_rsa` before the start of the build. So the -dependency manager will use it to fetch libs only accessible by ssh. - -*NB: Please provide a key without pass phrase, or the system will be unable to unlock it* - -## Post deploy hook - -If you need to perform additional actions after your app is started, you can define a -"postDeploy" hook in your `.json` file (e.g. if you are deploying a ruby app, -put it in your `ruby.json` file): - -```javascript -{ - "hooks": { - "postDeploy": "./clevercloud/myScript" - } -} -``` - -The `postDeploy` field must contain the path to a script, relative to the root of your -repository. The script file **MUST** have execution right set. - -In the example above, the script is a file named `myScript` in the `clevercloud` folder. -That is, right beside the `.json` file. diff --git a/commons/clever-cloud-overview/intro-to-addons.md b/commons/clever-cloud-overview/intro-to-addons.md deleted file mode 100644 index e8b26e09e..000000000 --- a/commons/clever-cloud-overview/intro-to-addons.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Intro to add-ons -position: 2 -shortdesc: Add-ons allows you to extend your apps with databases, search engines, monitoring etc. -tags: -- dashboard-setup -- addons ---- - -# Intro to add-ons - -Applications often requires one or more services in addition to the runtime itself. For example, you may need databases -for storing data, cache engine for performances, long time log storage, etc... - -These services are called add-ons. There is a great number of them, based on many technologies, and developed by many -companies, or communities. It could be a database, a cache system or a search engine. - -## Clever Cloud add-ons - -Some add-ons are developed and maintained by Clever Cloud, exclusively. - -* Cellar -* File System Buckets -* MongoDB -* MySQL -* PostgreSQL -* Redis -* Redsmin - -Add-ons from external partners will be released shortly. - -## Adding an add-on - -To add an addon, please refer to the [dedicated section](/doc/addons/clever-cloud-addons/). - -## Billing - -Each add-on is billed monthly. The price showed for each plan does not include taxes. diff --git a/commons/clever-cloud-overview/intro-to-apps.md b/commons/clever-cloud-overview/intro-to-apps.md deleted file mode 100644 index cda63b2c2..000000000 --- a/commons/clever-cloud-overview/intro-to-apps.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Intro to Apps -position: 1 -shortdesc: A quick overview of the concept of application on Clever Cloud -tags: -- dashboard-setup ---- - -# Introduction to Applications - -## Application's definition - -An application is defined on Clever Cloud by the following elements: - -* a dedicated language/framework -* a deployment method (FTP and/or Git) -* RAM and CPU consumption, depending on the language or framework used -* an optional configuration file you've added to your project - -If one of these elements is missing, Clever Cloud can't deploy your application properly (except the configuration file, optional in some cases). - -Available languages are listed below: - -* [Go](/doc/go) -* [Java](/doc/java) [Play Framework 1 & 2, Maven, War files… ] -* [Node.js](/doc/nodejs) -* [PHP](/doc/php) -* [Python](/doc/python) -* [Ruby](/doc/ruby) -* [Scala](/doc/scala) - - -## How it works - -When an application is pushed, the platform receives it. It then checks the resources’ requirements. If they are complete, the deployment is launched. When finished and successful, the application is up and running. - -The log system retrieves all output from the application and displays it in your admin console. diff --git a/commons/clever-cloud-overview/pricing.md b/commons/clever-cloud-overview/pricing.md deleted file mode 100644 index 38da86645..000000000 --- a/commons/clever-cloud-overview/pricing.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -title: Pricing -position: 1 -shortdesc: Pricing table of Clever Cloud's runtimes -tags: -- billing ---- -# Billing -Clever Cloud billing is counted every 10 minutes. The following prices are based on the language you use. - - -## Per hour applications billing rates - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SizeRAMvCPUCost per hour
XS1 GB10.02 €
S1 GB20.04 €
M4 GB40.15 €
L8 GB60.25 €
XL16 GB80.45 €
-
- -## Clever Cloud Native Add-ons pricing - -The following add-ons are the production databases maintained internally by Clever Cloud. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
PostgreSQL pricing plans
NameCache (Memory)DiskConn. limitPrice /month
DevSHARED256 MB5Free
SSHARED1 GB1010 €
M1 GB100 GB7530 €
L8 GB450 GB500240 €
XL32 GB600 GB750700 €
XXL64 GB900 GB10001200 €
-
-
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MySQL pricing plans
NameCache (Memory)DiskConn. limitPrice /month
DevSHARED10 MB5Free
SSHARED256 MB1015 €
M1 GB10 GB7545 €
L2 GB200 GB500300 €
XL8 GB500 GB7501600 €
XXL16 GB900 GB10002200 €
- - -
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
MongoDB pricing plans
NameMemoryStoragePrice /month
SShared500 MBFree
SM2 GB30 GB75.00 €
M4 GB100 GB150.00 €
- - -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Redis pricing plans
NameSizeConnection limitDatabasesPrice /month
DEV10 MB10100Free
S100 MB1001008.00 €
M250 MB10010013.00 €
L500 MB25010043.00 €
XL1 GB50010078.00 €
XXL2.5 GB500100190.00 €
- -
-
- - - - - - - - - - - - - - - - - - - -
FS Buckets pricing plans
NameMountsStoragePrice /month
BasicUnlimitedFirst 100 MBFree
BasicUnlimitedPer 1GB1.50 € -
- -
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Cellar pricing plans
Storage
First 100MBFree
First 1TB20.48 € / TB / mo -
First 25TB15.36 € / TB / mo
First 50TB10.24 € / TB / mo
Traffic (outbound)
First 100MBFree
First 10TB0.09 € / GB / mo
First 40TB0.07 € / GB / mo
\ No newline at end of file diff --git a/commons/clever-cloud-overview/scaling.md b/commons/clever-cloud-overview/scaling.md deleted file mode 100644 index 553979a2d..000000000 --- a/commons/clever-cloud-overview/scaling.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Scaling -position: 3 -shortdesc: This article introduces the wat Clever Cloud bills apps and services -tags: -- scaling-tips -- developer ---- - -# Application scalling - -When your application is running, you don't have the same number of user all the time. During an event for example, -the number of users can grow up and the loading on the server increase. If too many requests are done on your -server in the same time, the response time will increase and could slow down your website. - -To avoid this problem and keep a fast website, the main solution is to deploy more **Scalers** of your application to -support the loading. That's what is scalling : adapting automatically the number of **Scalers** and there size to feet the -loading of your application, without action from you. - -Clever Cloud gives you the ability to fine tune your application's scaling by managing both horizontal and vertical -scaling. These two parameters can be combined to adapt to your needs. - -## What is a Scaler? - -A **Scaler** is the Clever Cloud "instance". It is an individual container hosting your application. They are not virtual -machines and are independent. A Scaler is defined by two factors: RAM and CPU. - -With the Scalers, Clever Cloud gives you the ability to scale your application **up and down** with **two non -exclusive methods**: horizontal and vertical scaling. - -### Enable scalability - -To enable the scalability of your application, open the [console](https://console.clever-cloud.com/) and go in the -"scalability" section of your application. Then, enable the auto-scalability. - -## Horizontal scaling - -In case of large traffic, we detect a high load on your application and spawn **another instance in parallel**. -It gives more power to your application by setting up another identical application. Both will run in parallel with load -balancing. And so on. - -This process is exactly the opposite when the **load decreases**. A Scaler is removed and so on till a **minimum -reasonable level** is reached. - -The following scheme depicts a Scaler replication in case of a load increase: - -
- -
- -You can manage the range of Scalers you consider in the application configurator. The range is from 1 to 20. - -
- -
Horizontal scaling: the amount of scaler will increase, not the scaler size.
-
- -## Vertical scaling - -In case of large traffic, we detect a high load on your application and set up **a new larger Scaler**. - -In case of low traffic, we detect a low load and set up **a new smaller Scaler**. - -You give more power to your application by setting up a larger instance that will replace the previous one. The more the -load, the larger the instance. - -The following scheme depicts a larger Scaler replacement in case of a load increase: - -
- -
- -You can choose the type of Scalers you consider of just let Clever Cloud choose for you: - -
- -
Vertical scaling: the amount of scalers will not increase in this configuration, but the scaler size will, - from S to XL.
-
- -## Combination of both scalings - -When both scalings are set up, **vertical scaling** is privileged over **horizontal scaling**. In the case you set the -vertical scaling from S to L, and the horizontal scaling from 2 scalers to 4 scalers, Clever Cloud will firstly up -the size of the 2 scalers already launched. - -If the 2 initials scalers are in there maximum size, Clever Cloud will launch new scalers with the maximum size of scalers. -This is how it'll be done : - -2-S => 2-M => 2-L => 3-L => 4-L. diff --git a/commons/get-help/faq.md b/commons/get-help/faq.md deleted file mode 100644 index f132072a2..000000000 --- a/commons/get-help/faq.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: FAQ -position: 3 -tags: -- support ---- - -# Clever Cloud FAQs - -## What is a Scaler? - -A scaler is an individual container hosting your app. You can attribute one or more Scalers to your apps. Scalers comes in many sizes based on each language requirement from XS to XXXL. - -Each [scaler](#def-scaler) is given a fixed set of resources, depending on the chosen language. A Java [scaler](#def-scaler) will have more RAM than a PHP [scaler](#def-scaler). -The way you scale an application is by assigning it new [scalers](#def-scaler). -When enabling auto-scalability, you have to set a minimum and a maximum of active [scalers](#def-scaler) in your apps settings. This way you can precisely control your monthly fee. - -## What languages and frameworks are supported by Clever Cloud? - -Currently Clever Cloud supports: - -* Java (Play Framework 1 & 2, Maven, War files… ) -* Node.js -* PHP ([see frameworks and CMS](/doc/php/php-apps/#frameworks-and-cms)) -* Python (Django) -* Ruby -* Go - -## How many applications can I create with Clever Cloud? - -As much as you want. We've not set a limited number of apps by developer. - -## How can I disable one of my existing applications? - -Log in with your account to [console.clever-cloud.com](https://console.clever-cloud.com), and select the appropriate organisation and app in the head-bar. Then click on **Configuration** in the left pane to stop your app. It will be un-deployed, and ready for a new start without pushing your app via Git or FTP again. - -## What type of content is allowed on Clever Cloud? - -Please refer to our Terms and Conditions, article 6, *Obligations and responsibilities of the client*. - -## How is the current load report in my application's admin console generated? - -We use custom probes to monitor: - -* hardware's components usage -* databases read / write / update operations - -## How do I authenticate members of my organisation? - -Log in with your account to [console.clever-cloud.com](https://console.clever-cloud.com), and select the appropriate organisation in the head-bar. Then click on **Configuration** in the left pane and select **Members**. You'll see a list of the organisation's members. If your are an admin, you can revoke or grant apps permissions. - -## How do I report an application that is in violation of your Terms and Conditions? - -To report an application that is in violation of the Clever Cloud's Terms and Condition, please contact us at . - -We will investigate and contact the application's owner over the violation if needed. - -## Does Clever Cloud support SSL (HTTPS)? - -Absolutely! For now, it's not automatic. Contact us at , we will enable it for you. Custom SSL certificates will be available directly in Clever Cloud very soon. - -## I'd like to map my app to http://mydomain.com. - -See [Custom Domain Names](/doc/admin-console/apps-management/#custom-domain-names) section of Apps Management. - -## How do I define cron jobs for my application? - -See [Cron Configuration File](/doc/tools/crons/) for more information. - -## How many active requests can my app serve at one time? - -There are two possibilities, according to the scalability settings you've opted for. - -1. You have set a single [scaler](#def-scaler) : the maximum active requests depends on your [scaler's](#def-scaler) -computing limits. -2. You have set auto-scalability, new [scalers](#def-scaler) will be started as long as your app need more resources -(until it reaches the maximum number of [scalers](#def-scaler) you have defined). - -## How to know if a user comes from a secure connection? - -All connections are handled by load-balancers ahead of your applications and forwarded in plain http, you cannot rely on the server port to know the scheme used by the user. - -Instead of it you can use the `X-Forwarded-Proto` HTTP header to get the information, it is set to '*http*' or '*https*'. - -
-

Note for Play Framework! 1.2.x users

-

In order to use `request.secure` instead of accessing the header, you must add `XForwardedSupport=all` in your *application.conf*.

-
- -
-

Note for Play Framework! 2.3+ users

-

In order to use `request.secure` instead of accessing the header, you must add `trustxforwarded=true` in your *application.conf*.

-
- - -## How to get the user's IP address? - -All connections are handled by load-balancers ahead of your applications -and forwarded in plain http. - -So if you get the `REMOTE_ADDR` or `Client-IP` header, you will only -get the IP of the front load balancer that forwarded the user request. - -Instead of these headers you need to use the `X-Forwarded-For` HTTP -header, which is set by our load balancer to the client's address. Please -remember that it is a list, containing the address of each proxy the request -has been through, if the said proxy has modified the `X-Forwarded-For` -header: [Read the Wikipedia page for more informations](https://en.wikipedia.org/wiki/X-Forwarded-For) - -## When my application runs on multiple instances, how can I differentiate them? - -If your application needs to differentiate all the running nodes internally, -you can use the `INSTANCE_NUMBER` environment variable. - -For example, if 3 instances are running for your application, this environment variable will -contain `0` on the first, `1` on the second and `2` on the third. - -## I need a private ssh key to fetch my private dependencies. How do I do that? - -If your company manages its own artifacts in a private repository (like, you can only -access them via git+ssh or sftp), and you need a private key to connect to the server, you -can commit them in your application's Clever Cloud repository and then add the -`clevercloud/ssh.json`. - -The ssh.json file is documented in the [common configuration page](/doc/clever-cloud-overview/common-application-configuration/#private-ssh-key) - -## I got a `Unsupported major.minor version` error. How can I fix it? - -If you get this error on a java (or any JVM language) application, it means that your application requires a specific version of java. -By default, java 7 is used, but you can change it. Please head up to [select java version](/doc/java/select-java-version/) -for more information. diff --git a/commons/get-help/reference-environment-variables.md b/commons/get-help/reference-environment-variables.md deleted file mode 100644 index 4369fdcc7..000000000 --- a/commons/get-help/reference-environment-variables.md +++ /dev/null @@ -1,802 +0,0 @@ ---- -title: Environment Variable Reference -position: 3 -tags: -- support ---- - -# Environment Variable Reference - -Source environment variable in a cron, create a script that starts with: source /home/bas/applicationrc - -## Applications - -### Commons to all Applications - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
[CC_TROUBLESHOOT](doc/clever-cloud-overview/troubleshoot-mode/)Enable debug log level, will also keep the VM up after failure for 15 minutes so you can SSH and debug. Don't forget to cancel deployment if you push a new commit.`false`
CC_WORKER_COMMANDCommand to run in background as a worker process.
CC_PRE_BUILD_HOOKRan before the dependencies are fetched. If it fails, the deployment fails.
CC_POST_BUILD_HOOKRan after the project is built, and before the cache archive is generated. If it fails, the deployment fails.
CC_PRE_RUN_HOOKRan before the application is started, but after the cache archive has been generated. If it fails, the deployment fails.
CC_RUN_SUCCEEDED_HOOKRan once the application has started successfuly.
CC_RUN_FAILED_HOOKRan once the application has failed to start.
CACHE_DEPENDENCIESEnable caching of your build dependencies to speed up following builds.`false`
ENABLE_METRICSBETA: Enable metrics collection, Contact support.`false`
[IGNORE_FROM_BUILDCACHE](doc/admin-console/environment-variables/#settings-you-can-define-using-environment-variables)Allows to specify paths to ignore when the build cache archive is created.
[INSTANCE_NUMBER](doc/admin-console/environment-variables/#special-environment-variables)Allows your application to differentiate each running node on the application level.Provided
INSTANCE_TYPEWhether this instance is a "build" instance or a "production" instance.Provided
APP_FOLDERFolder in which the application is located (inside the git repository)Provided
APP_IDThe ID of your Clever Cloud applicationProvided
APP_HOMEThe absolute path to your application folderProvided
CC_DEPLOYMENT_IDProvided
COMMIT_IDThe git commit id currently deployedProvided
- - -### Docker - -[Docker Documentation](doc/docker/) - - - - - - - - - - - - -
Name
Description
Default value
CC_MOUNT_DOCKER_SOCKETSet to true to access the host Docker socket from inside your container.`false`
- -### Go - -[Go Documentation](doc/go/) - - - - - - - - - - - - -
Name
Description
Default value
CC_GO_PKGMakes the deployer run go get ${CC_GO_PKG} instead of go get <app_id>.
- -### Haskell - -[Haskell Documentation](doc/haskell/) - - - - - - - - - - - - -
Name
Description
Default value
CC_RUN_COMMANDCustom command to run your application.
- -### Java - -[Java Documentation](doc/java/) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
CC_SBT_TARGET_DIR
GRADLE_DEPLOY_GOALDefine which gradle goals to run during build.
JAVA_VERSIONChoose the JVM version between `7` or `8`.`8`
MAVEN_DEPLOY_GOALDefine which maven goals to run during build.
NUDGE_APPID
PLAY1_VERSIONDefine which play1 version to use between `1.2`, `1.3` and `1.4`
SBT_DEPLOY_GOALDefine which sbt goals to run during build.`stage`
- -### NodeJS - -[NodeJS Documentation](doc/nodejs/) - - - - - - - - - - - - - - - - - - - - - - - - - - - https://www.clever-cloud.com/doc/nodejs/nodejs/#supported-package-managers -
Name
Description
Default value
CC_NODE_START_GOALDefines which node scripts to run`start`
CC_RUN_COMMANDDefine a custom command.Exemple for Meteor: `node .build/bundle/main.js <options>`
NODE_BUILD_TOOLChoose your build tool between `npm` and `yarn``npm`
NPM_TOKENPrivate repository token for npmjs.com
- -### PHP - -[PHP Documentation](doc/php/) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
ALWAYS_POPULATE_RAW_POST_DATA
CC_LDAP_CA_CERT
LDAPTLS_CACERT
ENABLE_REDIS`false`
HTTP_TIMEOUTDefine a custom HTTP timeout`180`
MAX_INPUT_VARS
PHP_VERSIONChoose your PHP version between `5.6`, `7` and `7.1``7`
[SESSION_TYPE](doc/php/php-apps/#use-redis-to-store-php-sessions)Choose `redis` to use it as session store
SOCKSIFY_EVERYTHING
USE_SOCKS`false`
- -### Python - -[Python Documentation](doc/python/) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
CC_PYTHON_CELERY_LOGFILERelative path to your Celery logfile: `/path/to/logdir`
CC_PYTHON_CELERY_MODULESpecify the Celery module you want to start: `mymodule`
CC_PYTHON_CELERY_USE_BEATSet to `true` to activate Beat support
CC_PYTHON_MODULESelect which module you want to start: `mymodule:app`
CC_PYTHON_USE_GEVENTSet to `true` to enable Gevent
HARAKIRITimeout (in seconds) after which an unresponding process is killed`180`
PYTHON_BACKENDChoose the Python backend to use between `uwsgi` and `gunicorn``uwsgi`
PYTHON_VERSIONChoose the Python version between `2.7` and `3.6`
PYTHON_SETUP_PY_GOALCustom setup goal to be launch after `requirements.txt` have been installed
STATIC_FILES_PATHRelative path to where your static files are stored: `path/to/static`
[STATIC_URL_PREFIX](doc/python/python_apps/#manage-your-static-files)The URL path under which you want to serve static file, usually `/public`
STATIC_WEBROOT
UWSGI_INTERCEPT_ERRORS
[UWSGI_ASYNC](doc/python/python_apps/#uwsgi-asynchronous-non-blocking-modes)Number of cores to use for uWSGI asynchronous/non-blocking modes
UWSGI_ASYNC_ENGINESelect the asynchronous engine for uWSGI (optional)
WSGI_WORKERSNumber of workers. (Defaut: automatically setup with the scaler size)
WSGI_THREADSNumber of threads per worker. (Defaut: automatically setup with the scaler size)
WSGI_BUFFER_SIZEBuffer size (in bytes) for uploads.`4096`
WSGI_POST_BUFFERINGMaximal size (in bytes) for the headers of a request. `4096`
ENABLE_GZIP_COMPRESSIONSet to `true` to gzip-compress the output of uwsgi
NGINX_READ_TIMEOUTRead timeout in seconds`300`
- -### Ruby - -[Ruby Documentation](doc/ruby/) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
CC_RACKUP_SERVER
HARAKIRITimeout (in seconds) after which an unresponding process is killed`180`
RACK_ENV
RAILS_ENV
RUBY_VERSIONChoose the Ruby version to use.
STATIC_FILES_PATHRelative path to where your static files are stored: `path/to/static`
[STATIC_URL_PREFIX](doc/python/python_apps/#manage-your-static-files)The URL path under which you want to serve static file, usually `/public`
STATIC_WEBROOT
UWSGI_INTERCEPT_ERRORS
[UWSGI_ASYNC](doc/python/python_apps/#uwsgi-asynchronous-non-blocking-modes)Number of cores to use for uWSGI asynchronous/non-blocking modes
UWSGI_ASYNC_ENGINESelect the asynchronous engine for uWSGI (optional)
WSGI_WORKERSNumber of workers. (Defaut: automatically setup with the scaler size)
WSGI_THREADSNumber of threads per worker. (Defaut: automatically setup with the scaler size)
WSGI_BUFFER_SIZEBuffer size (in bytes) for uploads.`4096`
WSGI_POST_BUFFERINGMaximal size (in bytes) for the headers of a request. `4096`
ENABLE_GZIP_COMPRESSIONSet to `true` to gzip-compress the output of uwsgi
NGINX_READ_TIMEOUTRead timeout in seconds`300`
- -### Rust - -[Rust Documentation](doc/rust/) - - - - - - - - - - - - -
Name
Description
Default value
RUSTUP_CHANNELRequire a specific channel version with `beta`, `nightly`, or a specifiv version like `1.13.0`
- -## Addons - -### FS Bucket - -[FS Bucket Documentation](doc/addons/fs_buckets/) - - - - - - - - - - - - - - - - - -
Name
Description
Default value
APP_BUCKET_HOST
CC_FS_BUCKET
- -### MongoDB - -[MongoDB Documentation](doc/mongodb/) - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
MONGODB_ADDON_DBProvided, Generated upon creation
MONGODB_ADDON_PASSWORDProvided, Generated upon creation
MONGODB_ADDON_USERProvided, Generated upon creation
- -### MySQL - -[MySQL Documentation](doc/mysql/) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
ADDON_API_HOSTProvided, Generated upon creation
EXISTING_BACKUP_URLProvided, Generated upon creation
INTERNAL_ADDON_AUTH_PASSProvided, Generated upon creation
MYSQL_ADDON_DBProvided, Generated upon creation
MYSQL_ADDON_PASSWORDProvided, Generated upon creation
MYSQL_ADDON_ROLEProvided, Generated upon creation
MYSQL_ADDON_USERProvided, Generated upon creation
- -### PostgreSQL - -[PostgreSQL Documentation](doc/postgresql/) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
ADDON_API_HOSTProvided, Generated upon creation
EXISTING_BACKUP_URLProvided, Generated upon creation
INTERNAL_ADDON_AUTH_PASSProvided, Generated upon creation
POSTGRESQL_ADDON_DBProvided, Generated upon creation
POSTGRESQL_ADDON_PASSWORDProvided, Generated upon creation
POSTGRESQL_ADDON_ROLEProvided, Generated upon creation
POSTGRESQL_ADDON_USERProvided, Generated upon creation
- -### Redis - -[Redis Documentation](doc/redis/) - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
REDIS_HOSTProvided, Generated upon creation
REDIS_PORTProvided, Generated upon creation
REDIS_PASSWORDProvided, Generated upon creation
REDIS_TOKEN
- - -### New Relic - - - - - - - - - - - - - - - - - -
Name
Description
Default value
NEWRELIC_APPNAME
NEWRELIC_LICENSE
- - - -### Socks - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
SOCKS_ADDON_HOST
SOCKS_ADDON_PORT
SOCKS_ADDON_PRIVATE_KEY
- -### VPN - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name
Description
Default value
VPN_ADDON_CRT
VPN_ADDON_CACRT
VPN_ADDON_KEY
VPN_ADDON_HOST
VPN_ADDON_PORT
VPN_ADDON_TAKEY
VPN_TARGETS
diff --git a/commons/get-help/support.md b/commons/get-help/support.md deleted file mode 100644 index b2678cf13..000000000 --- a/commons/get-help/support.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Support -position: 1 -tags: -- support ---- - -# Support - -We provide basic support free-of-charge to all our users, even those who are not paying customers. - -## Clever Cloud Help - -Seek help by querying us by email, allowing you to quickly gain answers to your Clever Cloud specific questions and open a ticket directly with our support staff. We will respond to your email within a few hours, or two business days in the worst case. - -* - -## Live Chat - -You can find in the console a button to start a live chat with one of our engineers. Feel free to use it when this service available, from 10am to 6pm CEST+2 during open business days. - -## Critical application support - -Clever Cloud offers a premium support option providing 24x7 a direct line to our team of support engineers. Our team’s focus is investigating and solving new problems, getting feedback on the service and working hard to improve the core service. - -Get more information and contact our sales team: - -* - diff --git a/commons/get-help/troubleshooting.md b/commons/get-help/troubleshooting.md deleted file mode 100644 index 38e996f67..000000000 --- a/commons/get-help/troubleshooting.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Troubleshooting -position: 4 -tags: -- support ---- - -## Troubleshooting - -### Common Technical Problems - - -
-
- -
-instance -
-
Git and File Persistence
- -
-
- -
-instance -
-
-Error about Empty Repository -
- -
-
- -
-instance -
-
-SSH: Password is Asked -
- -
-
- -
-instance -
-
- Node failed to deploy -
- -
-
-

- -#### Git and File Persistence - -> "Why are my files disappearing after an application restart?” - -Clever Cloud use Git to transfer your code and application's assets from your local host to your scaler. If your application writes files on the local file system, those files are not committed: so you can't save these files from a instance to an other. - -For most of Cloud providers, the use of the file system is not a good practice. But we know it could be sometimes pretty useful. That's why we provide an on-demand file system, easily pluggable to your app. In that case, your files will not be stored on the Git file system, but on a clustered file system, dedicated to it, accessible via FTP. This is the FS Bucket add-on. - -Setup FS Bucket for your app is kinda straightforward, because it consist in add a simple Json file at the root of your application. - -The Json contains two parameters: the ID of the FS Bucket, and the path you want to use as a FS. - -*Related page: [File System buckets](/doc/addons/clever-cloud-addons/#fs-buckets-file-system-with-persistance/).* - - -#### Error about Empty Repository - -> “Logs are telling me \"warning: You appear to have cloned an empty repository\"” - -This usually means that you created an application and asked to start it in the console without having pushed to it before. - -*You are not working on the master branch and pushed your branch to Clever Cloud* - -Clever Cloud uses the master branch to deploy your application but this does not mean that you cannot use another one on your computer. -The only thing that differs if you use another branch than the master one on your computer is that you need to explicitly tell that Clever Cloud needs to consider your branch as the master one. - -```bash -$ git push :master -``` - -If you called the Clever Cloud repository "clever" and your local branch is "production", this becomes - -```bash -$ git push clever production:master -``` - -*Related page: [Deploy an application](/doc/clever-cloud-overview/add-application/).* - -#### Error about not being a git repository - -> “I get errors telling me that it's not a git repository, what does it mean? - -This can mean several things, depending on the exact error message - -*fatal: Not a git repository (or any of the parent directories)* - -This means that the folder in which you are is not a git repository. -Please refer to our "git deployment" documentation for how to set it up properly. - -*fatal: 'clever' does not appear to be a git repository* - -"clever" is a name used in our examples to represent the Clever Cloud servers. -In order to be able to use the same name for yourself, you will add to create it like this: - -```bash -$ git remote add clever -``` - -*Related page: [Git deployment](/doc/clever-cloud-overview/add-application/)* - -#### SSH: Password is Asked - -> “When I try to push my app, the server responds by asking a password.” - -This occurs when a wrong ssh key has been entered in your Clever Cloud profile, in the dashboard. - -Most of the time, it's due to the presence of multiple ssh key, generated by 3rd party softwares, like Github for Mac. - -We strongly recommend using a single SSH key when interacting with Clever Cloud. But if you want to use multiple keys, the trick is to configure your local ssh by adding a custom Host to ~/.ssh/config (create it if it doesn't exist), generate a secondary ssh key specifically for your Clever Cloud account (e.g., ~/.ssh/id_rsa_clevercloud) and then execute ssh-add ~/.ssh/id_rsa_clevercloud from your local git project directory. - -Your `.ssh/config` should loo like this: - -```bash -#config for Clever Cloud specific key -Host ccloud - Hostname push.clever-cloud.com - User git - IdentityFile ~/.ssh/id_rsa_clevercloud -``` - -#### Node failed to deploy - -> “My Node.js application is unable to start. Logs are not helping” - -This kind of silent error may be due to the server port your have setup in your application. Make sure your app is listening on 8080. -Most of the time, this simple line could do the trick in your main JS file: - -```javascript -// Listen on port 8080 -server.listen(8080); -``` - -*Related page: [Deploy Node.js apps](/doc/nodejs/nodejs/).* diff --git a/commons/tools/crons.md b/commons/tools/crons.md deleted file mode 100644 index c5806a212..000000000 --- a/commons/tools/crons.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Running crons -position: 1 -tags: -- developer ---- - -# CRON configuration file - -The configuration file used for crontab is `/clevercloud/cron.json`. - -Here is the general syntax: - -```haskell - [ - "", - "" - ] -``` - -The string `` must use the cron format: - -```javascript -M H d m Y command -``` - -There are two restrictions about the usage of crontab on our platform: - -* The special date `@reboot` is not available since the crontab is added after the startup of the instance -* You must use the absolute path of commands - -You can use the special variable `$ROOT` to refer to the root folder of your application. - -Example of `clevercloud/cron.json` which executes the file `cron.php` every 5 minutes: - -```haskell - [ - "*/5 * * * * /usr/bin/php $ROOT/cron.php" - ] -``` - -
-

Warning:

-

All the servers are configured to use Coordinated Universal Time (UTC), please keep it in mind when configuring cron tasks to run at a specific hour.

-
- -
-

Warning:

-

We do not currently support the clustering of cron tasks, you must manage it yourself if your application requires more than one instance.

-

Also, please note that environment variables like `INSTANCE_NUMBER` are not yet injected into crons. You have to add this line at the beginning of your script: - ```bash - source /home/bas/applicationrc - ``` -

-

Once you added this line at the top of your script, you can access the directory in which your applicaiton is using `$APP_HOME`

-
- - -_* For more information about the syntax, you can check this page_ - - diff --git a/commons/tools/new-relic.md b/commons/tools/new-relic.md deleted file mode 100644 index 76d08daff..000000000 --- a/commons/tools/new-relic.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: New Relic -position: 2 -shortdesc: Configuring Newrelic on Clever Cloud -tags: -- developer ---- - -# New Relic - -[New Relic](http://www.newrelic.com/) is a software analytics company based in San Francisco, California. -New Relic's technology monitors Web and mobile applications in real-time that run in cloud, on-premise, or hybrid -environments. You can easily setup a New Relic based monitoring on your application to monitor it and find -performances problems. - -New Relic can be used on Clever Cloud with Java, NodeJS, PHP, Ruby and Scala applications. - -## New Relic for NodeJS and Ruby - -New Relic is very simple to install in a NodeJS or Ruby application as it is a simple dependency. -Install instructions for -[NodeJS](https://docs.newrelic.com/docs/agents/nodejs-agent/installation-configuration/installing-maintaining-nodejs) -and [Ruby](https://docs.newrelic.com/docs/agents/ruby-agent/installation-configuration/ruby-agent-installation) -are available in [the New Relic documentation](https://docs.newrelic.com/). - -## New Relic for Java, Scala and PHP - -To use New Relic in Java, Scala or Ruby instances, you need to configure it as it is provided directly inside the -instances. - -### Necessary information - -Before setting up your app, be sure to have a [New Relic Account](http://www.newrelic.com/). - -### Configuration - -To configure your New Relic, you have to create and add a `./clevercloud/newrelic.json` file in your project, with the -following fields: - -```javascript -{ - "license": "licenceID", - "appname": "NameOfYourApp(optional)" -} -``` - -Deploy your application on Clever Cloud with this file. A few minutes later, your application will begin sending data -to New Relic. Once we receive the data, your application will be listed on your dashboard. - - - diff --git a/commons/tools/varnish.md b/commons/tools/varnish.md deleted file mode 100644 index 58ccaaaf0..000000000 --- a/commons/tools/varnish.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Varnish as HTTP Cache -position: 3 -shortdesc: Configuring Varnish on Clever Cloud -tags: -- varnish -- caching ---- - -# Varnish - -[Varnish](https://www.varnish-cache.org/) is a HTTP proxy-cache, which works as a reverse proxy between your application -and the client. Following rules defined by the user, Varnish will cache the data of an application to reduce the load. - -## Enable Varnish for your application - -Varnish is provided by default in PHP >= 5.5 instances. To enable it, you just have to create a `varnish.vcl` file -in the `/clevercloud` folder. - -This file describes how Varnish caches your applications and how it decides to return a cached resource or not. - -
-

If you have a PHP FTP application or if your `varnish.vcl` file is on an FS Bucket, -make sure you redeploy the application for the changes to take effect.

-

The vcl 4.0; and backend section of the `varnish.vcl` configuration file are not necessary as they -are already handled by Clever Cloud.

-
- -## Varnish version / version migration - -We use **Varnish 4**. If you already have a configuration file written for varnish 3, you can use -[varnish3to4](https://github.com/fgsch/varnish3to4) to convert it to varnish 4. - -## Example files - -We provide some [examples of Varnish configuration files](https://github.com/CleverCloud/varnish-examples) that you can -use for your application. Create a `/clevercloud` folder at the root of your application if it does not exist, -rename the file to `varnish.vcl` and move it in the `/clevercloud` folder. diff --git a/content/_index.md b/content/_index.md new file mode 100644 index 000000000..354230033 --- /dev/null +++ b/content/_index.md @@ -0,0 +1,85 @@ +--- +type: docs +title: Clever Cloud Documentation +description: Documentation and guides to deploy, manage, and monitor your services on Clever Cloud +layout: hextra-home +disableSidebar: false +type: default +width: normal +aliases: +- /doc/developer +--- + +{{< hextra/hero-badge link="https://github.com/clevercloud/documentation">}} +
+ Contribute + {{< icon name="arrow-circle-right" attributes="height=14" >}} +{{< /hextra/hero-badge >}} + +
+{{< hextra/hero-headline >}} + Deploy and manage your apps + on Clever Cloud +{{< /hextra/hero-headline >}} +
+ +
+{{< hextra/hero-subtitle style="margin:.3rem 0 2rem 0">}} + Documentation and guides to deploy, + manage, and monitor your apps. +{{< /hextra/hero-subtitle >}} +
+ +
+{{< hero-button-primary text="Quickstart" link="/developers/doc/quickstart" >}} +{{< hero-button-secondary text="Explore" link="/developers/doc/" >}} +
+ +
+ +{{< hextra/feature-grid >}} + {{< hextra/feature-card + title="Environment Variables" + subtitle="Environment variables are a simple way of configuring your applications, their deployment and their behaviour." + link="/developers/doc/reference/reference-environment-variables" + class="hx-aspect-auto md:hx-aspect-[1.1/1] max-md:hx-min-h-[340px]" + image="/images/icons.png" + imageClass="hx-top-[40%] hx-left-[24px] hx-w-[180%] sm:hx-w-[110%] dark:hx-opacity-80" + style="background: radial-gradient(ellipse at 50% 80%,rgba(58, 56, 113, 0.1),hsla(0,0%,100%,0));" + >}} + {{< hextra/feature-card + title="API" + subtitle="The Clever Cloud API reference." + link="/developers/api" + class="hx-aspect-auto md:hx-aspect-[1.1/1] max-lg:hx-min-h-[340px]" + image="/images/metrics-home.png" + imageClass="hx-top-[40%] hx-left-[36px] hx-w-[180%] sm:hx-w-[110%] dark:hx-opacity-80" + style="background: radial-gradient(ellipse at 50% 80%,rgba(203, 28, 66, 0.1),hsla(0,0%,100%,0));" + >}} + {{< hextra/feature-card + title="The CLI Clever Tools" + subtitle="An official Command Line Interface for Clever Cloud." + link="/developers/doc/cli" + class="hx-aspect-auto md:hx-aspect-[1.1/1] max-md:hx-min-h-[340px]" + image="/images/brand.png" + imageClass="hx-top-[40%] hx-left-[36px] hx-w-[110%] sm:hx-w-[110%] dark:hx-opacity-80" + style="background: radial-gradient(ellipse at 50% 80%,rgba(245, 116, 97, 0.1),hsla(0,0%,100%,0));" + >}} + {{< hextra/feature-card + title="Steps by Steps Guides" + subtitle="Find detailed tutorials to deploy your favorite framework on Clever Cloud" + link="/developers/guides" + >}} + + {{< hextra/feature-card + title="Deploy an application" + subtitle="See supported languages and how to configure your app to deploy successfully" + link="/developers/doc/applications" + >}} + {{< hextra/feature-card + title="Connect your application to dependencies" + subtitle="See available add-ons such as MySQL, PostgreSQL, Redis, Mongo, Elastic…" + link="/developers/doc/addons" + >}} + +{{< /hextra/feature-grid >}} diff --git a/content/api/_index.md b/content/api/_index.md new file mode 100644 index 000000000..53a018f87 --- /dev/null +++ b/content/api/_index.md @@ -0,0 +1,27 @@ +--- +type: docs +title: API +description: Automate your workflows and connect your services to Clever Cloud using its API +aliases: +- /doc/api/ +- /doc/openapi +- /doc/clever-cloud-addons-api/add-ons-api +- /doc/clever-cloud-apis/add-ons-api +- /doc/clever-cloud-apis/cc-api +- /doc/extend/cc-api +- /doc/getting-started/openapi +- /docs/openapi +- /openapi +comments : false +--- + +{{< hextra/hero-subtitle >}} + Automate your workflows and connect your services to Clever Cloud using its API. +{{< /hextra/hero-subtitle >}} + +{{< cards >}} + {{< card link="/developers/api/howto" title="How to use our API" subtitle="Learn more about Clever Cloud API, endpoints, auth and how to access it from multiple tools." icon="api" >}} + {{< card link="/developers/api/v2" title="Base v2 Endpoints" subtitle="Our base API endpoints with users, organisations, applications, add-ons, etc." icon="endpoints" >}} + {{< card link="/developers/api/v4" title="New v4 Endpoints" subtitle="More recent API endpoints with billing, deployments, load balancers, logs, etc." icon="new" >}} + +{{< /cards >}} diff --git a/content/api/howto.md b/content/api/howto.md new file mode 100644 index 000000000..21ff6d9dc --- /dev/null +++ b/content/api/howto.md @@ -0,0 +1,114 @@ +--- +type: docs +weight: 1 +title: Clever Cloud API Overview +description: Getting started with the Clever Cloud API +tags: +- extend +keywords: +- api +- authentication +--- + +The [Clever Cloud Console](https://console.clever-cloud.com) and [Clever Tools](https://github.com/CleverCloud/clever-tools) allow you to manage your account and products with the same public API you can use for your own services and integrations. This article will explain how to connect to this API and use it. + +{{< cards >}} + {{< card link="/developers/api/v2/" title="Base v2 Endpoints" subtitle="Our base API endpoints with users, organisations, applications, add-ons, etc." icon="endpoints" >}} + {{< card link="/developers/api/v4/" title="New v4 Endpoints" subtitle="More recent API endpoints with billing, deployments, load balancers, logs, etc." icon="new" >}} +{{< /cards >}} + +## Request the API + +Clever Cloud's REST API offers two authentication mechanisms to meet different integration needs: + +* **API tokens** provide a straightforward way to authenticate requests on behalf of a specific user. These tokens operate similarly to passwords and should be handled with appropriate security measures. API tokens are ideal for personal scripts, CLI tools, and scenarios where you're accessing your own resources. Use them to request the API Bridge: https://api-bridge.clever-cloud.com + +* **OAuth 1** is designed for third-party applications that need to access Clever Cloud resources on behalf of their users. This authentication flow allows applications to request permissions from users without requiring direct access to their credentials. OAuth 1 is recommended for public applications, services that integrate with multiple user accounts, or any scenario where user delegation is required. + +Choose the authentication method that best aligns with your specific integration requirements and security considerations. + +### API tokens + +Clever Cloud Console allows you to easily create and manage API tokens. + +![Manage API tokens in Clever Cloud Console](/images/console-api-tokens.webp) + +[Clever Tools](https://github.com/CleverCloud/clever-tools) provides a `clever tokens` set of commands. This feature needs to be enabled: + +```bash +clever features enable tokens +clever tokens create "CI job Foobar" +clever tokens create "Quick local test" --expiration 1h +``` + +You can also list or revoke tokens: + +```bash +clever tokens -F json +clever tokens revoke api_tokens_xxx +``` + +Once created, API tokens must be used through the bridge URL: + +```bash +curl https://api-bridge.clever-cloud.com/v2/self -H "Authorization: Bearer [API_TOKEN]" +``` + +### clever curl + +`clever curl` is a wrapper around `curl`, it supports the same arguments and handles the authentication automatically for you using the CLI account you're currently logged in with. It's a simple way to make requests to the Clever Cloud API if [Clever Tools](https://github.com/CleverCloud/clever-tools) are installed on your system. + +```bash +clever curl https://api.clever-cloud.com/v2/self +clever curl https://api.clever-cloud.com/v2/summary +clever curl https://api.clever-cloud.com/v4/products/zones +clever curl https://api.clever-cloud.com/v2/organisations//applications | jq '.[].id' +clever curl https://api.clever-cloud.com/v4/billing/organisations//.pdf > invoice.pdf +``` + +### Official clients/SDKs + +You can request the Clever Cloud API from multiple languages through our official clients/SDKs: +- [Go](https://github.com/CleverCloud/clevercloud-client-go) +- [JavaScript](https://github.com/CleverCloud/clever-client.js) +- [Rust](https://github.com/CleverCloud/clevercloud-sdk-rust) + +### OAuth1 + +If you have an application that needs to access Clever Cloud resources on behalf of your users, you can use OAuth1. This is the recommended way to authenticate third-party applications. To manage OAuth tokens linked to your account, use the [Clever Cloud Console](https://console.clever-cloud.com/users/me/oauth-tokens). + +#### Create an OAuth consumer + +First, you'll need to create an OAuth consumer for your application. This can be done in the [Clever Cloud console](https://console.clever-cloud.com). Go to your organisation, click on **Create…**, then on **an OAuth consumer** and fill the form. You will get a consumer key and a consumer secret for your application. + +#### Integrate your application + +Your application must implement the OAuth 1 dance. It mostly consists of the following steps: + +* Get a "request token" + * [`POST /oauth/request_token`](/developers/api/v2/#post-/oauth/request_token) + * You will get a temporary `oauth_token` and `oauth_token_secret` +* Redirect the user to the authorization page with the `oauth_token` + * [`GET /oauth/authorize`](/developers/api/v2/#get-/oauth/authorize) + * Once the user is logged in, the browser will be redirected to your application with the query params `oauth_verifier` and `oauth_token` +* Make sure the `oauth_token` from the first step matches the one you get after the redirection +* Get the "access token" with the `oauth_token`, `oauth_token_secret` and `oauth_verifier` + * [`POST /oauth/access_token`](/developers/api/v2/#post-/oauth/access_token) + * You will get the user `oauth_token` and `oauth_token_secret` + +Once done, your application can make API requests on behalf of the user with an OAuth 1 compatible client and the following tokens: + +* Consumer key +* Consumer secret +* User token +* User token secret + +More information about [OAuth dance](https://oauth.net/core/1.0/#anchor9). + +#### About the OAuth1 signature + +There are 3 supported methods for the signature: `PLAINTEXT`, `HMAC-SHA1` and `HMAC-SHA512`. While `PLAINTEXT` is way easier, `HMAC-SHA512` ensures that the request is totally verified. The `Authorization` header must start with `OAuth`, with a specific format for key/values: + +```bash +Authorization: OAuth key="value", key2="value2" +``` diff --git a/content/api/v2.md b/content/api/v2.md new file mode 100644 index 000000000..81baf2c27 --- /dev/null +++ b/content/api/v2.md @@ -0,0 +1,5 @@ +--- +type: openapi +title: APIv2 Reference +description: Complete reference documentation for the Clever Cloud APIv2. Includes methods and examples to automate deployments and orchestration. +--- diff --git a/content/api/v4.md b/content/api/v4.md new file mode 100644 index 000000000..87c090e7a --- /dev/null +++ b/content/api/v4.md @@ -0,0 +1,330 @@ +--- +type: docs +title: APIv4 Reference +description: Reference documentation for the Clever Cloud APIv4 for billing, deployments, load balancers, logs, operators, etc. +keywords: +- openapi +- api +- reference +- endpoint +- v4 +--- +Clever Cloud provides a public REST API used by its own services and customers, known as [`/v2`](/developers/api/v2/). +As our platform evolves, we're progressively moving to `/v4` endpoints, adding functionalities, with a more modern approach: +``` +https://api.clever-cloud.com/v4/ +``` + +While the documentation moves towards completion, this page presents the most useful endpoints and example requests available now. + +{{< callout type="info" >}} +Each query response contains a `Sozu-Id`. If you need help from our support team, it can help to provide it. +{{< /callout>}} + +## Billing +- `/v4/billing/organisations/{orgid}/invoices` +- `/v4/billing/organisations/{orgid}/invoices/{invoiceid}` +- `/v4/billing/organisations/{orgid}/invoices/{invoiceid}.html` +- `/v4/billing/organisations/{orgid}/invoices/{invoiceid}.pdf` +- Type: `GET` + +You can use optional parameters to filter it: +| Parameter | Type | Comment | +| :--- | :--- | :--- | +| `limit` | `int` | | +| `since` | `string` | ISO 8601 formatted | +| `until` | `string` | ISO 8601 formatted | + +Example response, for each invoice: +```bash +[ + { + "invoice_number": "", + "kind": "", + "owner_id": "", + "address": { + "address_id": "", + "owner_id": "", + "name": "", + "company": "", + "address": "", + "city": "", + "zipcode": "", + "country_alpha2": "", + "vat_number": "", + "vat_percent": float, + "customer_cost_center": "", + "customer_purchase_order": "" + }, + "emission_date": "", + "pay_date": "", + "status": "", + "currency": "", + "price_factor": float, + "discount": float, + "vat_percent": float, + "total_tax_excluded": { + "currency": "", + "amount": float, + "amount_formatted": "", + "default_display": "" + }, + "total_tax": { + "currency": "", + "amount": float, + "amount_formatted": "", + "default_display": "" + }, + "category": "", + "payment_provider": "", + "transaction_id": "", + "customer_order_id": "" + }, + {…} +] +``` + +## Deployments +- `/v4/orchestration/organisations/{ownerId}/applications/{applicationId}/deployments` +- `/v4/orchestration/organisations/{ownerId}/applications/{applicationId}/deployments/{deploymentId}` +- Type: `GET` + +Example response, for each deployment: +```bash +[ + { + "id": "", + "ownerId": "", + "applicationId": "", + "startDate": "", + "state": "", + "steps": [ + { + "state": "", + "date": "" + }, + { + "state": "", + "date": "" + }, + { + "state": "", + "date": "" + } + ], + "version": { + "commitId": "" + }, + "origin": { + "action": "", + "cause": "", + "source": "", + "authorId": "", + "constraints": [ + "" + ], + "priority": "" + }, + "hasDedicatedBuild": boolean + }, + {…} +] +``` + +## Instances +- `/v4/orchestration/organisations/{ownerId}/applications/{applicationId}/instances` +- Type: `GET` + +You can use optional parameters to filter it: +| Parameter | Type | Comment | +| :--- | :--- | :--- | +| `deploymentId` | `string` | | +| `limit` | `int` | | +| `excludeDeleted` | `boolean`| | +| `since` | `string` | ISO 8601 formatted | +| `until` | `string` | ISO 8601 formatted | +| `order` | `string` | `ASC` or `DESC` | +| `includeState` | `string` | case sensitive, repeated | +| `excludeState` | `string` | case sensitive, repeated | + +Example response, for each instance: +```bash +[ + { + "id": "", + "ownerId": "", + "applicationId": "", + "deploymentId": "", + "name": "", + "flavor": "", + "index": int, + "state": "", + "creationDate": "", + "deletionDate": "", + "network": { + "ip": "", + "port": int + }, + "isBuildVm": boolean + }, + {…} +] +``` + +## Load Balancers +- `/v4/load-balancers/organisations/{ownerId}/applications/{applicationId}/load-balancers/default` +- Type: `GET` + +Example response: +```bash +[ + { + "id": "", + "name": "", + "zoneId": "", + "dns": { + "cname": "", + "a": [] + } + } +] +``` + +## Logs +- `/v4/logs/organisations/{ownerId}/applications/{applicationId}/logs` +- Type: `GET` + +Answers with logs in a SSE (Server-Sent Events) stream. You can use optional parameters to filter it: + +| Parameter | Type | Comment | +| :--- | :--- | :--- | +| `deploymentId` | `string` | | +| `instanceId` | `string` | | +| `since` | `string` | ISO 8601 formatted | +| `until` | `string` | ISO 8601 formatted | +| `field` | `string` | Allow to get only asked fields, repeated | +| `filter` | `string` | Case insensitive `contains` type search | +| `limit` | `int64 ` | Minimum: `1` | +| `service` | `string` | systemd service name, repeated (default: `bas` and `bas-deploy`, can be `all`) | +| `throttleElements` | `int` | Maximum elements read per `throttlePerInMilliseconds`, default `100` | +| `throttlePerInMilliseconds` | `long` | Default `300` | + +## Operators +A Clever Cloud Operator deploys and manage resources for a given service. Available operators are: `keycloak`, `matomo`, `metabase`, `otoroshi`. + +- `/v4/addon-providers/addon-{operator_name}/addons/{operator_id}` +- Type: `GET` + +Example response: +```bash +{ + "resourceId": "real_id", + "addonId": "addon_id", + "name": "resource_name", + "ownerId": "user_or_org_id", + "plan": "PLAN_NAME", + "version": "x.y.z", + "javaVersion": "X", # Optional + "phpVersion": "X", # Optional + "accessUrl": "https://service-web-ui-id.services.clever-cloud.com", + "api": { # Optional + "url": "https://service-api-id.services.clever-cloud.com", + … + }, + "availableVersions": [ + "x.y.z", + … + ], + "resources": { + "entrypoint": "app_id", + … + }, + "features": { + … + }, + "envVars": { + "VAR_NAME": "value", + … + } +} +``` + +- `/v4/addon-providers/addon-{operator_name}/addons/{operator_id}/reboot` +- `/v4/addon-providers/addon-{operator_name}/addons/{operator_id}/rebuild` +- Type: `POST` +- Response code: `204` + +### Network groups +You can add the deployed service main application in a [Network Group](/developers/doc/develop/network-groups/) to activate some enhanced features: +- `keycloak`: two instances are deployed and synced through a Network Group +- `otoroshi`: once in a Network Group, an Otoroshi instance can be used in front of Clever Cloud applications + +- `/v4/addon-providers/addon-{operator_name}/addons/{operator_id}/networkgroup` +- Type: `POST` +- Response code: `202` + +Response contains the full operator object with `networkGroup` feature enabled: +```bash +"features": { + "networkGroup": { + "id": "ng_id" + } +} +``` + +- `/v4/addon-providers/addon-{operator_name}/addons/{operator_id}/networkgroup` +- Type: `DELETE` +- Response code: `204` +If no Network Group is found, the `networkGroup` feature value is `null`: + +```bash +"features": { + "networkGroup": null +} +``` + +## Products zones +- `/v4/products/zones` +- `/v4/products/zones/{name}` +- Type: `GET` + +Example response, for each zone: +```bash +[ + { + "id": "", + "name": "", + "country": "", + "countryCode": "", + "city": "", + "displayName": "", + "lat": float, + "lon": float, + "outboundIPs": [], + "tags": [] + }, + {…} +] +``` + +## Pulsar policies +- `/v4/addon-providers/addon-pulsar/addons/{addon-id}/storage-policies` +- Type: `GET`/`PATCH` + +Define or get offload/retention policies of a [Pulsar add-on](/developers/doc/addons/pulsar). Retention is how long messages are kept in the topic. Offload is how long messages are kept in the hot storage (NVMe SSD) before being moved to Cellar object storage (S3 compatible, HDD). + +Example query/response: +```bash +{ + "retentionPolicies": { + "sizeInMB": number, + "durationInDays": number + }, + "offloadPolicies": { + "durationInDays": number, + "sizeInMB": number + } +} +``` + +A `null` value means an infinite retention or no offload. diff --git a/content/changelog/2023/11-10-healthcheck-for-java.md b/content/changelog/2023/11-10-healthcheck-for-java.md new file mode 100644 index 000000000..c0484cb58 --- /dev/null +++ b/content/changelog/2023/11-10-healthcheck-for-java.md @@ -0,0 +1,24 @@ +--- +title: Custom healthcheck paths for Java applications +date: 2023-11-10 +tags: + - applications + - java +authors: + - name: Julien Durillon + link: https://github.com/judu + image: https://github.com/judu.png?size=40 +description: Your java applications can now be deployed with one or multiple custom healtchecks +aliases: +- /changelog/2023-11-10-healthcheck-for-java +excludeSearch: true +--- + +You can now define the paths that the orchestrator will call to validate a deployment for Java applications through one or multiple `CC_HEALTH_CHECK_PATH` environment variables. It works as follows: + +* If the application responds on this specified path, and the response code is between `200` and `300`, the orchestrator considers that the deployment has been validated. +* If it responds with another error code outside this interval, the application is considered to have failed its deployment. + +Currently, the orchestrator only checks whether the application is listening to TCP port `8080`. It does not always mean that the application has started correctly. + +- Read the documentation about [Deployment healthcheck path](/developers/doc/develop/healthcheck/) 📖 diff --git a/content/changelog/2023/11-29-api-update.md b/content/changelog/2023/11-29-api-update.md new file mode 100644 index 000000000..af33fa212 --- /dev/null +++ b/content/changelog/2023/11-29-api-update.md @@ -0,0 +1,45 @@ +--- +title: Identify VM Tasks through the API +date: 2023-11-29 +tags: + - api + - applications +authors: + - name: Alexandre Duval + link: https://github.com/kannarfr + image: https://github.com/kannarfr.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: You can now check if an application is a task via the Clever Cloud API +aliases: +- /changelog/2023-11-29-api-update +excludeSearch: true +--- +For years, you can deploy applications on Clever Cloud as a `Task` with the API or more recently the `CC_TASK=true` environment variable. As this feature will be widely available and used, the API has been updated to return such a state in the `instance.lifetime` object: + +```json{filename="GET https://api.clever-cloud.com/v2/self/applications/",linenos=table,hl_lines=[17]} +{ + "id": "string", + "name": "string", + "description": "string", + "zone": "string", + "zoneId": "string", + "instance": { + "type": "string", + "version": "string", + "variant": {}, + "minInstances": int, + "maxInstances": int, + "maxAllowedInstances": int, + "minFlavor": {}, + "maxFlavor": {}, + "flavors": [], + "lifetime": "string", //Allowed: REGULAR ┃ MIGRATION ┃ TASK + "instanceAndVersion": "string" + }, + … +} +``` + +- [Read the full APIv2 documentation](/developers/api/v2) diff --git a/content/changelog/2023/12-13-cellar-migration-tool-update.md b/content/changelog/2023/12-13-cellar-migration-tool-update.md new file mode 100644 index 000000000..34880b757 --- /dev/null +++ b/content/changelog/2023/12-13-cellar-migration-tool-update.md @@ -0,0 +1,19 @@ +--- +title: Cellar migration tool 2.1.0 is available +date: 2023-12-13 +tags: + - addons + - cellar +authors: + - name: Arnaud Lefebvre + link: https://github.com/BlackYoup + image: https://github.com/BlackYoup.png?size=40 +description: Keep-alive support and better behavior during network errors +aliases: +- /changelog/2023-12-13-cellar-migration-tool-update +excludeSearch: true +--- + +If you want to import your object storage data on Clever Cloud, you can use our open source [Cellar migration tool](https://github.com/CleverCloud/cellar-migration/releases/tag/v2.1.0), written in Rust. Its new release adds support for keep-alive when used from S3 clients and prevents panic if a network error occurs. + + - Check this project [on GitHub](https://github.com/CleverCloud/cellar-migration) {{< icon "github" >}} diff --git a/content/changelog/2023/12-15-sozu-0.15.18.md b/content/changelog/2023/12-15-sozu-0.15.18.md new file mode 100644 index 000000000..3053f6ab9 --- /dev/null +++ b/content/changelog/2023/12-15-sozu-0.15.18.md @@ -0,0 +1,21 @@ +--- +title: Sōzu 0.15.18 is available +date: 2023-12-15 +tags: + - sozu +authors: + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: Better, faster, stronger +aliases: +- /changelog/2023-12-15-sozu-0.15.18 +excludeSearch: true +--- + +Our open source reverse proxy, Sōzu, is now deployed in its version 0.15.18. It gives performance enhancements and: + +* Fix 502 following a 304 response with a body that does not respect RFCs +* Fix of a panic when upgrading from HTTP to WS or from HTTPs to WSs +* Fix encryption issues when reusing TLS sessions (bump of Rustls) +* Added a `--json` flag to all commands diff --git a/content/changelog/2023/12-18-java-21-default.md b/content/changelog/2023/12-18-java-21-default.md new file mode 100644 index 000000000..72d4b3d82 --- /dev/null +++ b/content/changelog/2023/12-18-java-21-default.md @@ -0,0 +1,19 @@ +--- +title: Java 21 now used by default +date: 2023-12-18 +tags: + - applications + - java +authors: + - name: Julien Durillon + link: https://github.com/judu + image: https://github.com/judu.png?size=40 +description: Deploy Java applications on Clever Cloud with version 21 as default +aliases: +- /changelog/2023-12-18-java-21-default +excludeSearch: true +--- + +Java version 21 is available on Clever Cloud for several weeks, but is now deployed as the default version for new applications. Of course, you can set the one of your choice between those available through `CC_JAVA_VERSION` environment variable. + +- Read our documentation [about Java](/developers/doc/applications/java) diff --git a/content/changelog/2023/12-18-new-par-ip-console.md b/content/changelog/2023/12-18-new-par-ip-console.md new file mode 100644 index 000000000..5c9ebef62 --- /dev/null +++ b/content/changelog/2023/12-18-new-par-ip-console.md @@ -0,0 +1,19 @@ +--- +title: Updated DNS entries for the PAR region +date: 2023-12-18 +tags: + - applications + - console +authors: + - name: Guillaume Assier + link: https://github.com/GuillaumeASSIER + image: https://github.com/GuillaumeASSIER.png?size=40 +description: New IP list for DNS of Clever Cloud PAR region in the Console +aliases: +- /changelog/2023-12-18-new-par-ip-console +excludeSearch: true +--- + +Setup of our new infrastructure in Paris implies addition of new IP which can be used for DNS entries. They are now detailed in the **Domain Names** section of your applications in the [Console](https://console.clever-cloud.com). + +![New IP entries in Clever Cloud Console](/images/console-new-ip-par.webp "The new IP of the PAR region in the Console") diff --git a/content/changelog/2023/12-18-php-8-default.md b/content/changelog/2023/12-18-php-8-default.md new file mode 100644 index 000000000..75b5077d4 --- /dev/null +++ b/content/changelog/2023/12-18-php-8-default.md @@ -0,0 +1,22 @@ +--- +title: Latest PHP 8.x now used by default +date: 2023-12-18 +tags: + - applications + - php +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Julien Durillon + link: https://github.com/judu + image: https://github.com/judu.png?size=40 +description: Deploy PHP applications on Clever Cloud with latest version 8.x as default +aliases: +- /changelog/2023-12-18-php-8-default +excludeSearch: true +--- + +PHP 8.x is available for years on Clever Cloud, but is now deployed as the default version for new applications. Of course, you can set the one of your choice between those available through `CC_PHP_VERSION` environment variable. + +- Read our documentation [about PHP version](/developers/doc/applications/php/#choose-your-php-version) diff --git a/content/changelog/2023/12-19-console-web-components-v12.md b/content/changelog/2023/12-19-console-web-components-v12.md new file mode 100644 index 000000000..aba926118 --- /dev/null +++ b/content/changelog/2023/12-19-console-web-components-v12.md @@ -0,0 +1,23 @@ +--- +title: Console update and Clever Web Components v12 +date: 2023-12-19 +tags: + - console + - components +authors: + - name: Pierre De Soyres + link: https://github.com/pdesoyres-cc + image: https://github.com/pdesoyres-cc.png?size=40 +description: Console update with new icons for the documentation +aliases: +- /changelog/2023-12-19-console-web-components-v12 +excludeSearch: true +--- + +Among other changes under the hood, our [Console](https://console.clever-cloud.com) now uses the latest release of Clever Web Components. This v12 paves the way to our new `log` components. It also gives multiple new features with some bug fixes, refactoring and breaking changes. + +- Read the [full changelog](https://github.com/CleverCloud/clever-components/releases/tag/12.0.0) 📖 + +Links to the new documentation are now available in the Console. They're more precise depending on the `variant` (e.g. PHP/Static), use small icons to boost visibility and are now effective for applications and add-ons: + +![The new documentation link in the Console](/images/doc-link-console.webp "The new documentation link in the Console") diff --git a/content/changelog/2023/12-22-sozu-wider-usage.md b/content/changelog/2023/12-22-sozu-wider-usage.md new file mode 100644 index 000000000..faabda28d --- /dev/null +++ b/content/changelog/2023/12-22-sozu-wider-usage.md @@ -0,0 +1,17 @@ +--- +title: Wider Sōzu usage +date: 2023-12-22 +tags: + - sozu +authors: + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: Sōzu gets better and can be used on more services on Clever Cloud +aliases: +- /changelog/2023-12-22-sozu-wider-usage +- /changelog/2023-12-22-sozu-update +excludeSearch: true +--- + +Our open source reverse proxy Sōzu can now be used as a load balancer for any kind of managed services, add-ons included. It also got better filtering and performances on Sōzu services. diff --git a/content/changelog/2024/01-02-pulsar-update.md b/content/changelog/2024/01-02-pulsar-update.md new file mode 100644 index 000000000..3b8b28086 --- /dev/null +++ b/content/changelog/2024/01-02-pulsar-update.md @@ -0,0 +1,17 @@ +--- +title: Pulsar update is available +date: 2024-01-02 +tags: + - addons + - pulsar +authors: + - name: Alexandre Duval + link: https://github.com/kannarfr + image: https://github.com/kannarfr.png?size=40 +description: The Clever Cloud Pulsar stack has been updated and is more stable +aliases: +- /changelog/2024-01-02-pulsar-update +excludeSearch: true +--- + +We've deployed a new version of Apache Pulsar on our platform. Our aim is to improve topics availability, avoiding conflicts between namespaces and bundle unloading. diff --git a/content/changelog/2024/01-10-documentation-changelog.md b/content/changelog/2024/01-10-documentation-changelog.md new file mode 100644 index 000000000..a0c058da5 --- /dev/null +++ b/content/changelog/2024/01-10-documentation-changelog.md @@ -0,0 +1,23 @@ +--- +title: Learn what's new on Clever Cloud platform +date: 2024-01-10 +tags: + - changelog + - documentation +authors: + - name: Julia March + link: https://github.com/juliamrch + image: https://github.com/juliamrch.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Clément Nivolle + link: https://github.com/cnivolle + image: https://github.com/cnivolle.png?size=40 +description: You can now check Clever Cloud's evolutions in our new changelog, RSS feed included +aliases: +- /changelog/2024-01-10-documentation-changelog +excludeSearch: true +--- + +A changelog has been [added](/developers/changelog) to our [Developer Center](/developers). It will be regularly updated by the Clever Cloud teams to give you an overview of our new features, but also changes made and deprecations planned on the platform. diff --git a/content/changelog/2024/01-11-redis-7.2.4.md b/content/changelog/2024/01-11-redis-7.2.4.md new file mode 100644 index 000000000..1d30b2efd --- /dev/null +++ b/content/changelog/2024/01-11-redis-7.2.4.md @@ -0,0 +1,30 @@ +--- +title: Redis 7.2.4 is available +date: 2024-01-11 +tags: + - addons + - redis +authors: + - name: Aurélien Hébert + link: https://github.com/aurrelhebert + image: https://github.com/aurrelhebert.png?size=40 +description: Use Redis 7.2 in its latest release on Clever Cloud +aliases: +- /changelog/2024-01-11-redis-7.2.4 +- /changelog/2024-01-11-redis-update +excludeSearch: true +--- + +Redis™ `7.2.4` is now available for each new deployment. You can easily migrate an existing instance from [Console](https://console.clever-cloud.com). + +## Security fixes + +* (CVE-2023-41056) In some cases, Redis™ may incorrectly handle resizing of memory buffers which can result in incorrect accounting of buffer sizes and lead to heap overflow and potential remote code execution. + +## Bug fixes + +* Fix crashes of cluster commands clusters with mixed versions of 7.0 and 7.2 (#12805, #12832) +* Fix slot ownership not being properly handled when deleting a slot from a node (#12564) +* Fix atomicity issues with the RedisModuleEvent_Key module API event (#12733) + +- [Learn more about Redis™ 7.2.x branch](https://redis.com/blog/introducing-redis-7-2/). diff --git a/content/changelog/2024/01-15-go-sdk-v0.0.8.md b/content/changelog/2024/01-15-go-sdk-v0.0.8.md new file mode 100644 index 000000000..5e5fef15f --- /dev/null +++ b/content/changelog/2024/01-15-go-sdk-v0.0.8.md @@ -0,0 +1,23 @@ +--- +title: Go Client v0.0.8 is available +date: 2024-01-15 +tags: + - go + - api + - client +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +description: The Clever Cloud Go Client has been updated to v0.0.8 +aliases: +- /changelog/2024-01-15-go-sdk-v0.0.8 +excludeSearch: true +--- + +If you want to use our API from a Go application or module, we provide an easy-to-use open source client. It has just been updated to version 0.0.8 with updated dependencies, fixes and better authentication on some systems. + +- Check this project [on GitHub](https://github.com/CleverCloud/clevercloud-client-go) {{< icon "github" >}} diff --git a/content/changelog/2024/01-22-matomo-5.0.1.md b/content/changelog/2024/01-22-matomo-5.0.1.md new file mode 100644 index 000000000..2c4866104 --- /dev/null +++ b/content/changelog/2024/01-22-matomo-5.0.1.md @@ -0,0 +1,24 @@ +--- +title: Matomo v5.0.1 is available +date: 2024-01-22 +tags: + - addons + - matomo +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +description: You can now deploy Matomo 5.0.1 on Clever Cloud +aliases: +- /changelog/2024-01-22-matomo-5.0.1 +excludeSearch: true +--- + +[Matomo](https://matomo.org/) 5.0 was released mid-December, version 5.0.1 is now available. Since then, we've worked on the support of this new branch on Clever Cloud. It's done! You can deploy this latest version right now from our [Console](https://console.clever-cloud.com) or [Clever Tools](https://github.com/CleverCloud/clever-tools). + +Existing customers add-ons are already up-to-date. +- [Learn more about Matomo 5.0](https://matomo.org/changelog/matomo-5-0-0/) +- [Learn more about Matomo 5.0.1](https://matomo.org/changelog/matomo-5-0-1/) \ No newline at end of file diff --git a/content/changelog/2024/01-24-ruby-3.3.0.md b/content/changelog/2024/01-24-ruby-3.3.0.md new file mode 100644 index 000000000..22da37ccd --- /dev/null +++ b/content/changelog/2024/01-24-ruby-3.3.0.md @@ -0,0 +1,23 @@ +--- +title: Ruby 3.3.0 is available +date: 2024-01-24 +tags: + - applications + - ruby +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Use Ruby 3.3.0 in your Ruby on Rails applications on Clever Cloud +aliases: +- /changelog/2024-01-24-ruby-3.3.0 +excludeSearch: true +--- + +You can now choose the `3.3.0` release of Ruby when you deploy Ruby on Rails applications on Clever Cloud. It can be set either through your `Gemfile` or the `CC_RUBY_VERSION` [environment variable](/developers/doc/reference/reference-environment-variables/#ruby). + +* [Learn more about Ruby 3.3.0 release](https://www.ruby-lang.org/en/news/2023/12/25/ruby-3-3-0-released/) + +{{< callout type="info" >}} + If you use Node.js on this image, be aware that default version is now 20.11.0 (LTS). If you need another release to deploy your application, set the `CC_NODE_VERSION` [environment variable](/developers/doc/develop/env-variables/). +{{< /callout >}} diff --git a/content/changelog/2024/01-25-clever-tools-3.1.0.md b/content/changelog/2024/01-25-clever-tools-3.1.0.md new file mode 100644 index 000000000..f7b90030a --- /dev/null +++ b/content/changelog/2024/01-25-clever-tools-3.1.0.md @@ -0,0 +1,36 @@ +--- +title: Clever Tools 3.1.0 is available +date: 2024-01-25 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Be prepared for a new wave of Clever Tools starting this release 3.1.0! +aliases: +- /changelog/2024-01-25-clever-tools-3.1.0 +excludeSearch: true +--- + +For several months, we were preparing our CLI, [Clever Tools](https://github.com/CleverCloud/clever-tools/), for big changes. It starts to be ready for prime time with the 3.1.0 release. First, the packaging process moved to GitHub Actions with some improvements: +- You can now get the [list of releases](https://github.com/CleverCloud/clever-tools/releases) with a changelog and source code archives +- No more beta channel: you'll be able to test new features easier +- Better process, quicker tests, more releases! + +If 3.0.x branch brought new log stack (faster, longer, order), you now get updated runtimes and zones lists [in autocomplete](https://github.com/CleverCloud/clever-tools?tab=readme-ov-file#enabling-autocompletion), details about application owner during deployment, `git+ssh` URL in new linked/created applications information. + +`clever deploy` can now be used with the `--same-commit-policy` or `-p` flag to set policy to apply when the local commit is the same as the remote one: `error`, `ignore`, `restart` or `rebuild` (default: `error`). + +Of course, there are also some bug fixes. And be prepared: more new features are on the way! + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2024/01-30-js-client-8.0.3.md b/content/changelog/2024/01-30-js-client-8.0.3.md new file mode 100644 index 000000000..8dd34cb4f --- /dev/null +++ b/content/changelog/2024/01-30-js-client-8.0.3.md @@ -0,0 +1,23 @@ +--- +title: JS Client 8.0.3 is available +date: 2024-01-30 +tags: + - js + - api + - client +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: The Clever Cloud JS Client has been updated to version 8.0.3 +aliases: +- /changelog/2024-01-30-js-client-8.0.3 +excludeSearch: true +--- + +If you want to use our API from a JavaScript application or module, we provide an easy-to-use open source client, available [as a npm package](https://www.npmjs.com/package/@clevercloud/client). It has just been updated to [version 8.0.3](https://github.com/CleverCloud/clever-client.js/blob/master/CHANGELOG.md#803-2024-01-30) where the options param of the `on` method is optional. There are fixes for the auto retry of logs SSE v2, event WS. But also for new logs SSE v4 ([ApplicationLogStream](https://github.com/CleverCloud/clever-client.js/pull/93)). + +- Check this project [on GitHub](https://github.com/CleverCloud/clever-client.js) {{< icon "github" >}} diff --git a/content/changelog/2024/02-02-images-update.md b/content/changelog/2024/02-02-images-update.md new file mode 100644 index 000000000..91746ebff --- /dev/null +++ b/content/changelog/2024/02-02-images-update.md @@ -0,0 +1,37 @@ +--- +title: February 2024 images update (part 1) +date: 2024-02-02 +tags: + - images + - update + - security +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: An in-depth work leading to faster updates +aliases: +- /changelog/2024-02-02-images-update +excludeSearch: true +--- + +Over the past few months, we've overhauled the way we build our applications and add-ons images from tooling to included binaries. We'll deliver soon the first public milestone of this project, which will leads us to more frequent releases. + +In the meantime, we've updated Docker, Erlang, Go, Haskell, Ruby and Rust images into production with no impact for our users. They include security patches and now use Linux kernel 6.7.1, OpenSSL 3.2.1 and Node.js 20.11.0 by default. For the latter, you can change it in the updated images via the `CC_NODE_VERSION` [environment variable](/developers/doc/reference/reference-environment-variables/#commons-to-all-applications). Other changes are as follows: + +- **Docker**: + - moby 25.0.2 + - runc 1.1.12 + - containerd 1.7.13 + - docker-cli 25.0.2 +- **Erlang**: + - elixir 1.15.7, erlang 26.2.1 + - elixir 1.16.0, erlang 26.2.1 +- **Rust**: + - Stable: 1.75.0 + - Beta: 1.76.0 + - Nightly: 1.77.0 +- **Go**: + - go 1.21.6 + +Other images will be updated the same way in the coming days. diff --git a/content/changelog/2024/02-07-clever-tools-3.2.0.md b/content/changelog/2024/02-07-clever-tools-3.2.0.md new file mode 100644 index 000000000..89d777ca4 --- /dev/null +++ b/content/changelog/2024/02-07-clever-tools-3.2.0.md @@ -0,0 +1,33 @@ +--- +title: Clever Tools 3.2.0 is available +date: 2024-02-07 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: And more is coming! +aliases: +- /changelog/2024-02-07-clever-tools-3.2.0 +excludeSearch: true +--- + +As mentioned [in the previous release](../01-25-clever-tools-3.1.0/), the packaging process moved to GitHub Actions to provide a better process, quicker tests and more frequent releases. We start with [the 3.2.0](https://github.com/CleverCloud/clever-tools/releases/tag/3.2.0) adding the log auto retry feature on network failures and some fixes: + +* **api:** improve error message with `EAI_AGAIN` and `ECONNRESET` ([b134213](https://github.com/CleverCloud/clever-tools/commit/b134213f30d46dd7f5690a38425deb4fd752148c)) +* **logs:** improve error message with `EAI_AGAIN` and `ECONNRESET` ([fada067](https://github.com/CleverCloud/clever-tools/commit/fada06771369173e579f5fd3a708ff3cef40c95f)) +* **logs:** improve open and error debug message ([28dd996](https://github.com/CleverCloud/clever-tools/commit/28dd9968bec8de9545c6b940be732d3f8f87a8f9)) +* **logs:** increase connection timeout ([a4ec4b9](https://github.com/CleverCloud/clever-tools/commit/a4ec4b90b5d3938e27679edeb7d375281def3776)) +* **logs:** only print SSE errors as debug when verbose mode is enabled ([3ea21c6](https://github.com/CleverCloud/clever-tools/commit/3ea21c6a4ff75db8df5f8177bba10ef17c2962e0)) + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2024/02-08-sozu-0.15.19.md b/content/changelog/2024/02-08-sozu-0.15.19.md new file mode 100644 index 000000000..ba1500216 --- /dev/null +++ b/content/changelog/2024/02-08-sozu-0.15.19.md @@ -0,0 +1,23 @@ +--- +title: Sōzu 0.15.19 is available, 1.0 is coming +date: 2024-02-08 +tags: + - sozu +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: Do you know protobuf? +aliases: +- /changelog/2024-02-08-sozu-0.15.19 +excludeSearch: true +--- + +Our open source reverse proxy, Sōzu, is now deployed in its version 0.15.19. We fixed behaviors when parsing HTTP 1.1 (mainly pipelining or streaming issues) and implemented the flag `--json` on every query command. We also reduced logging level, enhanced few logs and updated the logger to better track issues. + +- Read the full changelog [on GitHub](https://github.com/sozu-proxy/sozu/releases/tag/0.15.19) {{< icon "github" >}} + +We expect the next release to be 1.0, with [protobuf](https://protobuf.dev/) everywhere and 2x faster messaging. We'll now use [Metal I/O](https://github.com/tokio-rs/mio) also for communication between workers, rather than threadpools. A release candidate should be released this month. \ No newline at end of file diff --git a/content/changelog/2024/02-12-new-grahds-region.md b/content/changelog/2024/02-12-new-grahds-region.md new file mode 100644 index 000000000..f5eed3f21 --- /dev/null +++ b/content/changelog/2024/02-12-new-grahds-region.md @@ -0,0 +1,22 @@ +--- +title: New Gravelines HDS region +date: 2024-02-12 +tags: + - addons + - applications + - platform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: HDS servers, the duplicate way +aliases: +- /changelog/2024-02-12-new-grahds-region +excludeSearch: true +--- + +For some time now, you can deploy your applications and add-ons through Clever Cloud, to Health Data Hosting (HDS) certified servers provided by OVHcloud in Roubaix. We also provide an object storage service (Cellar) from cluster composed of such servers in Roubaix and Gravelines (separated by ~100 km), available as the `fr-north-hds` region. + +Some customers asked us to make the Gravelines HDS region available independently for applications and add-ons, we listened to them. You can now deploy to it from [`clever-tools`](https://github.com/CleverCloud/clever-tools) or [the Console](https://console.clever-cloud.com) as `grahds`. + +Please note that Clever Cloud’s services and infrastructures obtained the ISO 9001 certification last year, we’re waiting for the definitive approval of ISO 27001. HDS certification is the next step and our current priority \ No newline at end of file diff --git a/content/changelog/2024/02-16-clever-tools-3.4.0.md b/content/changelog/2024/02-16-clever-tools-3.4.0.md new file mode 100644 index 000000000..6155c2a2b --- /dev/null +++ b/content/changelog/2024/02-16-clever-tools-3.4.0.md @@ -0,0 +1,47 @@ +--- +title: Clever Tools 3.4.0 is available +date: 2024-02-16 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: JSON everywhere, create more easily! +aliases: +- /changelog/2024-02-16-clever-tools-3.4.0 +excludeSearch: true +--- + +This week, we published two Clever Tools updates in a row. 3.3.0 was about adding [our new Gravelines HDS region](../02-12-new-grahds-region/) support and fixing a bug in our add-ons logs feature. 3.4.0 brings `json` and `json-stream` formats for applications logs. The latter uses the Newline delimited JSON (NDJSON) specification (`jq` compatible). You can learn more about [ndjson/ndjson-spec/ on GitHub](https://github.com/ndjson/ndjson-spec/blob/master/README.md). + +But it's the `create` and `deploy` commands which are the most improved by this release. First, you'll now get the application or add-on name confirmed after creation. You can also get a JSON response adding `--format json` or `-F json` to the `create` or `create-addon` command. Second, the current folder name is now used as default application name if none is provided. + +To create a Node.js application once logged in, you can now just: + +``` +clever create -t node +``` + +If you need a JSON response for a Go application deployed on Gravelines HDS: + +``` +clever create --type go --region grahds --format json +``` + +Last but not least: you can deploy a specific tag from your local git repository adding the `--tag` or `-t` option: + +``` +clever deploy --tag v0.4.2 +``` + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2024/02-22-postgresql-pgvector-support.md b/content/changelog/2024/02-22-postgresql-pgvector-support.md new file mode 100644 index 000000000..f77e42855 --- /dev/null +++ b/content/changelog/2024/02-22-postgresql-pgvector-support.md @@ -0,0 +1,29 @@ +--- +title: "PostgreSQL: ask for pgvector support" +date: 2024-02-22 +tags: + - addons + - postgresql +authors: + - name: Lucas Draescher + link: https://github.com/draescherl + image: https://github.com/draescherl.png?size=40 + - name: Aurélien Hébert + link: https://github.com/aurrelhebert + image: https://github.com/aurrelhebert.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Your wishes are our commands +aliases: +- /changelog/2024-02-22-postgresql-pgvector-support +excludeSearch: true +--- + +PostgreSQL databases managed by Clever Cloud come with [lots of extensions enabled by default](/developers/doc/addons/postgresql/#default-extensions). There are also [some you can ask for](/developers/doc/addons/postgresql/#on-demand-extensions), and we'll set them up, like `pg_cron`, `pgtap` or `timescaledb`. + +We recently noticed an increased interest from our clients in supporting the `pgvector` extension, needed for specific (AI) workloads. To answer these needs, we've packaged it and are now able to provide it on-demand. + +If you need `pgvector`, open a ticket to our support team through [the Console Ticket Center](https://console.clever-cloud.com/ticket-center-choice). If you need any other extension, feel free to ask, we will try our best to respond to your use-case. + +- Learn more about `pgvector` [on GitHub](https://github.com/pgvector/pgvector) {{< icon "github" >}} \ No newline at end of file diff --git a/content/changelog/2024/02-26-healthcheck-for-everyone.md b/content/changelog/2024/02-26-healthcheck-for-everyone.md new file mode 100644 index 000000000..a15e5a415 --- /dev/null +++ b/content/changelog/2024/02-26-healthcheck-for-everyone.md @@ -0,0 +1,24 @@ +--- +title: Custom healthcheck paths for all applications +date: 2024-02-26 +tags: + - applications +authors: + - name: Julien Durillon + link: https://github.com/judu + image: https://github.com/judu.png?size=40 +description: Your applications can now be deployed with one or multiple custom healtchecks +aliases: +- /changelog/2024-02-26-healthcheck-for-everyone +excludeSearch: true +--- + +Up until now, the deployment process only checked whether the application is listening to TCP port `8080`. That doesn't always mean that the application has started correctly. + +You can now define the paths that the orchestrator will call to validate a deployment for applications through one or multiple `CC_HEALTH_CHECK_PATH` environment variables. It works as follows: + +* If the application responds on this specified path, and the response code is between `200` and `300`, the orchestrator considers that the deployment has been validated. +* If it responds with a code outside this interval, the application is considered to have failed its deployment. + +- Read the documentation about [Deployment healthcheck path](/developers/doc/develop/healthcheck/) 📖 + diff --git a/content/changelog/2024/02-26-mtl-iplb-update.md b/content/changelog/2024/02-26-mtl-iplb-update.md new file mode 100644 index 000000000..a35c7ec49 --- /dev/null +++ b/content/changelog/2024/02-26-mtl-iplb-update.md @@ -0,0 +1,37 @@ +--- +title: "Montreal region (MTL): A records update for your domains/DNS" +date: 2024-02-23 +tags: + - sozu + - applications + - addons +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: But please, prefer CNAMEs +aliases: +- /changelog/2024-02-26-mtl-iplb-update +excludeSearch: true +--- + +As we're upgrading our infrastructure and load balancers in Montreal, we've added new failover IPs in this region. + +If you configure your domains through CNAME records, this update will be transparent. But if you use A records, switch to CNAME or update your [DNS configuration](/developers/doc/administrate/domain-names/). Old IPs will continue to work for a while, but we recommend you to update your DNS as soon as possible to avoid any service interruption. + +## Applications + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.mtl.clever-cloud.com.` | +| A
Only if CNAME is not available | @ 10800 IN A 158.69.109.229
@ 10800 IN A 149.56.117.183 | + +## Add-ons + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain-sdc.mtl.clever-cloud.com.` | +| A
Only if CNAME is not available | @ 10800 IN A 54.39.154.128
@ 10800 IN A 167.114.35.164 | diff --git a/content/changelog/2024/02-27-images-update-part2.md b/content/changelog/2024/02-27-images-update-part2.md new file mode 100644 index 000000000..84fa30d9f --- /dev/null +++ b/content/changelog/2024/02-27-images-update-part2.md @@ -0,0 +1,28 @@ +--- +title: February 2024 images update (part 2) +date: 2024-02-27 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: New .Net version, Java Elastic/APM agent update +aliases: +- /changelog/2024-02-27-images-update-part2 +excludeSearch: true +--- + +Earlier this month, we published [a first set of updates](../02-02-images-update) for Docker, Erlang, Go, Haskell, Ruby and Rust. Some days ago, we finished this work and all images are now up-to-date. This process occurred with no impact for our users. As mentioned in a previous post, this enables [the new `healthcheck` feature](../02-26-healthcheck-for-everyone) available for all applications. + +New images include security patches, Linux kernel 6.7.1, OpenSSL 3.2.1 and Node.js 20.11.0 by default. For the latter, you can set it via the `CC_NODE_VERSION` [environment variable](/developers/doc/reference/reference-environment-variables/#commons-to-all-applications). Other changes are as follows: + +* **.Net:** + * Version 8.0 support + * `CC_DOTNET_VERSION` [environment variable](/developers/doc/reference/reference-environment-variables/#net) can be `6.0` or `8.0` +* **Java - Elastic / APM:** + * The agent has been updated to 1.47.1 + * Java 21 support + +New PHP image is next to come, with 8.3 version support, we're currently working on it. After that, we'll bring our new strategy to build images into production. We're currently testing it, and preparing enhancements for multiples runtimes. Your applications will automatically benefit from it when available. [Stay tuned](/developers/changelog/index.xml). diff --git a/content/changelog/2024/02-27-js-client-8.2.0.md b/content/changelog/2024/02-27-js-client-8.2.0.md new file mode 100644 index 000000000..8adef3da2 --- /dev/null +++ b/content/changelog/2024/02-27-js-client-8.2.0.md @@ -0,0 +1,22 @@ +--- +title: JS Client 8.2.0 is available +date: 2024-02-27 +tags: + - js + - client +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +description: The Clever Cloud JS Client has been updated to version 8.2.0 +aliases: +- /changelog/2024-02-27-js-client-8.2.0 +excludeSearch: true +--- + +Since [latest big update](../01-30-js-client-8.0.3/) of the [JS Client](https://www.npmjs.com/package/@clevercloud/client/v/8.2.0), we've fixed multiple issues with Server-Sent Events (SSE). [8.2.0 release](https://github.com/CleverCloud/clever-client.js/blob/master/CHANGELOG.md#820-2024-02-27) allows error handling from legacy client and brings support repeatable query parameters, which is a feature enabler for some tools. + +- Check this project [on GitHub](https://github.com/CleverCloud/clever-client.js) {{< icon "github" >}} diff --git a/content/changelog/2024/03-07-env-vars-app-creation-api.md b/content/changelog/2024/03-07-env-vars-app-creation-api.md new file mode 100644 index 000000000..b8dc91369 --- /dev/null +++ b/content/changelog/2024/03-07-env-vars-app-creation-api.md @@ -0,0 +1,43 @@ +--- +title: "API: set environment variables at application creation" +date: 2024-03-07 +tags: + - api + - applications +authors: + - name: Alexandre Duval + link: https://github.com/kannarfr + image: https://github.com/kannarfr.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: A game changer for some features coming soon +aliases: +- /changelog/2024-03-07-env-vars-app-creation-api +excludeSearch: true +--- + +When you create an application with the Clever Cloud API, you can now set environment variables directly. This feature is available in the `POST v2/organisations/{id}/applications` endpoint, with an object to set: + +```json +"env": { + "ENV_VAR": "value", + "ANOTHER_ENV_VAR": "another value" +} +``` + +The response will contain an `env` object, with the environment variables set: + +```json +"env": [ +{ + "name": "ENV_VAR", + "value": "value" +}, +{ + "name": "ANOTHER_ENV_VAR", + "value": "another value" +}] +``` + +You can get this object from the applications endpoints, such as `GET v2/organisations/{id}/applications/{appId}`. diff --git a/content/changelog/2024/03-07-web-components-v13.md b/content/changelog/2024/03-07-web-components-v13.md new file mode 100644 index 000000000..447aad8a2 --- /dev/null +++ b/content/changelog/2024/03-07-web-components-v13.md @@ -0,0 +1,24 @@ +--- +title: Clever Web Components v13 +date: 2024-03-07 +tags: + - console + - components +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florian Sanders + link: https://github.com/florian-sanders-cc + image: https://github.com/florian-sanders-cc.png?size=40 +description: Console update with new icons for the documentation +aliases: +- /changelog/2024-03-07-web-components-v13 +excludeSearch: true +--- + +Clever Cloud's [Web Components](https://www.clever.cloud/developers/clever-components/) v13 are available, with bug fixes, refactoring, and new features. We introduced new possibilities to highlight form fields (larger labels, with color), paving the way for our new add-on/application creation process. + +A standardized API is used for UI components that depend on a smart component. It includes a `state` property receiving state type: `loaded`, `loading`, `error` and data. Latest smart components no longer rely on `rxjs`, making them easier to maintain. + +- Read the [full changelog](https://github.com/CleverCloud/clever-components/releases/tag/13.0.0) {{< icon "github" >}} diff --git a/content/changelog/2024/03-11-console-components-update.md b/content/changelog/2024/03-11-console-components-update.md new file mode 100644 index 000000000..396bb2e5a --- /dev/null +++ b/content/changelog/2024/03-11-console-components-update.md @@ -0,0 +1,20 @@ +--- +title: Console's components upgrade +date: 2024-03-12 +tags: + - console + - components +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Pierre De Soyres + link: https://github.com/pdesoyres-cc + image: https://github.com/pdesoyres-cc.png?size=40 +description: More security and information for our users +aliases: +- /changelog/2024-03-11-console-components-update +excludeSearch: true +--- + +In our ongoing effort to improve our [Console](https://console.clever-cloud.com) experience, we upgraded some of its components. It now uses [JS Client 8.2.0](../02-27-js-client-8.2.0/) and [Web Components 13.0.0](../03-07-web-components-v13/). This update also brings some fixes regarding deployment logs links and Warp10 calls. \ No newline at end of file diff --git a/content/changelog/2024/03-12-oauth-token-expiration.md b/content/changelog/2024/03-12-oauth-token-expiration.md new file mode 100644 index 000000000..cc2fed527 --- /dev/null +++ b/content/changelog/2024/03-12-oauth-token-expiration.md @@ -0,0 +1,27 @@ +--- +title: "OAuth tokens expiration" +date: 2024-03-12 +tags: + - api + - security +authors: + - name: Mathieu Degand + link: https://github.com/galimede + image: https://github.com/galimede.png?size=40 + - name: Julien Durillon + link: https://github.com/judu + image: https://github.com/judu.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: More security and information for our users +aliases: +- /changelog/2024-03-12-oauth-token-expiration +excludeSearch: true +--- + +When you connect to Clever Cloud's interfaces, such as API, Console or CLI, you use OAuth tokens. They are now valid for a certain amount of time, and you need to refresh it before it expires. + +The duration of the token is 1 year for [Clever Tools](https://github.com/CleverCloud/clever-tools), 3 months for [Console](https://console.clever-cloud.com) and any other integration. The expiration date of the token is mentioned at the time of its creation from CLI, you can also check it from [Console](https://console.clever-cloud.com/users/me/oauth-tokens). You can still revoke tokens at any time from the same (enhanced) page. We'll add such information in future releases of Clever Tools. + +Please note that if you ask a member of our support team to access your account, this interface will show their own token, you can revoke, valid for 12 hours. This change is part of our ongoing effort to improve [the security](https://www.clever-cloud.com/security/) of our users' accounts and data. If you have any questions or concerns, please [contact us](https://console.clever-cloud.com/ticket-center-choice). \ No newline at end of file diff --git a/content/changelog/2024/03-20-pulsar-3.2.1-update.md b/content/changelog/2024/03-20-pulsar-3.2.1-update.md new file mode 100644 index 000000000..e1c98ab81 --- /dev/null +++ b/content/changelog/2024/03-20-pulsar-3.2.1-update.md @@ -0,0 +1,22 @@ +--- +title: "Pulsar: 3.2.1 release and storage policies" +date: 2024-03-20 +tags: + - addons + - pulsar +authors: + - name: Alexandre Duval + link: https://github.com/kannarfr + image: https://github.com/kannarfr.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: New API endpoint and stack update +aliases: +- /changelog/2024-03-20-pulsar-3.2.1-update +excludeSearch: true +--- + +We've deployed the [3.2.1 release](https://github.com/apache/pulsar/releases/tag/v3.2.1) of Apache Pulsar on our platform. It brings lots of fixes and some new features. Please note we also added [a new v4 endpoint](/developers/api/v4/#pulsar-policies) in our API to control Pulsar's storage policies (offload, retention). + +- Learn more about [Apache Pulsar](https://www.clever-cloud.com/product/pulsar/) \ No newline at end of file diff --git a/content/changelog/2024/04-04-CVE-2024-3094.md b/content/changelog/2024/04-04-CVE-2024-3094.md new file mode 100644 index 000000000..19b49cdc7 --- /dev/null +++ b/content/changelog/2024/04-04-CVE-2024-3094.md @@ -0,0 +1,34 @@ +--- +title: "Backdoor in xz/liblzma (CVE-2024-3094): our response" +date: 2024-04-03 +tags: + - security +authors: + - name: Arnaud Lefebvre + link: https://github.com/BlackYoup + image: https://github.com/BlackYoup.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: None of our services were impacted +aliases: +- /changelog/2024-04-04-cve-2024-3094 +excludeSearch: true +--- + +On March 29th, we were informed that a backdoor was discovered in the source code of `xz`, introduced with version 5.6.0 (CVE-2024-3094). Our security team instantly made sanity checks, and found our services were not impacted. + +As stated [by NIST](https://nvd.nist.gov/vuln/detail/CVE-2024-3094), « *Through a series of complex obfuscations, the liblzma build process extracts a prebuilt object file from a disguised test file existing in the source code, which is then used to modify specific functions in the liblzma code. This results in a modified liblzma library that can be used by any software linked against this library, intercepting and modifying the data interaction with this library.* ». + +First, the malicious version was not deployed on images we use for most of our services. Second, we don't use patches to support systemd within OpenSSH through libsystemd (which depends on the backdoored libzma). Third, some GNU/Linux distributions were specifically targeted, not [Exherbo Linux](https://www.exherbolinux.org/) which we use for our services. + +Nevertheless, we immediately put the backdoored version on a deny list to prevent its installation, and so did Exherbo Linux maintainers promptly after. We also started to revert `xz` 5.6.x to 5.4.6 on the few custom services where it had been set up, although it would not have been possible for an attacker to exploit it. + +You can know more about this CVE following these links: + +* https://boehs.org/node/everything-i-know-about-the-xz-backdoor +* https://gynvael.coldwind.pl/?lang=en&id=782 +* https://lcamtuf.substack.com/p/technologist-vs-spy-the-xz-backdoor +* https://www.openwall.com/lists/oss-security/2024/03/29/4 + +You can contact [our support team](https://console.clever-cloud.com/ticket-center-choice) if you have further questions about this topic. \ No newline at end of file diff --git a/content/changelog/2024/04-11-clever-tools-3.5.2.md b/content/changelog/2024/04-11-clever-tools-3.5.2.md new file mode 100644 index 000000000..14c38ff8d --- /dev/null +++ b/content/changelog/2024/04-11-clever-tools-3.5.2.md @@ -0,0 +1,62 @@ +--- +title: Clever Tools 3.5.2 is available with cURL, KV, Tasks and more! +date: 2024-04-11 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Lots of new features included! +aliases: +- /changelog/2024-04-11-clever-tools-3.5.2 +excludeSearch: true +--- + +Clever Tools 3.5 is now available, and this branch brings lots of new important features. First, `clever curl` is now public and listed as an official command. It helps you to send curl requests with the auth context of your Clever Tools configuration. Thus, you can use Clever Cloud [API v2 or v4](/developers/api/). + +JSON format is supported for more commands, the `--since` option now supports a duration value. For example if you want to get logs since 2 hours ago, you can use `clever logs --since 2h`. This command documentation is available [there](/developers/doc/cli/logs-drains/#logs). + +Clever Tasks can now be directly created and configured from Clever Tools. They're applications which can be run on demand, not awaiting any HTTP request on the `8080` port, but needing a `CC_RUN_COMMAND` to execute. Once it's done, the application stops. You're just billed for the execution time. It can help you to make some checks, compilation, file conversions, etc. + +To create a Clever Task using Python for example: + +``` +# We create a Python App and its Git repository +mkdir pythonTask && cd pythonTask +echo 'print("Hello, from a Clever Cloud Task!")' > task.py +git init && git add . && git commit -m "Initial commit" + +# We deploy this app as a Task +clever create -t python --task 'python task.py' +clever deploy +``` + +If you want to check if an application will deploy as a `TASK` or the `REGULAR` way, use `clever status`. Change the executed command using an environment variable. Set another value, for example with a bash script: + +``` +clever env set CC_RUN_COMMAND "bash a_bash_script.sh" +``` +Clever Tasks will evolve with enhancements planed over the coming months. Feel free to tell us about your needs or ideas on this! + +* [Learn more about Clever Tasks](/developers/doc/develop/tasks/) + +Last but not least, we're introducing the access to Materia KV. Those granted with alpha access can now create a serverless, synchronously-replicated (over our 3 data centers in Paris) key-value add-on. You'll be able to use it with multiples kind of clients. First to be supported is Redis API. Thus, you can run: + +```` +clever addon create kv myKV +source <(clever addon env addon_myKV_id -F shell) +redis-cli -h $KV_HOST -p $KV_PORT --tls PING +```` +* [Learn more about Materia KV](https://www.clever-cloud.com/blog/company/2024/04/16/materiadb-kv-materia-functions/) ([FR](https://www.clever-cloud.com/fr/blog/entreprise/2024/04/16/materiadb-kv-functions/)) + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install) + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2024/04-15-new-logs-interface-public-beta.md b/content/changelog/2024/04-15-new-logs-interface-public-beta.md new file mode 100644 index 000000000..5d83113a0 --- /dev/null +++ b/content/changelog/2024/04-15-new-logs-interface-public-beta.md @@ -0,0 +1,27 @@ +--- +title: New logs interface is available in public beta +date: 2024-04-15 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Pierre De Soyres + link: https://github.com/pdesoyres-cc + image: https://github.com/pdesoyres-cc.png?size=40 +description: Lots of new features included! +aliases: +- /changelog/2024-04-15-new-logs-interface-public-beta +excludeSearch: true +--- + +Since 2023, applications use a new Logs stack based on Pulsar and Vector, through CLI. Thanks to it, we provide a more reliable service, with new filtering features. It's now available from [the Console](https://console.clever-cloud.com) too! As it's in public beta stage, you'll need to activate it through the "Try the new Logs experience" link. You can revert this choice if needed. + +This new feature is available for **applications only**. + +In this new interface you'll get better access to your instance/deployments, dark/light themes, a text filter, multiple settings (stored into your Clever Cloud account). + +* [Learn more about our new Logs interface](https://www.clever-cloud.com/blog/company/2024/04/15/our-new-logs-interface/) ([FR](https://www.clever-cloud.com/fr/blog/entreprise/2024/04/15/notre-nouvelle-interface-de-logs-est-disponible/)) +* [Give us feedback about new Logs interface](https://github.com/CleverCloud/Community/discussions/categories/new-logs-interface) \ No newline at end of file diff --git a/content/changelog/2024/04-16-clever-tools-3.6.0.md b/content/changelog/2024/04-16-clever-tools-3.6.0.md new file mode 100644 index 000000000..e754f827b --- /dev/null +++ b/content/changelog/2024/04-16-clever-tools-3.6.0.md @@ -0,0 +1,27 @@ +--- +title: Clever Tools 3.6.0 is available +date: 2024-04-16 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Lots of new features included! +aliases: +- /changelog/2024-04-16-clever-tools-3.6.0 +excludeSearch: true +--- + +Clever Tools 3.6 is now available, with some minor fixes and a new feature: the support of SD-PARAMS ([RFC 5424](https://www.rfc-editor.org/rfc/rfc5424.html)) for UDP and TCP drains with `clever drain create --sd-params "SD_PARAMS_STRING"`. + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install) + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2024/04-24-php-deprecate-warning.md b/content/changelog/2024/04-24-php-deprecate-warning.md new file mode 100644 index 000000000..ecd29fec9 --- /dev/null +++ b/content/changelog/2024/04-24-php-deprecate-warning.md @@ -0,0 +1,24 @@ +--- +title: "PHP: a warning message when a deprecated version is used" +date: 2024-04-24 +tags: + - php + - applications + - information +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Please, update! +aliases: +- /changelog/2024-04-24-php-deprecate-warning +excludeSearch: true +--- + +PHP ecosystem is evolving at a steady pace with a clear lifecycle: 1 version per year, 2 years of active support, plus 1 year of security support. PHP 8.2 is actively supported, while 8.1 is in its security support window. ALL previous releases are considered end-of-life (EOL) by PHP Team. PHP 5.x branch is EOL since 2019, 7.x branch since the end of 2022. + +As we still see a lot of applications using deprecated versions, the new PHP image we'll release next week will start to better inform our users about this. When PHP 8.0 or a previous release is used, a warning will be shown during deployment, asking to set `CC_PHP_VERSION` to `8` (latest 8.x), `8.2` currently on Clever Cloud. In the coming month, we'll extend such informative warnings to other runtimes. We'll also explore ways to show them in other interfaces and send emails about it. + + There is no short term plan to cut access to supported versions such as PHP 5.6 or 7.x, but you do it at your own risks. + +* Learn more about [PHP releases lifecycle](https://www.php.net/supported-versions.php) diff --git a/content/changelog/2024/04-25-images-update.md b/content/changelog/2024/04-25-images-update.md new file mode 100644 index 000000000..256ef0cef --- /dev/null +++ b/content/changelog/2024/04-25-images-update.md @@ -0,0 +1,32 @@ +--- +title: "Images: April 2024 update" +date: 2024-04-25 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Kernel 6.8.6, security fixes and action executor +aliases: +- /changelog/2024-04-25-images-update +excludeSearch: true +--- + +We've updated all our images and deployed them without any impact for our users. They include our new action executor, which will help to make some features available soon. They also include the following changes: + +* **Common:** + * Linux kernel 6.8.6 + * glibc security fix (CVE-2024-2961) + * Node.js 20.12.2 as default version +* **Ruby:** + * Update to 3.0.7, 3.1.5, 3.2.4 and 3.3.1 (CVE-2024-27282, CVE-2024-27281 et CVE-2024-27280) +* **Erlang / Elixir:** + * Update to 21.16.2, 22.3.4.27, 23.3.4.20, 24.3.4.17, 25.3.2.11, 26.2.4 +* **.NET:** + * Update to 8.0.103, 8.0.3 + +We had to delay the release of PHP image with 8.3 version support, to better support some extensions and include latest security fixes. It will start to deploy next week and include an informative message when a deprecated version of PHP is used. + +* Learn more about the [message for deprecated PHP versions](../04-24-php-deprecate-warning/). diff --git a/content/changelog/2024/04-26-new-images-stack.md b/content/changelog/2024/04-26-new-images-stack.md new file mode 100644 index 000000000..a640768db --- /dev/null +++ b/content/changelog/2024/04-26-new-images-stack.md @@ -0,0 +1,19 @@ +--- +title: Our new images stack enters production +date: 2024-04-26 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Fewer images, more updates coming +aliases: +- /changelog/2024-04-26-new-images-stack +excludeSearch: true +--- + +As mentioned in previous posts, we've made a major overhaul of how we create the images underlying our virtual machines over the past few months. Our main goals are to provide a more efficient way of keeping add-ons and application up to date without breaking changes, to make new features available more quickly and to keep it simple for our team to manage all of this. + +We also use fewer base images for our runtimes to reduce binaries and configuration disparities, storage footprint, simplify build and maintenance. After extensive tests, this new stack is now used in production, starting with .Net, Go and Rust images. We'll progressively deploy it to all our products in the coming months. This should be done without any impact for our users. \ No newline at end of file diff --git a/content/changelog/2024/05-28-tasks-in-console.md b/content/changelog/2024/05-28-tasks-in-console.md new file mode 100644 index 000000000..9db2faebe --- /dev/null +++ b/content/changelog/2024/05-28-tasks-in-console.md @@ -0,0 +1,24 @@ +--- +title: Manage Clever Tasks in the Console +date: 2024-05-28 +tags: + - console + - tasks +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Pierre De Soyres + link: https://github.com/pdesoyres-cc + image: https://github.com/pdesoyres-cc.png?size=40 +description: Just a box to check +aliases: +- /changelog/2024-05-28-tasks-in-console +excludeSearch: true +--- + +Since [its release 3.5.2](../04-11-clever-tools-3.5.2/), Clever Tools is able to manage [Clever Tasks](/developers/doc/develop/tasks/). It's now possible to create, configure and deploy them directly from the Console. To declare an application as a Task, check the corresponding box in the `Information` tab. + +A Clever Task can be run on demand. It executes the command you've set in the `CC_RUN_COMMAND` environment variable, without waiting for any HTTP request on the `8080` port. After that, the application stops. It's just billed for the execution time. + +![Clever Task Management in Console](/images/clever-tasks.webp "Defines a Clever Cloud application as a Task in Console") diff --git a/content/changelog/2024/05-30-php-8.3-java-22.md b/content/changelog/2024/05-30-php-8.3-java-22.md new file mode 100644 index 000000000..38ad45856 --- /dev/null +++ b/content/changelog/2024/05-30-php-8.3-java-22.md @@ -0,0 +1,32 @@ +--- +title: PHP 8.3, Composer 2.7.6 and Java 22 are available +date: 2024-05-30 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: May images update +aliases: +- /changelog/2024-05-30-php-8.3-java-22 +excludeSearch: true +--- + +We've updated some of our images and deployed them without any impact for our users. You can now set `CC_PHP_VERSION` to `8.3`. It's the default version for new PHP applications. If `CC_PHP_VERSION` is set to `8`, version 8.2 is still used. We also start to warn you if you use a [deprecated](https://www.php.net/supported-versions.php) PHP version, older than `8.1`. Other changes include: + +* **Common:** + * Linux kernel 6.8.11 (PHP is still 6.8.6) + * Node.js 20.14.0 as default version +* **.Net, Go, Rust:** + * Fix for crons +* **.Net:** + * Fix for deployment issues with 8.x branch +* **Java:** + * Support for Java 22 (non LTS) + * Support for NewRelic with Java 22 +* **PHP:** + * Composer 2.7.6 + * Support for PHP 8.3 with [all supported extensions](/developers/doc/applications/php/#available-extensions-and-modules) + * PHP info apps are available for PHP [8.0](https://php80info.cleverapps.io), [8.1](https://php81info.cleverapps.io), [8.2](https://php82info.cleverapps.io) and [8.3](https://php83info.cleverapps.io) diff --git a/content/changelog/2024/06-07-sozu-1.0.2.md b/content/changelog/2024/06-07-sozu-1.0.2.md new file mode 100644 index 000000000..57cb09d30 --- /dev/null +++ b/content/changelog/2024/06-07-sozu-1.0.2.md @@ -0,0 +1,27 @@ +--- +title: Sōzu 1.0.2 is available and deployed +date: 2024-06-07 +tags: + - sozu +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: A big step forward for our open source reverse proxy +aliases: +- /changelog/2024-06-07-sozu-1.0.2 +- /changelog/2024-10-04-sozu-1.0.2 +excludeSearch: true +--- + +After the availability of Sōzu 1.0 in release candidate and an extensive testing phase, we've identified and fixed some bugs. Over the last few days, we've been deploying version 1.0.2 across all our regions, and it's now fully used in production. This new branch brings a lot of improvements, security and new features to our open source Rust based reverse proxy. + +The communication between processes is more efficient thanks to [ProtoBuf](https://fr.wikipedia.org/wiki/Protocol_Buffers), which is now widely used in Sōzu. We've improved the performance through [our contribution to Rustls](https://github.com/rustls/rustls/pull/1774), added colors to logs. Process configuration is 50% faster, certificates renewal has been optimized, and their resolution is now significantly more responsive. + +We've also fixed a bug affecting socket timeouts on frontends, ensuring better handling of requests. + +* [New Sōzu website](https://www.sozu.io) +* Learn more about [Sōzu new releases](https://github.com/sozu-proxy/sozu/releases) {{< icon "github" >}} \ No newline at end of file diff --git a/content/changelog/2024/06-10-mongo-db-terraform.md b/content/changelog/2024/06-10-mongo-db-terraform.md new file mode 100644 index 000000000..684a99620 --- /dev/null +++ b/content/changelog/2024/06-10-mongo-db-terraform.md @@ -0,0 +1,24 @@ +--- +title: Deploy MongoDB add-ons with our Terraform provider +date: 2024-06-10 +tags: + - mongodb + - terraform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Mathieu Barcelo + link: https://github.com/TheCrabe + image: https://github.com/TheCrabe.png?size=40 +description: +aliases: +- /changelog/2024-06-10-mongo-db-terraform +excludeSearch: true +--- + +If you can deploy on Clever Cloud through our [Console](https://console.clever-cloud.com), our CLI ([Clever Tools](https://github.com/CleverCloud/clever-tools)), or our [API](/developers/api/), you can also use Terraform and compatible tools such as [OpenTofu](https://opentofu.org/). We maintain a provider that allows you to manage your resources as code, from applications to add-ons (object storage, databases, etc.). + +We've recently added support for Python and [Materia KV](/developers/doc/addons/materia-kv/). It's MongoDB's turn [to be available](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs/resources/mongodb). You can now create such an add-on, choose its plan, region and get the credentials to connect to it. + +* Learn more about [our Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs) diff --git a/content/changelog/2024/06-11-clever-tools-3.7.0.md b/content/changelog/2024/06-11-clever-tools-3.7.0.md new file mode 100644 index 000000000..cafa0718e --- /dev/null +++ b/content/changelog/2024/06-11-clever-tools-3.7.0.md @@ -0,0 +1,27 @@ +--- +title: Clever Tools 3.7.0 is available +date: 2024-06-11 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: cURL is fixed, some enhancements +aliases: +- /changelog/2024-06-11-clever-tools-3.7.0 +excludeSearch: true +--- + +[Clever Tools 3.7](https://github.com/CleverCloud/clever-tools/releases/tag/3.7.0) is now available, with some bug fixes, including `clever curl` in packaged and node versions. We've also enhanced `activity` and `addon`. With the latest, selected plan is now always the cheapest by default at creation. + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2024/06-11-materia-kv-public-alpha.md b/content/changelog/2024/06-11-materia-kv-public-alpha.md new file mode 100644 index 000000000..478702680 --- /dev/null +++ b/content/changelog/2024/06-11-materia-kv-public-alpha.md @@ -0,0 +1,23 @@ +--- +title: Materia KV enters public Alpha +date: 2024-06-11 +tags: + - materia + - kv +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: May images update +aliases: +- /changelog/2024-06-11-materia-kv-public-alpha +excludeSearch: true +--- + +At Devoxx France 2024, we introduced our new [Materia](https://www.clever-cloud.com/materia/) databases offering. The first "flavor", KV, is now available in public Alpha to all our customers. It's a key-value data store, compatible with Redis protocol and soon DynamoDB, GraphQL. You can create such an add-on from [API](/developers/api/), [Clever Tools](https://github.com/CleverCloud/clever-tools) or [Console](https://console.clever-cloud.com/users/me/addons/new). Let us know what to improve ! + +- [Materia KV public announcement](https://www.clever-cloud.com/blog/company/2024/04/16/materiadb-kv-materia-functions/) +- [Materia KV documentation](/developers/doc/addons/materia-kv/) +- [Give us your feedback](https://github.com/CleverCloud/Community/discussions/categories/materia) + +{{< youtube id="B8wQEG8qkqs" >}} diff --git a/content/changelog/2024/06-21-better-new-logs.md b/content/changelog/2024/06-21-better-new-logs.md new file mode 100644 index 000000000..4b098a1d2 --- /dev/null +++ b/content/changelog/2024/06-21-better-new-logs.md @@ -0,0 +1,34 @@ +--- +title: Better new Logs +date: 2024-06-21 +tags: + - console + - logs +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Pierre De Soyres + link: https://github.com/pdesoyres-cc + image: https://github.com/pdesoyres-cc.png?size=40 +description: Lots of new features included! +aliases: +- /changelog/2024-06-21-better-new-logs +excludeSearch: true +--- + +We recently introduced a new Logs interface for applications in [the Console](https://console.clever-cloud.com), available on-demand in public beta. Since, we listened customers feedbacks and improved this feature. An updated version is now available, with two modes in the text filter field: + +- Exact match (case-sensitive) +- Regular expression + +You can select one or the other using the buttons to the right of the text field. This is only a first step, as we'll later introduce a new stack with indexed logs to better handle such filters and provide new features. + +![New logs interface](/images/new-logs-update.webp) + +Some of you also asked for a change of the default behavior of this Logs interface. Until now, users were redirected to `Live` view during a deployment, otherwise to the `7 days` view, containing all available deployments/instances, with logs of the last deployment shown. We today introduce a new mechanism and now remember the last choice of a user, per application. + +Depending on your feedback, we'll improve this further in the coming weeks. Here again, this is a first step as the indexed logs will open up a wide range of possibilities in this area. + +* Share your comments and ideas on our [GitHub Community](https://github.com/CleverCloud/Community/discussions/categories/new-logs-interface) + diff --git a/content/changelog/2024/06-28-new-ip-list-paris.md b/content/changelog/2024/06-28-new-ip-list-paris.md new file mode 100644 index 000000000..1b31d02ac --- /dev/null +++ b/content/changelog/2024/06-28-new-ip-list-paris.md @@ -0,0 +1,34 @@ +--- +title: IP list update on Paris zone +date: 2024-06-28 +tags: + - domain + - IP +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: A big step forward for our open source reverse proxy +aliases: +- /changelog/2024-06-28-new-ip-list-paris +excludeSearch: true +--- + +As our network evolves, we've updated [IP list for Paris (PAR) zone](/developers/doc/administrate/domain-names/#your-application-runs-in-the-europeparis-par-zone). If you use A records for DNS configuration, update them. 4 new IP addresses should be added (`91.208.207.220` to `91.208.207.223`). **We strongly recommend using CNAME records instead.** + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.par.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 91.208.207.214`
`@ 10800 IN A 91.208.207.215`
`@ 10800 IN A 91.208.207.216`
`@ 10800 IN A 91.208.207.217`
`@ 10800 IN A 91.208.207.218`
`@ 10800 IN A 91.208.207.220`
`@ 10800 IN A 91.208.207.221`
`@ 10800 IN A 91.208.207.222`
`@ 10800 IN A 91.208.207.223` | + +We are going to remove 4 IPs that **you must stop to use between now and August 23rd**: + +- 46.252.181.103 +- 46.252.181.104 +- 185.42.117.108 +- 185.42.117.109 + + After this date, they won't answer to requests anymore. You'll find the updated values in the `Domain names` section of your application in [the Console](https://console.clever-cloud.com). If you have any question about this change, feel free to ask [our customer support](https://console.clever-cloud.com/ticket-center-choice) about it. diff --git a/content/changelog/2024/07-01-matomo-5.1.0.md b/content/changelog/2024/07-01-matomo-5.1.0.md new file mode 100644 index 000000000..46c9100e2 --- /dev/null +++ b/content/changelog/2024/07-01-matomo-5.1.0.md @@ -0,0 +1,25 @@ +--- +title: Matomo v5.1.0 is available +date: 2024-07-01 +tags: + - addons + - matomo +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +description: You can now deploy Matomo v5.1.0 on Clever Cloud +aliases: +- /changelog/2024-07-01-matomo-5.1.0 +excludeSearch: true +--- + +Our [Matomo](https://matomo.org/) add-on has been updated to version `5.1.0` which is now used by default. You can deploy this latest release from our [Console](https://console.clever-cloud.com) or [Clever Tools](https://github.com/CleverCloud/clever-tools). Existing customers add-ons are already up-to-date. + +Here are the changes since previous deployed version (`5.0.1`): +- [Learn more about Matomo 5.0.2](https://matomo.org/changelog/matomo-5-0-2/) +- [Learn more about Matomo 5.0.3](https://matomo.org/changelog/matomo-5-0-3/) +- [Learn more about Matomo 5.1.0](https://matomo.org/changelog/matomo-5-1-0/) diff --git a/content/changelog/2024/07-02-clever-tools-3.8.0.md b/content/changelog/2024/07-02-clever-tools-3.8.0.md new file mode 100644 index 000000000..c80bbe2cd --- /dev/null +++ b/content/changelog/2024/07-02-clever-tools-3.8.0.md @@ -0,0 +1,67 @@ +--- +title: 'Clever Tools 3.8: "Big Summer Update" is available' +date: 2024-07-02 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Better manage your apps, lots of new features +aliases: +- /changelog/2024-07-02-clever-tools-3.8.0 +excludeSearch: true +--- + +[Clever Tools 3.8](https://github.com/CleverCloud/clever-tools/releases/tag/3.8.0) is now available. It's an important release, as we've worked on some of its features for several weeks. + +## Brand new application management + +It introduces a complete new way to use our CLI with `--app` option, available to every application-related commands. It allows you to target any application available from your account, by its ID or its name. You can for example restart an application this way: + +```bash +clever restart --app app_id +clever restart --app my_app_name +clever restart --app my_app_name --org my_org_name +``` +`clever applications list` new command can be used from any folder of your system. It prints details about applications across your organisations. You can filter the result with `--org` or `-o` option. It includes IDs, names and local aliases (if available) in a table. + +## More (consistent) options + +For most commands, you can now get a result in the format of your choice with `--format` or `-F` option. In most cases, you can use `human` (default) or `json`, but sometimes `json-stream` or `shell` are available too (for example). + +You can now define when to stop logs streaming during a `clever deploy` or a `clever restart` with `exit-on` option. Available values are: `deploy-start`, `deploy-end` and `never` (default: `deploy-end`). Thus, the `--follow` option is now deprecated. + +Of course, you can combine these new options: + +```bash +# We show ID and name of all applications in JSON format +clever applications list --org my_org_name --format json | jq '.[].applications[] | {app_id, name}' + +# We check status of an application +clever status --app app_id_or_name -F json | jq '.status' + +# If it's running, we restart it and stop the logs streaming when the deployment starts +clever restart --app app_id_or_name --exit-on deploy-start +``` + +These changes are available thanks to a `cliparse` update [introducing private options](https://github.com/CleverCloud/cliparse-node/commit/023bd72ddce66337c5b0716ddb3c2a103ff252a8). + +## Lots of new features + +Multiple new features are also available in this "Big Summer Update". Access Logs feature now uses `v4` API. It's faster and more reliable, only available for applications and as an alpha test for now. It's available through `clever accesslogs` command. + +`--no-color` or `--color true|false` global option is available. It's used by default when the output is not a terminal. `clever console` now opens the [Console](https://console.clever-cloud.com) even if your not in a folder with a linked application. [3.8.1 release](https://github.com/CleverCloud/clever-tools/releases/tag/3.8.1) comes with some minor fixes. + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install) + +``` +npm update -g clever-tools +clever version +``` + +Note that we reintroduced [Nix support](/developers/doc/cli/install/#nix-package-manager) with this release. diff --git a/content/changelog/2024/07-03-docker-terraform.md b/content/changelog/2024/07-03-docker-terraform.md new file mode 100644 index 000000000..495660dec --- /dev/null +++ b/content/changelog/2024/07-03-docker-terraform.md @@ -0,0 +1,24 @@ +--- +title: Deploy Docker containers on Clever Cloud with Terraform (or OpenTofu) +date: 2024-07-03 +tags: + - docker + - terraform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +description: Manage your Docker containers on Clever Cloud with Terraform or compatible tools such as OpenTofu +aliases: +- /changelog/2024-07-03-docker-terraform +excludeSearch: true +--- + +To manage your resources as code on Clever Cloud, from applications to add-ons (object storage, databases, etc.), you can use our Terraform provider. It's compatible with tools such as [OpenTofu](https://opentofu.org/) and can now deploy applications using [our Docker runtime](/developers/doc/applications/docker/). + +You can define instances count or flavors, region, dependencies, ports, Dockerfile and application paths, registry credentials and more. Read [the full parameters list](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs/resources/docker). + +* Learn more about [our Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs) diff --git a/content/changelog/2024/07-04-apache-php-image-update.md b/content/changelog/2024/07-04-apache-php-image-update.md new file mode 100644 index 000000000..d8b48c007 --- /dev/null +++ b/content/changelog/2024/07-04-apache-php-image-update.md @@ -0,0 +1,24 @@ +--- +title: PHP 8.2.21 and 8.3.9 image update +date: 2024-07-04 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Apache 2.4.60 and Composer 2.7.7 also included +aliases: +- /changelog/2024-07-04-apache-php-image-update +excludeSearch: true +--- + +We've updated our PHP image to support versions [8.2.21](https://www.php.net/ChangeLog-8.php#8.2.21) and [8.3.9](https://www.php.net/ChangeLog-8.php#8.3.9): +* They fix a bug [introduced](https://github.com/api-platform/core/issues/6416) in 8.2.20 and 8.3.8 which we had previously patched +* This image includes a fix for GnuPG extension +* PHP info apps are up-to-date: [8.2](https://php82info.cleverapps.io) and [8.3](https://php83info.cleverapps.io) + +Over the past few weeks, we have also included [Apache 2.4.60](https://dlcdn.apache.org/httpd/CHANGES_2.4.60), fixing CVE-2024-36387, 38472, 38473, 38474, 38475, 38476, 38477, 39573 and [Composer 2.7.7](https://github.com/composer/composer/releases/tag/2.7.7), fixing CVE-2024-35241, 35242. + +* Learn more about [PHP on Clever Cloud](/developers/doc/applications/php/) diff --git a/content/changelog/2024/07-05-go-haskell-ruby-update.md b/content/changelog/2024/07-05-go-haskell-ruby-update.md new file mode 100644 index 000000000..9a6813323 --- /dev/null +++ b/content/changelog/2024/07-05-go-haskell-ruby-update.md @@ -0,0 +1,25 @@ +--- +title: Go, Haskell and Ruby images update +date: 2024-07-05 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Some fixes and new versions +aliases: +- /changelog/2024-07-05-go-haskell-ruby-update +excludeSearch: true +--- + +We've updated some of our images: + +* **Go:** + * Default to 1.22.5 + * Fixes CVE-2024-2479 +* **Haskell:** + * Includes Stack 2.15.7 +* **Ruby:** + * Supports 3.1.6, 3.3.2 and 3.3.3 diff --git a/content/changelog/2024/07-06-mysql-pgsql-update.md b/content/changelog/2024/07-06-mysql-pgsql-update.md new file mode 100644 index 000000000..245ea12c0 --- /dev/null +++ b/content/changelog/2024/07-06-mysql-pgsql-update.md @@ -0,0 +1,25 @@ +--- +title: MySQL and PostgreSQL update +date: 2024-07-06 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: And some new extensions/versions for PostgreSQL +aliases: +- /changelog/2024-07-06-mysql-pgsql-update +excludeSearch: true +--- + +We've updated some of our database services: + +* **MySQL:** + * Version 8.0.34-26 +* **PostgreSQL:** + * Version 15.7 + * `pgvector` extension 0.7.1 + * `timescaledb` extension 2.14.2 + * `pg_ivm` extension 1.8 is now available (ask it to [our support team](https://console.clever-cloud.com/ticket-center-choice)) diff --git a/content/changelog/2024/07-10-CVE-2024-6387.md b/content/changelog/2024/07-10-CVE-2024-6387.md new file mode 100644 index 000000000..48dc6b7dd --- /dev/null +++ b/content/changelog/2024/07-10-CVE-2024-6387.md @@ -0,0 +1,25 @@ +--- +title: "regreSSHion (CVE-2024-6387): our response" +date: 2024-07-10 +tags: + - security +authors: + - name: Arnaud Lefebvre + link: https://github.com/BlackYoup + image: https://github.com/BlackYoup.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: All our systems are up-to-date +aliases: +- /changelog/2024-07-10-cve-2024-6387 +excludeSearch: true +--- + +On July 1st, we were informed that an unauthenticated Remote Code Execution (RCE) vulnerability that could grant an attacker full root access was found in OpenSSH’s server (`sshd`) on glibc-based Linux systems. Our security team instantly made sanity checks, and listed impacted services. + +As stated [by Qualys](https://www.qualys.com/regresshion-cve-2024-6387/), « *versions from 4.4p1 up to, but not including, 8.5p1 are not vulnerable due to a transformative patch for CVE-2006-5051, which made a previously unsafe function secure. The vulnerability resurfaces in versions from 8.5p1 up to, but not including, 9.8p1 due to the accidental removal of a critical component in a function.* ». + +There was no known exploit for 64-bit systems, but we immediately strengthened firewall rules for port 22 and packaged OpenSSH 9.8p1. Then we deployed it on all our systems, images, managed services and started to redeploy applications gradually for our customers. This work is now completed on all our servers and thousands of virtual machines without any impact. + +You can contact [our support team](https://console.clever-cloud.com/ticket-center-choice) if you have further questions about this topic. \ No newline at end of file diff --git a/content/changelog/2024/07-11-pulsar-3.3.0-update.md b/content/changelog/2024/07-11-pulsar-3.3.0-update.md new file mode 100644 index 000000000..a6f79769b --- /dev/null +++ b/content/changelog/2024/07-11-pulsar-3.3.0-update.md @@ -0,0 +1,19 @@ +--- +title: "Pulsar 3.3.0 is available" +date: 2024-07-11 +tags: + - addons + - pulsar +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: New API endpoint and stack update +aliases: +- /changelog/2024-07-11-pulsar-3.3.0-update +excludeSearch: true +--- + +[Apache Pulsar 3.3.0](https://github.com/apache/pulsar/releases/tag/v3.3.0) is deployed on our platform. It brings lots of fixes and some new features. + +- Learn more about [Apache Pulsar](https://www.clever-cloud.com/product/pulsar/) on Clever Cloud diff --git a/content/changelog/2024/07-12-accountant-access-console-fix.md b/content/changelog/2024/07-12-accountant-access-console-fix.md new file mode 100644 index 000000000..7859f5655 --- /dev/null +++ b/content/changelog/2024/07-12-accountant-access-console-fix.md @@ -0,0 +1,20 @@ +--- +title: "Console: a fix for accountant access" +date: 2024-07-12 +tags: + - console + - fix +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florian Sanders + link: https://github.com/florian-sanders-cc + image: https://github.com/florian-sanders-cc.png?size=40 +description: You won't be constantly disconnected anymore +aliases: +- /changelog/2024-07-12-accountant-access-console-fix +excludeSearch: true +--- + +Users with an "accountant" role were constantly disconnected from the Console. This issue has been fixed. diff --git a/content/changelog/2024/07-17-keycloak-public-release.md b/content/changelog/2024/07-17-keycloak-public-release.md new file mode 100644 index 000000000..8312a01b2 --- /dev/null +++ b/content/changelog/2024/07-17-keycloak-public-release.md @@ -0,0 +1,22 @@ +--- +title: "Keycloak add-on in public alpha" +date: 2024-07-17 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Try it and give us feedback +aliases: +- /changelog/2024-07-17-keycloak-public-release +excludeSearch: true +--- + +Clever Cloud provides a Keycloak add-on, developed with Please Open-it, for some months in private alpha. We're releasing it publicly, with a new version and some fixes. Any Clever Cloud user can now deploy a Keycloak service from [API](/developers/api/), [Clever Tools](https://github.com/CleverCloud/clever-tools) or [Console](https://console.clever-cloud.com) and use it. If you have any question or feedback, use our [GitHub Community space](https://github.com/CleverCloud/Community/discussions/categories/keycloak). + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak/) \ No newline at end of file diff --git a/content/changelog/2024/07-17-new-logs-default.md b/content/changelog/2024/07-17-new-logs-default.md new file mode 100644 index 000000000..1fdfcf5ab --- /dev/null +++ b/content/changelog/2024/07-17-new-logs-default.md @@ -0,0 +1,21 @@ +--- +title: "Console: new logs interface is now used by default" +date: 2024-07-17 +tags: + - console + - logs +authors: + - name: Pierre De Soyres + link: https://github.com/pdesoyres-cc + image: https://github.com/pdesoyres-cc.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + +description: Final countdown +aliases: +- /changelog/2024-07-17-new-logs-default +excludeSearch: true +--- + +New logs interface is available in the Console in public beta [for some months](../04-15-new-logs-interface-public-beta/), and we already [enhanced it](../06-21-better-new-logs/). We're now confident enough to use it by default. You can still disable it. If you have any question or feedback, use our [GitHub Community space](https://github.com/CleverCloud/Community/discussions/categories/new-logs-interface). \ No newline at end of file diff --git a/content/changelog/2024/07-18-elastic-8.10.2-jenkins-2.452.3.md b/content/changelog/2024/07-18-elastic-8.10.2-jenkins-2.452.3.md new file mode 100644 index 000000000..0ef2f7240 --- /dev/null +++ b/content/changelog/2024/07-18-elastic-8.10.2-jenkins-2.452.3.md @@ -0,0 +1,26 @@ +--- +title: "Elasticsearch and Jenkins update" +date: 2024-07-18 +tags: + - addons + - update +authors: + - name: Aurélien Hebert + link: https://github.com/aurrelhebert + image: https://github.com/aurrelhebert.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Elasticsearch 8.1.0 and Jenkins 2.452.3 are now available +aliases: +- /changelog/2024-07-18-elastic-8.10.2-jenkins-2.452.3 +excludeSearch: true +--- + +We've updated Elasticsearch and Jenkins services: + +* **Elasticsearch:** + * Version 8.10.2 +* **Jenkins:** + * New add-ons are deployed with version 2.452.3 and Java 21 + * Existing Jenkins were upgraded to Java 17 diff --git a/content/changelog/2024/07-18-github-action-review-apps.md b/content/changelog/2024/07-18-github-action-review-apps.md new file mode 100644 index 000000000..3a17d506e --- /dev/null +++ b/content/changelog/2024/07-18-github-action-review-apps.md @@ -0,0 +1,33 @@ +--- +title: "Version 1.0 of our GitHub Action for review applications is available" +date: 2024-07-18 +tags: + - github + - action +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Julia March + link: https://github.com/juliamrch + image: https://github.com/juliamrch.png?size=40 +description: Simplify your GitHubworkflows +aliases: +- /changelog/2024-07-18-github-action-review-apps +excludeSearch: true +--- + +Some months ago, Clever Cloud released [a new GitHub Action](https://github.com/marketplace/actions/clever-cloud-review-app-on-prs) to deploy applications from GitHub to Clever Cloud. After some iterations, version 1.0 is available. We make it simpler to use by making it [composite](https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action)). Now you can just add this in your workflow for example: + +```yml +- name: Create review app + uses: CleverCloud/clever-cloud-review-app@latest + env: + CLEVER_SECRET: ${{ secrets.CLEVER_SECRET }} + CLEVER_TOKEN: ${{ secrets.CLEVER_TOKEN }} + ORGA_ID: ${{ secrets.ORGA_ID }} + with: + type: '' +``` + +- [Learn more about how to deploy from GitHub to Clever Cloud](/developers/doc/ci-cd/github/) \ No newline at end of file diff --git a/content/changelog/2024/07-26-domains-console-update.md b/content/changelog/2024/07-26-domains-console-update.md new file mode 100644 index 000000000..683080681 --- /dev/null +++ b/content/changelog/2024/07-26-domains-console-update.md @@ -0,0 +1,27 @@ +--- +title: "Console: new Domains management interface" +date: 2024-07-26 +tags: + - console + - domains +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florian Sanders + link: https://github.com/florian-sanders-cc + image: https://github.com/florian-sanders-cc.png?size=40 +description: Did you know about path routing? +aliases: +- /changelog/2024-07-26-domains-console-update +excludeSearch: true +--- + +We've upgraded the applications' Domains page in the Console. It's now more clear, complete and easy to use. We designed it to highlight some of our underrated features such as [path routing](/developers/doc/administrate/domain-names/#path-routing). You also now have: + +- A unique form to add a custom domain or a test domain (`cleverapps.io`) +- A unique list of test and custom domains +- A direct link to add your own certificate +- Clearer error messages/warnings +- Clearer instructions about DNS configuration and IP lists +- Better accessibility, responsiveness, internationalization diff --git a/content/changelog/2024/07-30-github-action-1.1.md b/content/changelog/2024/07-30-github-action-1.1.md new file mode 100644 index 000000000..1ecbcd9b7 --- /dev/null +++ b/content/changelog/2024/07-30-github-action-1.1.md @@ -0,0 +1,22 @@ +--- +title: "Version 1.1 of our GitHub Action for review applications is available" +date: 2024-07-30 +tags: + - github + - action +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Julia March + link: https://github.com/juliamrch + image: https://github.com/juliamrch.png?size=40 +description: Better, simpler GitHub Action +aliases: +- /changelog/2024-07-30-github-action-1.1 +excludeSearch: true +--- + +Update for [GitHub Action](https://github.com/marketplace/actions/clever-cloud-review-app-on-prs) to deploy applications from GitHub to Clever Cloud. Version 1.1 simplifies workflow files and gives conditional comments depending on the actions performed on the PR (deploy, update, delete). + +- [Learn more about how to deploy from GitHub to Clever Cloud](/developers/doc/ci-cd/github/) \ No newline at end of file diff --git a/content/changelog/2024/08-01-lagging-server-crate.md b/content/changelog/2024/08-01-lagging-server-crate.md new file mode 100644 index 000000000..9e60e2076 --- /dev/null +++ b/content/changelog/2024/08-01-lagging-server-crate.md @@ -0,0 +1,22 @@ +--- +title: "Lagging server: our Sōzu testing tool available as a Rust Crate" +date: 2024-08-01 +tags: + - sōzu + - tools +authors: + - name: Emmanuel Bosquet + link: https://github.com/Keksoj + image: https://github.com/Keksoj.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: n2 is the new n1 +aliases: +- /changelog/2024-08-01-lagging-server-crate +excludeSearch: true +--- + +When we release new versions of our reverse proxy [Sōzu](https://www.sozu.io), we now systematically run performances tests. To conduct some of them directly from our CI, we developed a small tool: Lagging Server. It's open source, and now [available as a Rust crate](https://crates.io/crates/lagging_server) anyone can use. + +* Learn more about [Lagging Server](https://github.com/CleverCloud/lagging_server) {{< icon "github" >}} \ No newline at end of file diff --git a/content/changelog/2024/08-09-python-3.12-update.md b/content/changelog/2024/08-09-python-3.12-update.md new file mode 100644 index 000000000..ec856d571 --- /dev/null +++ b/content/changelog/2024/08-09-python-3.12-update.md @@ -0,0 +1,28 @@ +--- +title: "Docker and Python image update" +date: 2024-08-09 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Aurélien Hebert + link: https://github.com/s0dyy + image: https://github.com/s0dyy.png?size=40 +description: Python 3.12 support and lighter Docker image +aliases: +- /changelog/2024-08-09-python-3.12-update +excludeSearch: true +--- + +We've updated Docker and Python image and deployed them without any impact for our users. + +* **Common:** + * Linux kernel 6.10.2 +* **Docker:** + * Lighter updated image +* **Python:** + * Python 3.12 support + * A fix for missing system locales diff --git a/content/changelog/2024/08-26-java-containers-update.md b/content/changelog/2024/08-26-java-containers-update.md new file mode 100644 index 000000000..0a44c27d3 --- /dev/null +++ b/content/changelog/2024/08-26-java-containers-update.md @@ -0,0 +1,22 @@ +--- +title: "Java servlet containers cleanup, Wildfly upgrade" +date: 2024-08-26 +tags: + - applications + - java +authors: + - name: Julien Durillon + link: https://github.com/judu + image: https://github.com/judu.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Wildfly 27.0.1 and 33.0.1 are now supported +aliases: +- /changelog/2024-08-26-java-containers-update +excludeSearch: true +--- + +As part of our images' enhancement process, we've tidied up the [list of supported servlet containers](/developers/doc/applications/java/java-war/#available-containers). Those that are no longer used by our customers are removed from the Java image. If you need a container which is not listed in [the servlet container list](/developers/doc/applications/java/java-war/#available-containers) or a specific version, please contact [our support team](https://console.clever-cloud.com/ticket-center-choice). This release also includes a [Wildfly](https://github.com/wildfly/wildfly) upgrade. Versions 27.0.1 and 33.0.1 are now available. + +- Learn more about [Java on Clever Cloud](/developers/doc/applications/java/) diff --git a/content/changelog/2024/08-30-deploy-url-mtl.md b/content/changelog/2024/08-30-deploy-url-mtl.md new file mode 100644 index 000000000..f86e8ba0b --- /dev/null +++ b/content/changelog/2024/08-30-deploy-url-mtl.md @@ -0,0 +1,30 @@ +--- +title: "Montreal (MTL) zone: new deployment URL" +date: 2024-08-30 +tags: + - applications + - montreal +authors: + - name: Arnaud Lefebvre + link: https://github.com/BlackYoup + image: https://github.com/BlackYoup.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: n2 is the new n1 +aliases: +- /changelog/2024-08-30-deploy-url-mtl +excludeSearch: true +--- + +We improved our git services on Montreal zone. Newly created applications now use `push-n2-mtl-clevercloud-customers.services.clever-cloud.com` as deployment URL. Applications still using the previous URL starting with `push-n1` won't be impacted by this change. If the new URL is not in your known hosts, you can see a warning during `git+ssh` operations: + +``` +❯ git clone git+ssh://git@push-n2-mtl-clevercloud-customers.services.clever-cloud.com/app_xxx.git +Cloning into 'app_xxx'… +The authenticity of host 'push-n2-mtl-clevercloud-customers.services.clever-cloud.com (192.99.188.152)' can't be established. +… +This host key is known by the following other names/addresses: + ~/.ssh/known_hosts:2142: push-n1-mtl-clevercloud-customers.services.clever-cloud.com +Are you sure you want to continue connecting (yes/no/[fingerprint])? +``` diff --git a/content/changelog/2024/09-03-gitlab-components-review-apps.md b/content/changelog/2024/09-03-gitlab-components-review-apps.md new file mode 100644 index 000000000..7aaf63841 --- /dev/null +++ b/content/changelog/2024/09-03-gitlab-components-review-apps.md @@ -0,0 +1,24 @@ +--- +title: "Version 2.0 of our GitLab Component for review applications is available" +date: 2024-09-03 +tags: + - gitlab + - component +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Julia March + link: https://github.com/juliamrch + image: https://github.com/juliamrch.png?size=40 +description: Simplify your GitLab workflows +aliases: +- /changelog/2024-09-03-gitlab-components-review-apps +excludeSearch: true +--- + +Some months ago, we released [a new GitLab Component](https://gitlab.com/explore/catalog/CleverCloud/clever-cloud-pipeline) to deploy applications from GitLab to Clever Cloud. Version 2.0 is available with variables injection from GitLab CI/CD and automatic releases. You can now use it with the `latest` tag for tests, or `2.0.1` tag for production. + +**Breaking changes**: Input `deploy` have been removed to prevent users to script the environment variables injection before deploying the app. Remove it from your `.gitlab-ci.yml` file if it's set up, to avoid breaking your pipeline. + +- [Learn more about how to deploy from GitLab to Clever Cloud](/developers/doc/ci-cd/gitlab/) diff --git a/content/changelog/2024/09-12-clever-tools-3.8.3.md b/content/changelog/2024/09-12-clever-tools-3.8.3.md new file mode 100644 index 000000000..cbdee0696 --- /dev/null +++ b/content/changelog/2024/09-12-clever-tools-3.8.3.md @@ -0,0 +1,27 @@ +--- +title: 'Clever Tools 3.8.3 is available' +date: 2024-09-12 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Last minors updates before a big change +aliases: +- /changelog/2024-09-12-clever-tools-3.8.3 +excludeSearch: true +--- + +After two minor releases fixing issues with drains, [Clever Tools 3.8.3](https://github.com/CleverCloud/clever-tools/releases/tag/3.8.3) is available. It fixes Nix support, `update-notifier` and enhances the add-on deletion command. It will now only need the add-on ID or name if it's in an organisation linked to your account. + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2024/09-12-js-client-9.0.0.md b/content/changelog/2024/09-12-js-client-9.0.0.md new file mode 100644 index 000000000..49d2c39b2 --- /dev/null +++ b/content/changelog/2024/09-12-js-client-9.0.0.md @@ -0,0 +1,20 @@ +--- +title: 'JS Client 9.0 is available' +date: 2024-09-12 +tags: + - client + - javascript +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: A must have for next packaging of clever tools +aliases: +- /changelog/2024-09-12-js-client-9.0.0 +excludeSearch: true +--- + +We released [Clever Cloud JS client 9.0.0](https://github.com/CleverCloud/clever-client.js/blob/master/CHANGELOG.md#900-2024-09-11). It computes OAuth v1 signature with Web Crypto for all platforms (Browser, Node.js, Deno, Bun, CF workers, etc.) instead of relying on `node:crypto`. This will simplify usage of the client with a bundler. \ No newline at end of file diff --git a/content/changelog/2024/10-01-materia-kv-ttl-layer-update.md b/content/changelog/2024/10-01-materia-kv-ttl-layer-update.md new file mode 100644 index 000000000..953a00f54 --- /dev/null +++ b/content/changelog/2024/10-01-materia-kv-ttl-layer-update.md @@ -0,0 +1,23 @@ +--- +title: 'Materia KV: layer update, with TTL support' +date: 2024-10-01 +tags: + - Materia KV + - TTL +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Get ready for more commands and layers soon +aliases: +- /changelog/2024-10-01-materia-kv-ttl-layer-update +excludeSearch: true +--- + +After the first release of our [Materia KV add-on](/developers/doc/addons/materia-kv), we discussed with users and what they wanted to see in the next version. A major milestone for us was to add support for `TTL` (Time To Live) command, and those related to it such as `EXPIRE`, `PEXPIRE`, `PTTL`, `SET EX`. It's now available and will helps us, for example, to bring Materia KV support to PHP sessions. + +This new release of our Redis API compatible layer brings a new design, helping us to better support more commands in the future. In the meantime, we've retired hash and list commands, to enhance them. They will be back soon. Some others are added, like `CLIENT ID`, `DECRBY`, `INCRBY`,`GETBIT`, `SETBIT`, etc. + +If you have any questions or feedback, let's discuss it on our [GitHub Community](https://github.com/CleverCloud/Community/discussions/categories/materia). + +- [The full Materia KV commands list](/developers/doc/addons/materia-kv/#supported-types-and-commands). diff --git a/content/changelog/2024/10-01-python-image-changes.md b/content/changelog/2024/10-01-python-image-changes.md new file mode 100644 index 000000000..97cf5785e --- /dev/null +++ b/content/changelog/2024/10-01-python-image-changes.md @@ -0,0 +1,41 @@ +--- +title: "Python image: what's new and what's to come" +date: 2024-10-01 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: uv, Python 3.13 and some clean up +aliases: +- /changelog/2024-10-01-python-image-changes +excludeSearch: true +--- + +Python ecosystem is diverse, with lots of legacy versions and practices. But in the recent months, it evolved on many fronts. So, we've decided to handle it and start to revise how you can deploy Python applications on Clever Cloud. + +## Package management: uv on Clever Cloud + +We only support [pip](https://packaging.python.org/en/latest/tutorials/installing-packages/), `requirements.txt` and `setup.py` natively. For some weeks, we've included [uv](https://docs.astral.sh/uv/getting-started/features/) in our Python image to make some tests. Based on Rust, this package and project manager is compliant with existing ecosystem and blazing fast. [It's now a part](/developers/doc/applications/python/#use-uv-as-a-package-manager) of our "Enthusiast tools" initiative and will be updated regularly. Thus, there is no active support for it yet. + +We'll enhance its native support in coming releases of our Python image. + +* [Learn more about uv](https://github.com/astral-sh/uv) {{< icon "github" >}} + +## Python versions: time to clean up + +We're in 2024 and Python 2.x still coexists with Python 3.x. As it's always used by some of our customers, we've decided to continue to support it. Python 3.x is now the default version for new Python applications. We'll make this change for other runtimes (where Python is also included), starting 2025. If you need Python 2.x, set `CC_PYTHON_VERSION=2` in your applications. + +We'll also get closer to [the official Python release cycle](https://devguide.python.org/versions/#python-release-cycle), which is 5 years of support. Thus, we'll stop using Python 3.7 starting December 1st, 2024. Next year, we'll deprecate Python 3.8 and stop providing it. If an application is asking for a deprecated version, it will use the latest available by default. So, upgrade your `CC_PYTHON_VERSION` towards your needs. + +If you need to sideload unsupported Python versions, `uv` [can help you](https://docs.astral.sh/uv/guides/install-python/). You can also deploy your applications through [Docker](/developers/doc/applications/docker), but you should avoid to use end of life runtime in your applications. + +* Learn more about [Python on Clever Cloud](/developers/doc/applications/python/) + +## What's next? + +We'll enhance our Python images to better support modern Python ecosystem and simplify the deployment process. Python 3.13, [released today](https://docs.python.org/3.13/whatsnew/3.13.html), will be available on Clever Cloud in the coming weeks. + +If you have any questions or suggestions, feel free to tell us on [our community page](https://github.com/CleverCloud/Community/discussions/categories/paas-runtimes). diff --git a/content/changelog/2024/10-04-keycloak-beta-release.md b/content/changelog/2024/10-04-keycloak-beta-release.md new file mode 100644 index 000000000..052453b53 --- /dev/null +++ b/content/changelog/2024/10-04-keycloak-beta-release.md @@ -0,0 +1,26 @@ +--- +title: "Keycloak updated to 25.0.6, now in public beta" +date: 2024-10-04 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Release 26 is coming +aliases: +- /changelog/2024-10-04-keycloak-beta-release +excludeSearch: true +--- + +Clever Cloud's Keycloak add-on, developed with Please Open-it, is now available in public beta. We enhanced user experience, performances and features since [the alpha stage](../07-17-keycloak-public-release/). We revised the default configuration of underlying resources. We now use a `S flavored` Java application with more memory and a XXS Small Space PostgreSQL database which is enough for low-volume needs. Of course, you can change it according to your needs at any time. + +The default Keycloak version is now 25.0.6. If you want to upgrade, change the `CC_KEYCLOAK_VERSION` environment variable to `25.0.6` and restart the Java application. You can also add the new `CC_METRICS_PROMETHEUS_PATH=/metrics` and `CC_METRICS_PROMETHEUS_PORT=9000`to access metrics [from Grafana](/developers/doc/metrics/#publish-your-own-metrics). + +We plan to upgrade to [26.x](https://github.com/keycloak/keycloak/releases/tag/26.0.0) in the next few weeks after checking its stability and validating it for our platform. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak/) diff --git a/content/changelog/2024/10-07-CVE-2024-47561.md b/content/changelog/2024/10-07-CVE-2024-47561.md new file mode 100644 index 000000000..0629706de --- /dev/null +++ b/content/changelog/2024/10-07-CVE-2024-47561.md @@ -0,0 +1,18 @@ +--- +title: "CVE-2024-47561: we upgraded Avro and Apache Pulsar" +date: 2024-10-07 +tags: + - security +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: All our systems are up-to-date +aliases: +- /changelog/2024-10-07-cve-2024-47561 +excludeSearch: true +--- + +On October 4th, we were informed of [a schema parsing vulnerability](https://nvd.nist.gov/vuln/detail/CVE-2024-47561) in the Java SDK of Apache Avro 1.11.3 and previous versions, allowing bad actors to execute arbitrary code. Our security team instantly made sanity checks, and listed impacted services. + +We upgraded our tools using Avro to 1.11.4. As Apache Pulsar was impacted, we upgraded our cluster to [version 3.3.2](https://github.com/apache/pulsar/releases/tag/v3.3.2). The complete rolling of these updates is now ended, without any impact to our users. You can contact [our support team](https://console.clever-cloud.com/ticket-center-choice) if you have further questions about this topic. \ No newline at end of file diff --git a/content/changelog/2024/10-17-sozu-1.0.5.md b/content/changelog/2024/10-17-sozu-1.0.5.md new file mode 100644 index 000000000..1d716de94 --- /dev/null +++ b/content/changelog/2024/10-17-sozu-1.0.5.md @@ -0,0 +1,23 @@ +--- +title: Sōzu 1.0.5 is available and deployed +date: 2024-10-17 +tags: + - sozu +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: Lots of fixes and improvements before the 1.1.0 release +aliases: +- /changelog/2024-10-17-sozu-1.0.5 +excludeSearch: true +--- + +[Sōzu](https://www.sozu.io) 1.0.5 is now available and deployed on `cleverapps.io` domains, we're progressively rolling it out on our own domains and dedicated load balancers. Since [the release of Sōzu 1.0.2](../06-07-sozu-1.0.2) we've fixed some bugs, improved CLI, metrics and performances. + +We're currently testing the 1.1.0 release candidate of Sōzu, with HTTP/2 support, coming soon on Clever Cloud. + +* Learn more about [Sōzu new releases](https://github.com/sozu-proxy/sozu/releases) {{< icon "github" >}} \ No newline at end of file diff --git a/content/changelog/2024/10-18-azimutt-available.md b/content/changelog/2024/10-18-azimutt-available.md new file mode 100644 index 000000000..620b4d700 --- /dev/null +++ b/content/changelog/2024/10-18-azimutt-available.md @@ -0,0 +1,27 @@ +--- +title: "Azimutt is available as an add-on on Clever Cloud" +date: 2024-10-18 +tags: + - addons + - azimutt +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: A new partner enters our Marketplace +aliases: +- /changelog/2024-10-18-azimutt-available +excludeSearch: true +--- + +Azimutt is [an open-source project](https://github.com/azimuttapp/azimutt) we follow for a long time. Created by Loïc Knuchel, it helps you to explore, analyze and manage your database in a pleasant graphical interface. It's a member of the [Clever Cloud startup program](https://www.clever-cloud.com/up-program/), for some weeks and now part of our [Marketplace](/developers/doc/marketplace/). Thus, you can create an Azimutt account, free or with a subscription, directly [from the Console](https://console.clever-cloud.com). + +You just have to provide a compatible database URI, hosted by Clever Cloud or not, and start exploring it. Our integration is based on a gateway hosted by Clever Cloud. No credentials are shared with Azimutt, and they're kept safely in your browser. + +Feel free to let us know what you think about this tool and if you want a deeper integration in [our GitHub Community](https://github.com/CleverCloud/Community/discussions/categories/dbaas). + +- [Learn more about Azimutt](https://azimutt.app/) +- [Azimutt documentation](https://azimutt.app/docs/) diff --git a/content/changelog/2024/10-21-clever-tools-3.9.0.md b/content/changelog/2024/10-21-clever-tools-3.9.0.md new file mode 100644 index 000000000..12cbf40c7 --- /dev/null +++ b/content/changelog/2024/10-21-clever-tools-3.9.0.md @@ -0,0 +1,43 @@ +--- +title: 'Clever Tools 3.9, with domain diagnostics and overview' +date: 2024-10-23 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Better manage your apps, lots of new features +aliases: +- /changelog/2024-10-21-clever-tools-3.9.0 +excludeSearch: true +--- + +[Clever Tools 3.9](https://github.com/CleverCloud/clever-tools/releases/tag/3.9.0) is available. It's the first minor release since our [Big Summer Update](../07-02-clever-tools-3.8.0/). Over the past few months, we've revamped many things under the hood, to clean the code and prepare next big changes we're working on. + +## List and diagnose your domains +This new version brings two new features to manage domains. First is `clever domain overview`, allowing you to list domains linked to your account, across all the organisations you manage. List only domains containing a specific text string in their name thanks to the `--filter` option. Use the `json` output (`--format`/`-F`) and tools such as [jless](https://jless.io/) to navigate through long lists easily. + +This feature uses a new "short" link for the Console, which doesn't require organisation or user ID: + +```bash +# The id can be an app_id, an addon_id or a real_id +https://console.clever-cloud.com/goto/id +``` + +The `clever domain diag` command allows you to check domains' configuration for an application, locally linked or targeted with the `--app` option. If some DNS records are wrong or missing, it will help you to know how to fix them. There is a `--filter` option to get only domains containing a specific text string in their name and a `--format`/`-F` option to output the result in `human` or `json`. + +## Post-creation instructions for add-ons and fixes + +This release also provides bug fixes, the token expiry date/time in `clever profile` and a better experience with add-ons like [Keycloak](/developers/doc/addons/keycloak/), [Matomo](/developers/doc/addons/matomo) or [Metabase](/developers/doc/addons/metabase/). Once created, you get post-creation instructions such as management/Console URL, temporary credentials and a link to the add-on's documentation. + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2024/10-28-metabase-available.md b/content/changelog/2024/10-28-metabase-available.md new file mode 100644 index 000000000..b80481955 --- /dev/null +++ b/content/changelog/2024/10-28-metabase-available.md @@ -0,0 +1,26 @@ +--- +title: "Metabase is available as an add-on on Clever Cloud" +date: 2024-10-28 +tags: + - addons + - metabase +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Analyze and explore your data with ease +aliases: +- /changelog/2024-10-28-metabase-available +excludeSearch: true +--- + +After some weeks of testing, the Clever Cloud's Metabase add-on, developed with [David Sferruzza](https://david.sferruzza.fr/), is available in public beta. Thus, you can deploy the service, from [Console](https://console.clever-cloud.com/users/me/addons/new), [API](/developers/api) or [Clever Tools](https://github.com/CleverCloud/clever-tools), and use it in minutes. + +It's based on a Java application and a PostgreSQL database. Once deployed you'll get a management URL to create an admin account. Then, just start using Metabase, add your data sources, create your questions and dashboards. You'll get benefits from the Clever Cloud's integration, with scalability options, database backups logs, metrics, easy version and upgrade management. + +Feel free to let us know what you think and ask your questions in [our GitHub Community](https://github.com/CleverCloud/Community/discussions/categories/metabase). + +- [Learn more about Metabase on Clever Cloud](/developers/doc/addons/metabase/) diff --git a/content/changelog/2024/10-28-pulsar-4.0.0-update.md b/content/changelog/2024/10-28-pulsar-4.0.0-update.md new file mode 100644 index 000000000..0469e4574 --- /dev/null +++ b/content/changelog/2024/10-28-pulsar-4.0.0-update.md @@ -0,0 +1,19 @@ +--- +title: "Pulsar 4.0.0 is available" +date: 2024-10-28 +tags: + - addons + - pulsar +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: And soon lots of news for Pulsar on Clever Cloud +aliases: +- /changelog/2024-10-28-pulsar-4.0.0-update +excludeSearch: true +--- + +[4.0.0 release of Apache Pulsar](https://github.com/apache/pulsar/releases/tag/v4.0.0) is deployed on our platform. It brings lots of new features and fixes, including enhanced `Key_Shared` subscription implementation, which helps us to resolve some recent issues. + +- Learn more about [Apache Pulsar](https://www.clever-cloud.com/product/pulsar/) on Clever Cloud diff --git a/content/changelog/2024/11-08-erlang-rust-update.md b/content/changelog/2024/11-08-erlang-rust-update.md new file mode 100644 index 000000000..cfc9e8aed --- /dev/null +++ b/content/changelog/2024/11-08-erlang-rust-update.md @@ -0,0 +1,32 @@ +--- +title: "Erlang and Rust images update, Redirection.io support" +date: 2024-11-08 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: New versions, tools, colors and more +excludeSearch: true +aliases: +- /changelog/2024-11-08-erlang-rust-update +- /changelog/2024-11-11-08-erlang-rust-update +--- + +We’ve updated Erlang and Rust images. They were deployed without any impact for our users. + +* **Common:** + * Linux kernel 6.11.6 + * Lighter Vector binary + * New build/deploy message with colors + * Users can now use multiple OpenVPN clients in a single instance +* **Erlang:** + * Elixir 1.17 + * Erlang 27.1.2 +* **Rust:** + * Rust 1.82.0 + * libassuan fix + +We also started to add [Redirection.io](https://redirection.io) agent in our images with this update, as part of our [Enthusiast Tools initiative](../10-01-python-image-changes/), and plan to ease its native support in coming releases. \ No newline at end of file diff --git a/content/changelog/2024/11-08-mysql-mysql-8.4.0.md b/content/changelog/2024/11-08-mysql-mysql-8.4.0.md new file mode 100644 index 000000000..ce058e700 --- /dev/null +++ b/content/changelog/2024/11-08-mysql-mysql-8.4.0.md @@ -0,0 +1,20 @@ +--- +title: MySQL 8.4 (LTS) is available +date: 2024-11-08 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Try the new branch now, and discover what's new +aliases: +- /changelog/2024-11-08-mysql-mysql-8.4.0 +excludeSearch: true +--- + +MySQL 8.4 is available on Clever Cloud. You can deploy it as a new add-on or migrate existing ones. As this is the first release (8.4.0) of this long term support (LTS) branch for the [Percona Server](https://www.percona.com/mysql/software/percona-server-for-mysql) we use, it's tagged as `early`. That means you should consider it mostly to make some tests and discover what's new. But we recommend [waiting a bit](https://www.percona.com/blog/severe-instability-of-mysql-8-0-38-8-4-1-and-9-0-resolved-in-upcoming-releases/) before using a new branch in production. + +* [Learn more about MySQL 8.4](https://www.percona.com/blog/mysql-8-4-first-peek/) +* [Learn more about MySQL on Clever Cloud](/developers/doc/addons/mysql/) diff --git a/content/changelog/2024/11-09-java-update.md b/content/changelog/2024/11-09-java-update.md new file mode 100644 index 000000000..3a34cff24 --- /dev/null +++ b/content/changelog/2024/11-09-java-update.md @@ -0,0 +1,26 @@ +--- +title: "Java 23 is available" +date: 2024-11-09 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: New versions, tools, colors and more +aliases: +- /changelog/2024-11-09-java-update +excludeSearch: true +--- + +We’ve updated Java image. It was deployed without any impact for our users. + + * Java 23 support + * Linux kernel 6.11.6 + * Lighter Vector binary + * New build/deploy message with colors + * [Redirection.io](https://redirection.io) agent is included in the image + * Users can now use multiple OpenVPN clients in a single instance + +As Java 22 is now [considered as end-of-life](https://www.oracle.com/fr/java/technologies/java-se-support-roadmap.html), we invite you to upgrade `CC_JAVA_VERSION` of your applications to `23` or to `21` (latest LTS). \ No newline at end of file diff --git a/content/changelog/2024/11-13-metabase-51-version-warning.md b/content/changelog/2024/11-13-metabase-51-version-warning.md new file mode 100644 index 000000000..e45140cd6 --- /dev/null +++ b/content/changelog/2024/11-13-metabase-51-version-warning.md @@ -0,0 +1,25 @@ +--- +title: "Metabase 51 is available" +date: 2024-11-13 +tags: + - addons + - metabase +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: New branch, better update instructions +aliases: +- /changelog/2024-11-13-metabase-51-version-warning +excludeSearch: true +--- + +The `x.51` branch of Metabase is now available on Clever Cloud. To update, just set `CC_METABASE_VERSION` of the add-on's Java application to `0.51` for the community edition or `1.51` for the enterprise edition (EE). We also added a warning message in logs if you modify the version to deploy and restart the application without rebuilding it. + +- [Learn more about Metabase on Clever Cloud](/developers/doc/addons/metabase/) +- [Learn more about Metabase 51](https://www.metabase.com/releases/metabase-51) + +{{< youtube id="oqoqSiVihdo" >}} diff --git a/content/changelog/2024/11-18-keycloak-26.md b/content/changelog/2024/11-18-keycloak-26.md new file mode 100644 index 000000000..116131276 --- /dev/null +++ b/content/changelog/2024/11-18-keycloak-26.md @@ -0,0 +1,24 @@ +--- +title: "Keycloak 26 is available with a new login theme" +date: 2024-11-18 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Lot of changes, just an environment variable to update +aliases: +- /changelog/2024-11-18-keycloak-26 +excludeSearch: true +--- + +The `26` branch of Keycloak is available on Clever Cloud. To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.0.5`. Newly created add-ons come with this release by default and an enhanced `clever-cloud` login theme. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak/) +- [Learn more about Keycloak 26](https://www.keycloak.org/2024/10/keycloak-2600-released.html) +- [Latest Keycloak releases](https://github.com/keycloak/keycloak/releases) diff --git a/content/changelog/2024/11-21-eol-warnings-console.md b/content/changelog/2024/11-21-eol-warnings-console.md new file mode 100644 index 000000000..ef24b35ad --- /dev/null +++ b/content/changelog/2024/11-21-eol-warnings-console.md @@ -0,0 +1,25 @@ +--- +title: "Console: end of life versions warnings" +date: 2024-11-21 +tags: + - console + - eol +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florian Sanders + link: https://github.com/florian-sanders-cc + image: https://github.com/florian-sanders-cc.png?size=40 +description: Better stay up to date! +aliases: +- /changelog/2024-11-21-eol-warnings-console +excludeSearch: true +--- + +[Earlier this year](../04-24-php-deprecate-warning/), we started to show warnings in logs when you deploy PHP applications with a `CC_PHP_VERSION` corresponding to a release considered as [end-of-life by PHP community](https://www.php.net/supported-versions.php). Today, we start showing such warnings in the environment variables panel of applications in the Clever Cloud Console for: +- `CC_PHP_VERSION` +- `CC_PYTHON_VERSION` +- `CC_RUBY_VERSION` + +Our goal is to better inform our customers about the lifecycle of their ecosystems, and to provide guidance on the proper values to use for the version management of their applications. We'll extend this to other runtimes in the coming weeks. diff --git a/content/changelog/2024/11-26-keycloak-26.0.06.md b/content/changelog/2024/11-26-keycloak-26.0.06.md new file mode 100644 index 000000000..109537205 --- /dev/null +++ b/content/changelog/2024/11-26-keycloak-26.0.06.md @@ -0,0 +1,24 @@ +--- +title: "Keycloak 26.0.6 is available (security update)" +date: 2024-11-26 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Thanks to Clever Cloud, it's easy to upgrade +aliases: +- /changelog/2024-11-26-keycloak-26.0.06 +excludeSearch: true +--- + +The release `26.0.6` of Keycloak is available on Clever Cloud. [It fixes](https://github.com/keycloak/keycloak/releases/26.0.6) some bugs, but also security issues: [CVE-2024-10451](https://nvd.nist.gov/vuln/detail/CVE-2024-10451), [CVE-2024-10270](https://nvd.nist.gov/vuln/detail/CVE-2024-10270), [CVE-2024-10492](https://nvd.nist.gov/vuln/detail/CVE-2024-10492), [CVE-2024-9666](https://nvd.nist.gov/vuln/detail/CVE-2024-9666) and [CVE-2024-10039](https://nvd.nist.gov/vuln/detail/CVE-2024-10039). + +To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.0.6` and rebuild it. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak) diff --git a/content/changelog/2024/11-27-clever-tools-3.10.md b/content/changelog/2024/11-27-clever-tools-3.10.md new file mode 100644 index 000000000..123d05eb4 --- /dev/null +++ b/content/changelog/2024/11-27-clever-tools-3.10.md @@ -0,0 +1,31 @@ +--- +title: 'Clever Tools 3.10 is available' +date: 2024-11-27 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Some tiny changes, before the huge ones +aliases: +- /changelog/2024-11-27-clever-tools-3.10 +excludeSearch: true +--- + +[Clever Tools 3.10](https://github.com/CleverCloud/clever-tools/releases/tag/3.10.0) is available. It includes some bug fixes on the `domain` command and supports [plugins activation](../11-27-elastic-plugins-support/) for Elasticsearch add-ons at creation (supported plugins list [is here](/developers/doc/addons/elastic/#plugins)). For example: + +```bash +clever addon create es-addon --option plugins=analysis-icu,mapper-murmur3 +``` + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2024/11-27-elastic-plugins-support.md b/content/changelog/2024/11-27-elastic-plugins-support.md new file mode 100644 index 000000000..c1f9c7e99 --- /dev/null +++ b/content/changelog/2024/11-27-elastic-plugins-support.md @@ -0,0 +1,22 @@ +--- +title: "Elasticsearch: plugins activation support" +date: 2024-11-22 +tags: + - addons + - elastic +authors: + - name: Aurélien Hebert + link: https://github.com/aurrelhebert + image: https://github.com/aurrelhebert.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: More flexibility for Elasticsearch add-ons +aliases: +- /changelog/2024-11-27-elastic-plugins-support +excludeSearch: true +--- + +When you create an Elasticsearch add-on, you can now activate plugins through [API](/developers/api) or the `--option` flag of [Clever Tools](/developers/doc/cli/addons/). You must pass the option as a comma-separated list: `plugins=plugin1,plugin2`. + +- Learn more about [Elasticsearch plugins support on Clever Cloud](/developers/doc/addons/elastic/#plugins) diff --git a/content/changelog/2024/11-28-kv-explorer-available.md b/content/changelog/2024/11-28-kv-explorer-available.md new file mode 100644 index 000000000..5ec0aa9fd --- /dev/null +++ b/content/changelog/2024/11-28-kv-explorer-available.md @@ -0,0 +1,31 @@ +--- +title: "Clever Cloud KV Explorer is available for Materia KV and Redis® add-ons" +date: 2024-11-28 +tags: +- addons +- kv +authors: + - name: Pierre De Soyres + link: https://github.com/pdesoyres-cc + image: https://github.com/pdesoyres-cc.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Lot of changes, just an environment variable to update +aliases: +- /changelog/2024-11-28-kv-explorer-available +excludeSearch: true +--- + +Since we've launched [Materia KV](https://www.clever-cloud.com/materia/materia-kv/), our serverless key-value database compatible with third-party protocols such as Redis® (and soon DynamoDB or GraphQL), customers were asking about a way to explore data directly from the Clever Cloud Console. This summer, we started to work on such a project, to provide a pleasant and easy-to-use interface, not only for Materia KV, but for any key-value add-on. After some months of internal alpha testing, it's available in Beta for all our Materia KV and Redis® add-ons. + +To use it, just open the `KV Explorer` tab of any compatible add-on, it's part of the Clever Cloud experience. This first public iteration supports hash, list, set and string data types, only strings for Materia KV add-ons as other types are yet to come. + +![KV Explorer](/images/kv-explorer.webp "The KV Explorer tool in the Console") + +You can filter keys by type, with a filter (`*value_to_search*` for example), value text fields are multi-lines, and you can copy/paste values directly from the interface. As usual, we've worked on keyboard shortcuts and accessibility. At the bottom, the KV Explorer Terminal allows you to type any command you want as you would do in a CLI client. It works the same, you type a command, press Enter, and you get the result (yes, also when you type `FLUSHDB` or `FLUSHALL`, so be careful). + +Of course, we'll continue to improve this tool, over the coming months, thanks to your feedback and suggestions. So feel free to share them and ask your questions in our [GitHub Community](https://github.com/CleverCloud/Community/discussions/categories/kv-explorer). + +- [Learn more about Materia KV](/developers/doc/addons/materia-kv/) +- [Learn more about Redis® on Clever Cloud](/developers/doc/addons/redis/) diff --git a/content/changelog/2024/12-04-otoroshi-available.md b/content/changelog/2024/12-04-otoroshi-available.md new file mode 100644 index 000000000..0a68536da --- /dev/null +++ b/content/changelog/2024/12-04-otoroshi-available.md @@ -0,0 +1,32 @@ +--- +title: "Otoroshi with LLM is available as an add-on on Clever Cloud" +date: 2024-12-04 +tags: + - addons + - Otoroshi +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Make the AI enterprise-grade +aliases: +- /changelog/2024-12-04-otoroshi-available +excludeSearch: true +--- + +After some weeks of testing, the Clever Cloud's Otoroshi with LLM add-on, is available in public beta. Thus, you can deploy the service, from [Console](https://console.clever-cloud.com/users/me/addons/new), [API](/developers/api) or [Clever Tools](https://github.com/CleverCloud/clever-tools), and use it in minutes. + +We developed this product with its creator and core developer: [Mathieu Ancelin](https://github.com/mathieuancelin) from [Cloud APIM](https://www.cloud-apim.com/). Otoroshi is an open source reverse proxy that allows you to create your own routes, manage authentication, authorization, and rate limiting. It helps you to expose services with enterprise needs in mind, as you can manage organisations, teams, service groups, with event management, data export, multiple secret stores support, etc. And it can be managed from a web interface or [as an API](https://maif.github.io/otoroshi/manual/api.html). + +On Clever Cloud, it comes batteries included, pre-configured with features such as [Coraza Web Appplication Firewall](https://maif.github.io/otoroshi/manual/how-to-s/instantiate-waf-coraza.html) or [LLM extension](https://cloud-apim.github.io/otoroshi-llm-extension/docs/overview). The latter allows you to manage AI services from many providers (Anthropic, Groq, Hugging Face, Mistral, OpenAI, OVHcloud), Ollama instances or any OpenAI API compatible endpoints. + +All this with a unique interface, adding token management, rate limit, context, validation, moderation, etc. Create your own agents and flows with an only URL, distributing tokens to your team or customers, for cURL requests or integrations to many services and tools… or your own applications hosted on Clever Cloud. + +It's based on a Java application and a Redis® database. Once deployed you'll get a management URL with credentials. Want to learn more? Feel free to let us know what you think and ask your questions in [our GitHub Community](https://github.com/CleverCloud/Community/discussions/categories/otoroshi). + +- [Learn more about Otoroshi](https://maif.github.io/otoroshi/manual/how-to-s/index.html) +- [Learn more about Otoroshi with LLM on Clever Cloud](/developers/doc/addons/otoroshi/) +- [Otoroshi LLM extension video tutorials](https://www.youtube.com/watch?v=M8PbydxPw4A&list=PLNHaf5rXAx3FWk7dn2fKGwQXxeLCPhZCh) diff --git a/content/changelog/2024/12-05-metabase-52.md b/content/changelog/2024/12-05-metabase-52.md new file mode 100644 index 000000000..da8d54172 --- /dev/null +++ b/content/changelog/2024/12-05-metabase-52.md @@ -0,0 +1,25 @@ +--- +title: "Metabase 52 is available" +date: 2024-12-05 +tags: + - addons + - metabase +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Faster, with more features +aliases: +- /changelog/2024-12-05-metabase-52 +excludeSearch: true +--- + +The `x.52` branch of Metabase is now available on Clever Cloud. To update, just set `CC_METABASE_VERSION` of the add-on's Java application to `0.52` for the community edition or `1.52` for the enterprise edition (EE). + +- [Learn more about Metabase on Clever Cloud](/developers/doc/addons/metabase/) +- [Learn more about Metabase 52](https://www.metabase.com/releases/metabase-52) + +{{< youtube id="h4xKT3MkLj0" >}} diff --git a/content/changelog/2024/12-12-python-3.13-update.md b/content/changelog/2024/12-12-python-3.13-update.md new file mode 100644 index 000000000..50cd6c46d --- /dev/null +++ b/content/changelog/2024/12-12-python-3.13-update.md @@ -0,0 +1,25 @@ +--- +title: "Python 3.13 is available" +date: 2024-12-12 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Newer Python and more tools +aliases: +- /changelog/2024-12-12-python-3.13-update +excludeSearch: true +--- + +We deployed an updated Python image with no impact for our users. + + * uv 0.5.7 + * Linux kernel 6.11.6 + * Redirection.io agent + * Python 3.13 support + * Python 3.7 withdrawal + +You can now use `3.13` as `CC_PYTHON_VERSION` environment variable. This version will also be used as default value. As announced [in October](../10-01-python-image-changes), Python 3.7 is not supported anymore. However, you can use `uv` to [install or use Python 3.7](https://docs.astral.sh/uv/guides/install-python/#installing-a-specific-version). \ No newline at end of file diff --git a/content/changelog/2024/12-18-clever-tools-3.11.md b/content/changelog/2024/12-18-clever-tools-3.11.md new file mode 100644 index 000000000..4bff4fd19 --- /dev/null +++ b/content/changelog/2024/12-18-clever-tools-3.11.md @@ -0,0 +1,36 @@ +--- +title: 'Clever Tools 3.11 is available with features flags and KV native support' +date: 2024-12-18 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Some tiny changes, before the huge ones +aliases: +- /changelog/2024-12-18-clever-tools-3.11 +excludeSearch: true +--- + +[Clever Tools 3.11](https://github.com/CleverCloud/clever-tools/releases/tag/3.11.0) is available. It includes some bug fixes and `clever profile open` commands. Most importantly, it introduces feature flags and KV native support. Thus, you can now enable some commands in alpha/beta status. First is `clever kv` which allows you to manage a Materia KV or Redis® database and send it commands without any dependencies: + +```bash +clever addon create kv myKV +clever features enable kv +clever kv myKV SET myKey myValue +clever kv myKV GET myKey +``` + +You can learn more about `clever kv` in [Clever Tools documentation](/developers/doc/cli/kv-stores/) or using `clever features info kv`. Next year we'll introduce more experimental commands through features flags. Next to come is `clever ng` to manage our [wireguard](https://www.wireguard.com/) based Network Groups. + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2024/12-24-terraform-0.5-Keycloak-Metabase.md b/content/changelog/2024/12-24-terraform-0.5-Keycloak-Metabase.md new file mode 100644 index 000000000..f33d0b48e --- /dev/null +++ b/content/changelog/2024/12-24-terraform-0.5-Keycloak-Metabase.md @@ -0,0 +1,23 @@ +--- +title: Deploy Keycloak and Metabase on Clever Cloud with Terraform (or OpenTofu) +date: 2024-12-24 +tags: + - addons + - terraform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +description: Your favorite services as code +aliases: +- /changelog/2024-12-24-terraform-0.5-keycloak-metabase.md +- /changelog/2024-12-24-terraform-0.5-keycloak-metabase +excludeSearch: true +--- + +You can now deploy [Keycloak](/developers/doc/addons/keycloak) and [Metabase](/developers/doc/addons/metabase) add-ons using our Terraform provider, compatible with OpenTofu. + +* Learn more about [our Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs) diff --git a/content/changelog/2025/01-06-sozu-1.0.6.md b/content/changelog/2025/01-06-sozu-1.0.6.md new file mode 100644 index 000000000..4826b405e --- /dev/null +++ b/content/changelog/2025/01-06-sozu-1.0.6.md @@ -0,0 +1,21 @@ +--- +title: Sōzu 1.0.6 is available and deployed, with new 4xx/5xx custom error pages +date: 2025-01-06 +tags: + - sozu +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: Next to come, HTTP/2! +aliases: +- /changelog/2025-01-06-sozu-1.0.6 +excludeSearch: true +--- + +[Sōzu](https://www.sozu.io) 1.0.6 is now available and deployed on all our shared and dedicated load balancers. It comes with a fix for a TLS bug we encountered with [Metabase](/developers/doc/addons/metabase) instances in some cases. We've also overhauled the custom pages for 4xx and 5xx errors. They now display a better designed and more detailed message. + +* Learn more about [Sōzu new releases](https://github.com/sozu-proxy/sozu/releases) {{< icon "github" >}} diff --git a/content/changelog/2025/01-14-keycloak-26.0.8.md b/content/changelog/2025/01-14-keycloak-26.0.8.md new file mode 100644 index 000000000..7288f0c17 --- /dev/null +++ b/content/changelog/2025/01-14-keycloak-26.0.8.md @@ -0,0 +1,20 @@ +--- +title: "Keycloak 26.0.8 is available (security update)" +date: 2025-01-14 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Thanks to Clever Cloud, it's easy to upgrade +excludeSearch: true +--- + +The release `26.0.8` of Keycloak is available on Clever Cloud. [It fixes](https://github.com/keycloak/keycloak/releases/26.0.8) some bugs, but also security issues: [CVE-2024-11734](https://nvd.nist.gov/vuln/detail/CVE-2024-11734) and [CVE-2024-11736](https://nvd.nist.gov/vuln/detail/CVE-2024-11736). To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.0.8` and rebuild it. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak) diff --git a/content/changelog/2025/01-15-node-22-lts-image-update.md b/content/changelog/2025/01-15-node-22-lts-image-update.md new file mode 100644 index 000000000..02d33d699 --- /dev/null +++ b/content/changelog/2025/01-15-node-22-lts-image-update.md @@ -0,0 +1,35 @@ +--- +title: "Node.js image update, with Mise package manager and Redirection.io easy setup" +date: 2025-01-15 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Ease your life on Clever Cloud +excludeSearch: true +--- + +We deployed an updated Node.js image with no impact for our users. It uses `22.13 LTS` release by default and Linux Kernel `6.12.9`. + +## Mise package manager + +It's the first image to include the [Mise package manager](https://mise.jdx.dev/), allowing you to install and manage many developer tools, environment variables, secrets, aliases, tasks, hooks through commands or a configuration file. It's compatible with [asdf ecosystem](https://mise.jdx.dev/dev-tools/comparison-to-asdf.html). + +* Learn more about [Mise](https://mise.jdx.dev/) + +## Redirection.io easy setup + +This image is also the first to include [Redirection.io](https://redirection.io/) easy setup. To configure the agent as a proxy, you just need to create an app listening on the port of your choice, get a project key from Redirection.io and set these environment variables: + +- `CC_ENABLE_REDIRECTIONIO=true` +- `CC_REDIRECTIONIO_PROJECT_KEY=""`: The Redirection.io project key +- `CC_REDIRECTIONIO_FORWARD_PORT=""`: The listening port of your application + +The Redirection.io agent will start as a service, listen to `8080` port and forward the traffic to your application. An optional `CC_REDIRECTIONIO_INSTANCE_NAME` is also available. It's the name of your application by default. + +These environment variables will progressively be available on all our compatible images. + +- [Clever Cloud Environment Variables Reference](/developers/doc/reference/reference-environment-variables/) diff --git a/content/changelog/2025/01-21-otoroshi-16.22.md b/content/changelog/2025/01-21-otoroshi-16.22.md new file mode 100644 index 000000000..ee09c7a37 --- /dev/null +++ b/content/changelog/2025/01-21-otoroshi-16.22.md @@ -0,0 +1,20 @@ +--- +title: "Otoroshi v16.22 is available" +date: 2025-01-21 +tags: + - addons + - Otoroshi +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Make the AI enterprise-grade +excludeSearch: true +--- + +The release `16.22.0` of Otoroshi is available on Clever Cloud for new add-ons. [It fixes](https://github.com/MAIF/otoroshi/releases/tag/v16.22.0) some bugs and adds some features such as a plugin to add very simple basic auth, without complex user management, plugins to provide information (metrics, health, etc.) as user endpoint. LLM Extension also contains multiple fixes. To upgrade, edit `CC_OTOROSHI_VERSION` to `v16.22.0`, `CC_OTOROSHI_APIM_VERSION` to `1737449369` in the Java application and rebuild it. + +- [Learn more about Otoroshi with LLM on Clever Cloud](/developers/doc/addons/otoroshi/) diff --git a/content/changelog/2025/01-22-elixir-1.18-image-update.md b/content/changelog/2025/01-22-elixir-1.18-image-update.md new file mode 100644 index 000000000..f2ad242d2 --- /dev/null +++ b/content/changelog/2025/01-22-elixir-1.18-image-update.md @@ -0,0 +1,15 @@ +--- +title: "Elixir 1.18 is available" +date: 2025-01-22 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Elixir 1.13 is now end-of-life +excludeSearch: true +--- + +We deployed an updated Elixir image with no impact for our users. It uses `1.18` release by default and Linux Kernel `6.12.9`. diff --git a/content/changelog/2025/01-31-keycloak-26.1.md b/content/changelog/2025/01-31-keycloak-26.1.md new file mode 100644 index 000000000..9fa75e60b --- /dev/null +++ b/content/changelog/2025/01-31-keycloak-26.1.md @@ -0,0 +1,22 @@ +--- +title: "Keycloak 26.1 is available" +date: 2025-01-31 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Lots of new features and improvements +excludeSearch: true +--- + +The release `26.1.0` of Keycloak is available on Clever Cloud. [It fixes](https://github.com/keycloak/keycloak/releases/26.1.0) some bugs, but also brings lots of new features and improvements, such as OpenTelemetry tracing, virtual thread pool support (embedded Infinispan and JGroups) when running on OpenJDK 21, a different way to discover other nodes of the same cluster (`jdbc-ping`) and a better OpenID for Verifiable Credential Issuance (OID4VCI) experimental support. + +To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.1.0` and rebuild it. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak) diff --git a/content/changelog/2025/02-04-otoroshi-available.md b/content/changelog/2025/02-04-otoroshi-available.md new file mode 100644 index 000000000..9c9b4bc4e --- /dev/null +++ b/content/changelog/2025/02-04-otoroshi-available.md @@ -0,0 +1,29 @@ +--- +title: "Otoroshi v16.23.2 is available, with Biscuit Studio and LLM updates" +date: 2025-02-04 +tags: + - addons + - Otoroshi +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Discover and use Biscuit, the easy way +excludeSearch: true +--- + +Otoroshi `v16.23.2` is now available on Clever Cloud for new add-ons. You can also update `CC_OTOROSHI_VERSION` to `v16.23.2`, `CC_OTOROSHI_APIM_VERSION` to `1738687356` in the Java application and rebuild it. + +This version includes the brand new Biscuit Studio, allowing you to use such tokens (we use in production for Materia KV and Pulsar) in your routes. It comes with key pair generator, Biscuit verifier, attenuation and roles management tools. The [client credentials plugin](https://cloud-apim.github.io/otoroshi-biscuit-studio/docs/plugins/clientcredentials) supports Biscuit to add a OAuth2 `client_credentials` flow to your routes. + +Web Application Firewall (WAF) plugin and interface are also enhanced in this release. Otoroshi can now use secrets management services declared with environment variables. This allows an easy integration of Clever KMS, our secrets management service available in private alpha for dedicated customers. + +LLM plugin includes a better models management, compatible with OVHcloud AI endpoints. Functions calling is enabled in Anthropic and Cohere, DeepSeek is available as a provider, [Citations from Anthropic](https://docs.anthropic.com/en/docs/build-with-claude/citations) are handled, such as reasoning models and tokens. + +- [Learn more about Biscuit](https://doc.biscuitsec.org/home) +- [Learn more about Otoroshi Biscuit Studio](https://cloud-apim.github.io/otoroshi-biscuit-studio/docs/overview) +- [Learn more about Otoroshi with LLM on Clever Cloud](/developers/doc/addons/otoroshi/) +- [Otoroshi LLM on Clever Cloud video streams](https://www.youtube.com/@Clevercloud-platform/search?query=Otoroshi) diff --git a/content/changelog/2025/02-05-mysql-update.md b/content/changelog/2025/02-05-mysql-update.md new file mode 100644 index 000000000..2b1888f53 --- /dev/null +++ b/content/changelog/2025/02-05-mysql-update.md @@ -0,0 +1,18 @@ +--- +title: MySQL update, with a new option +date: 2025-02-05 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Use skip-log-bin from Clever Tools +excludeSearch: true +--- + +We updated MySQL images for releases 8.4 (8.4.2-2) and 8.0 (8.0.39-30). A new option is available at database creation from Clever Tools: [skip-log-bin](https://dev.mysql.com/doc/refman/8.4/en/replication-options-binary-log.html#option_mysqld_log-bin). To use it, add `--option skip-log-bin` flag with the `clever create addon mysql-addon` command. + +* [Learn more about MySQL 8.4](https://www.percona.com/blog/mysql-8-4-first-peek/) +* [Learn more about MySQL on Clever Cloud](/developers/doc/addons/mysql/) diff --git a/content/changelog/2025/02-10-github-action-2.0.md b/content/changelog/2025/02-10-github-action-2.0.md new file mode 100644 index 000000000..0c8baeca3 --- /dev/null +++ b/content/changelog/2025/02-10-github-action-2.0.md @@ -0,0 +1,20 @@ +--- +title: "Version 2.0 of our GitHub Action for review applications is available" +date: 2025-02-10 +tags: + - github + - action +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Julia March + link: https://github.com/juliamrch + image: https://github.com/juliamrch.png?size=40 +description: Better, more secure practices for GitHub Action +excludeSearch: true +--- + +Update for [GitHub Action](https://github.com/marketplace/actions/clever-cloud-review-app-on-prs) to deploy applications from GitHub to Clever Cloud. Version 2.0 brings an improved interface for the comment section on deployments, as well as updated security practices in names and docs. + +- [Learn more about how to deploy from GitHub to Clever Cloud](/developers/doc/ci-cd/github/) \ No newline at end of file diff --git a/content/changelog/2025/02-10-metabase-53.md b/content/changelog/2025/02-10-metabase-53.md new file mode 100644 index 000000000..94bcb69fb --- /dev/null +++ b/content/changelog/2025/02-10-metabase-53.md @@ -0,0 +1,23 @@ +--- +title: "Metabase 53 is available" +date: 2025-02-10 +tags: + - addons + - metabase +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Faster, with more features +excludeSearch: true +--- + +The `x.53` branch of Metabase is now available on Clever Cloud. To update, just set `CC_METABASE_VERSION` of the add-on's Java application to `0.53` for the community edition or `1.53` for the enterprise edition (EE). + +- [Learn more about Metabase 53](https://www.metabase.com/releases/metabase-53) +- [Learn more about Metabase on Clever Cloud](/developers/doc/addons/metabase/) + +{{< youtube id="SMKsq6M__YM" >}} diff --git a/content/changelog/2025/02-11-otoroshi-16.23.md b/content/changelog/2025/02-11-otoroshi-16.23.md new file mode 100644 index 000000000..33db56162 --- /dev/null +++ b/content/changelog/2025/02-11-otoroshi-16.23.md @@ -0,0 +1,22 @@ +--- +title: "Otoroshi with LLM supports DeepSeek and reasoning" +date: 2025-02-11 +tags: + - addons + - Otoroshi +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: And a better support of OVHcloud AI endpoints +aliases: +- /changelog/2024-12-04-otoroshi-available +excludeSearch: true +--- + +The release `16.23.2` of Otoroshi is available for new add-ons. [It fixes](https://github.com/MAIF/otoroshi/releases/tag/v16.23.2) some bugs and adds some features but the better comes from LLM Extension which comes with a better OVHcloud AI endpoints integration, DeepSeek and reasoning models support. To upgrade, edit `CC_OTOROSHI_VERSION` to `v16.23.2`, `CC_OTOROSHI_APIM_VERSION` to `1739212580` in the Java application and rebuild it. + +- [Learn more about Otoroshi with LLM on Clever Cloud](/developers/doc/addons/otoroshi/) diff --git a/content/changelog/2025/02-12-matomo-5.2.2.md b/content/changelog/2025/02-12-matomo-5.2.2.md new file mode 100644 index 000000000..845198f4d --- /dev/null +++ b/content/changelog/2025/02-12-matomo-5.2.2.md @@ -0,0 +1,22 @@ +--- +title: Matomo v5.2.2 is available +date: 2025-02-12 +tags: + - addons + - matomo +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: With updated PHP version and soon new features +excludeSearch: true +--- + +Our [Matomo](https://matomo.org/) add-on has been updated to version `v5.2.2` which is now used by default. You can deploy this latest release from our [Console](https://console.clever-cloud.com) or [Clever Tools](https://github.com/CleverCloud/clever-tools). Existing customers add-ons are already up-to-date. + +- [Learn more about Matomo 5.2](https://matomo.org/changelog/matomo-5-2-0/) +- [Learn more about Matomo 5.2.2](https://matomo.org/changelog/matomo-5-2-2/) +- [Learn more about Matomo on Clever Cloud](/developers/doc/addons/matomo/) diff --git a/content/changelog/2025/02-12-php-8.4-update.md b/content/changelog/2025/02-12-php-8.4-update.md new file mode 100644 index 000000000..55e30eafb --- /dev/null +++ b/content/changelog/2025/02-12-php-8.4-update.md @@ -0,0 +1,27 @@ +--- +title: "PHP 8.4 is available, Symfony CLI included" +date: 2025-02-12 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: FrankenPHP is next to come +excludeSearch: true +--- + +We deployed an updated PHP image with no impact for our users. + + * PHP 8.4.3 + * Composer 2.8.5 + * Symfony CLI 5.10.7 + * Linux kernel 6.12.9 + +You can now use `8.4` as `CC_PHP_VERSION` environment variable, `8.3` is still the default for now. + +Only some extensions support PHP 8.4 for now: apcu, amqp, blackfire, event, elastic-apm, gnupg, grpc, imap, mailparse, maxminddb, memcache, memcached, mongodb, newrelic, oauth, pdflib, protobuf pspell, rdkafka, redis, ssh2, solr, tideways, uploadprogress, zip. We'll add support for more extensions as they are released. + +* [PHP migration guide from 8.3 to 8.4](https://www.php.net/migration84) +* [Learn more about PHP on Clever Cloud](/developers/doc/applications/php/) diff --git a/content/changelog/2025/02-17-rust-sdk-0.12.md b/content/changelog/2025/02-17-rust-sdk-0.12.md new file mode 100644 index 000000000..c71e29b4b --- /dev/null +++ b/content/changelog/2025/02-17-rust-sdk-0.12.md @@ -0,0 +1,17 @@ +--- +title: Rust SDK v0.12 is available +date: 2025-02-17 +tags: + - sozu +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: Maintenance release +excludeSearch: true +--- + +[Rust SDK v0.12](https://github.com/CleverCloud/clevercloud-sdk-rust/releases/tag/v0.12.0) is available, with updated PostgreSQL versions, fixes for Clever Functions, updated dependencies and Rust version. diff --git a/content/changelog/2025/02-18-kunernetes-operator-0.6.0.md b/content/changelog/2025/02-18-kunernetes-operator-0.6.0.md new file mode 100644 index 000000000..c2ecd3b24 --- /dev/null +++ b/content/changelog/2025/02-18-kunernetes-operator-0.6.0.md @@ -0,0 +1,21 @@ +--- +title: 'Clever Kubernetes Operator v0.6.0 with Materia KV and API Tokens support' +date: 2025-02-18 +tags: + - kubernetes + - operator +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: Preparing new features +excludeSearch: true +--- + +[Clever Kubernetes Operator v0.6.0](https://github.com/CleverCloud/clever-kubernetes-operator/releases/tag/v0.6.0) is available. It now uses [clevercloud-sdk-rust v0.12.0](https://github.com/CleverCloud/clevercloud-sdk-rust/releases/tag/v0.12.0) and [oauth10a v2.0.0](https://github.com/CleverCloud/oauth10a-rust/releases/tag/v2.0.0) to simplify authentication through API Tokens or Basic Auth. This release also adds Materia KV add-ons support as custom resource. + +- [Learn more about Clever Kubernetes Operator](/developers/guides/kubernetes-operator) +- [Learn more about Materia KV](/developers/doc/addons/materia-kv) diff --git a/content/changelog/2025/02-19-terraform-0.6-redis.md b/content/changelog/2025/02-19-terraform-0.6-redis.md new file mode 100644 index 000000000..fd30cf281 --- /dev/null +++ b/content/changelog/2025/02-19-terraform-0.6-redis.md @@ -0,0 +1,20 @@ +--- +title: Deploy Redis® on Clever Cloud with Terraform (or OpenTofu), update your plan +description: No more destroy/recreate +date: 2025-02-19 +tags: + - addons + - terraform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +excludeSearch: true +--- + +You can now deploy [Redis®](/developers/doc/addons/redis) add-ons using our Terraform provider, compatible with OpenTofu. The [0.6.0 release](https://github.com/CleverCloud/terraform-provider-clevercloud/releases/tag/v0.6.0) of the Clever Cloud Terraform provider also introduce the resource update. You can now apply a new plan without destroying and recreating the resource starting with PHP applications. + +* Learn more about [our Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs) diff --git a/content/changelog/2025/02-20-logs-interface-old-decomission.md b/content/changelog/2025/02-20-logs-interface-old-decomission.md new file mode 100644 index 000000000..f0737889d --- /dev/null +++ b/content/changelog/2025/02-20-logs-interface-old-decomission.md @@ -0,0 +1,22 @@ +--- +title: "Console: old logs stack decommission" +date: 2025-02-20 +tags: + - console + - logs +authors: + - name: Pierre De Soyres + link: https://github.com/pdesoyres-cc + image: https://github.com/pdesoyres-cc.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: And soon add-ons, access logs… and indexing +excludeSearch: true +--- + +[Last year](/developers/changelog/2024/07-17-new-logs-default/) we introduced a new logs interface in [the Console](https://console.clever-cloud.com) and enhanced it since then. After some months [using it by default](/developers/changelog/2024/07-17-new-logs-default/), we start decommissioning our old logs stack. Thus, you can't switch to the previous interface anymore for applications. + +Next, we'll use the new stack for add-ons, access logs and continue improving the interface. A big step will be to introduce logs indexing, allowing you to better search through your logs and load the latest. + +Feel free to ask for features and improvements in our [GitHub Community space](https://github.com/CleverCloud/Community/discussions/categories/new-logs-interface). \ No newline at end of file diff --git a/content/changelog/2025/02-21-keycloak-GA.md b/content/changelog/2025/02-21-keycloak-GA.md new file mode 100644 index 000000000..7af858ca0 --- /dev/null +++ b/content/changelog/2025/02-21-keycloak-GA.md @@ -0,0 +1,20 @@ +--- +title: "Keycloak in General Availability" +date: 2025-02-21 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: With the new Operator API +excludeSearch: true +--- + +Keycloak is now in General Availability (GA). Deployed version is `26.1.2` and you now have access [to the operator API](/developers/api/v4/#operators). To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.1.2` and rebuild it. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak/) diff --git a/content/changelog/2025/02-24-metabase-GA.md b/content/changelog/2025/02-24-metabase-GA.md new file mode 100644 index 000000000..e851bcbda --- /dev/null +++ b/content/changelog/2025/02-24-metabase-GA.md @@ -0,0 +1,20 @@ +--- +title: "Metabase in General Availability" +date: 2025-02-24 +tags: + - addons + - metabase +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: With the new Operator API +excludeSearch: true +--- + +Metabase is now in General Availability (GA). Deployed version is `x.53.4` and you now have access [to the operator API](/developers/api/v4/#operators). To update, just set `CC_METABASE_VERSION` of the add-on's Java application to `0.53` for the community edition or `1.53` for the enterprise edition (EE) and rebuild it. + +- [Learn more about Metabase on Clever Cloud](/developers/doc/addons/metabase/) diff --git a/content/changelog/2025/02-26-js-client-9.2.0.md b/content/changelog/2025/02-26-js-client-9.2.0.md new file mode 100644 index 000000000..9338473ac --- /dev/null +++ b/content/changelog/2025/02-26-js-client-9.2.0.md @@ -0,0 +1,18 @@ +--- +title: 'JS Client 9.2 is available' +date: 2025-02-26 +tags: + - client + - javascript +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Preparing new features +excludeSearch: true +--- + +[Clever Cloud JS client 9.2.0](https://github.com/CleverCloud/clever-client.js/blob/master/CHANGELOG.md#920-2025-02-26) is available with some enhancements and multiple new features for `billing`, `grafana`, `materia`, etc. diff --git a/content/changelog/2025/02-28-otoroshi-GA-16.24.md b/content/changelog/2025/02-28-otoroshi-GA-16.24.md new file mode 100644 index 000000000..130adaf5e --- /dev/null +++ b/content/changelog/2025/02-28-otoroshi-GA-16.24.md @@ -0,0 +1,20 @@ +--- +title: "Otoroshi in General Availability" +date: 2025-02-28 +tags: + - addons + - Otoroshi +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: With the new Operator API +excludeSearch: true +--- + +Otoroshi is now in General Availability (GA), with access [to the operator API](/developers/api/v4/#operators). Deployed version is `v16.24.0_1740754279`. The LLM extension includes new models filtering tools and pre-defined context per endpoint. To update, just set `CC_OTOROSHI_VERSION` of the add-on's Java application to `v16.24.0_1740754279` and rebuild it. You can also delete `CC_OTOROSHI_APIM_VERSION`, `CC_OTOROSHI_SECRET` variables from the Java application, they are not used anymore. + +- [Learn more about Otoroshi with LLM on Clever Cloud](/developers/doc/addons/otoroshi/) diff --git a/content/changelog/2025/03-03-images-update.md b/content/changelog/2025/03-03-images-update.md new file mode 100644 index 000000000..f09072178 --- /dev/null +++ b/content/changelog/2025/03-03-images-update.md @@ -0,0 +1,37 @@ +--- +title: "Multiple images update" +date: 2025-03-03 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Releases are getting bigger +excludeSearch: true +--- + +We deployed and updated all our images, except Docker, Go, Java, Node and Ruby, with no impact for our users. + +* **Common:** + * Linux kernel 6.13.5 +* **.Net:** + * Update to 8.0.108 +* **Elixir:** + * Update to 1.18.2 + * Erlang 27.2.2 +* **Haskell:** + * Stack 2.15.7 +* **PHP:** + * Update to 8.4.4 + * Composer 2.8.6 + * `CC_APACHE_HEADERS_SIZE` [environment variable](/developers/doc/reference/reference-environment-variables/) +* **Python:** + * Update to 3.13.2 + * pip 24.3.1 + * uv 0.6.3 +* **Rust:** + * Update to 1.85.0 + +All these images include [Mise and Redirection.io easy setup](/developers/changelog/2025/01-15-node-22-lts-image-update/). diff --git a/content/changelog/2025/03-03-keycloak-26.1.3.md b/content/changelog/2025/03-03-keycloak-26.1.3.md new file mode 100644 index 000000000..95d277ed6 --- /dev/null +++ b/content/changelog/2025/03-03-keycloak-26.1.3.md @@ -0,0 +1,20 @@ +--- +title: "Keycloak 26.1.3 is available" +date: 2025-03-03 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: With better realm import procedures +excludeSearch: true +--- + +The release `26.1.3` of Keycloak is available on Clever Cloud. [It fixes](https://github.com/keycloak/keycloak/releases/26.1.3) some bugs, and we enhanced [realm import procedures](/developers/doc/addons/keycloak/#importing-realms-data). To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.1.3` and rebuild it. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak) diff --git a/content/changelog/2025/03-06-clever-tools-winget.md b/content/changelog/2025/03-06-clever-tools-winget.md new file mode 100644 index 000000000..5bad324e8 --- /dev/null +++ b/content/changelog/2025/03-06-clever-tools-winget.md @@ -0,0 +1,34 @@ +--- +title: 'Install Clever Tools on Windows through WinGet' +date: 2025-03-06 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: The Clever way +excludeSearch: true +--- + +You can [install our CLI](/developers/doc/cli/install), Clever Tools, on any system through `npm`, binaries or many package managers. On Windows, we relied on Chocolatey with a dedicated Nexus instance for years, but we now also support the official Windows package manager, [WinGet](https://github.com/microsoft/winget-cli). + +To install the latest version of Clever Tools, you can now use the following command: + +```bash +winget install CleverTools +``` + +And upgrade it with: + +```bash +winget upgrade CleverTools +``` + +We'll add WinGet support to our automatic release process and start deprecating Chocolatey, as it began more difficult to install it through our Nexus instance over the recent releases. You can also continue to download a `.zip` archive [and extract the binary](/developers/doc/cli/install/#binary-zip). + +- [Learn more about Clever Tools](https://github.com/CleverCloud/clever-tools) {{< icon "github" >}} diff --git a/content/changelog/2025/03-07-clever-tools-3.12.md b/content/changelog/2025/03-07-clever-tools-3.12.md new file mode 100644 index 000000000..6ff5f7535 --- /dev/null +++ b/content/changelog/2025/03-07-clever-tools-3.12.md @@ -0,0 +1,105 @@ +--- +title: 'Clever Tools 3.12, with API Tokens and Network Groups' +date: 2025-03-07 +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Two new big features to play with +excludeSearch: true +--- + +[Clever Tools 3.12](https://github.com/CleverCloud/clever-tools/releases/tag/3.12.0) is available. It includes some bug fixes and two new experimental features, available through feature flags. + +## API Tokens +First is `clever tokens`, which allows you to create and manage API tokens, and use them to request the Clever Cloud API: + +```bash +clever features enable tokens + +clever tokens create "CI job Foobar" +clever tokens create "Quick local test" --expiration 1h +``` +You can also list or revoke tokens: + +```bash +clever tokens -F json +clever tokens revoke api_tokens_xxx +``` + +Once created, API tokens must be used through the bridge URL: + +```bash +curl https://api-bridge.clever-cloud.com/v2/self -H "Authorization: Bearer [API_TOKEN]" +``` +- [Clever Cloud API Documentation](/developers/api) +- [Give your feedback about API Tokens](https://github.com/CleverCloud/Community/discussions/categories/api-tokens) + +## Network Groups + +The second feature is `clever ng`, to manage the long awaited Network Groups. Use them to link resources over a [Wireguard-based](https://www.wireguard.com/) private and secure network. It can be applications, add-ons or external systems (a local machine, a third-party server, etc.). + +```bash +clever features enable ng + +clever ng create myNg +clever ng link app_id myNg +clever ng unlink app_id myNg + +clever ng create anotherNg --link app_id1,app_id2 +clever ng get anotherNg +clever ng get app_id1 + +clever ng +clever ng search Ng + +clever ng delete myNg +clever ng delete anotherNg +``` + +Once linked to a Network Groups, resources can communicate with each other directly, on any port. Each resources is identified as a "Member" with a dedicated domain name. Each instance of a resource is a "Peer" with a unique IP address inside the Network Group. + +- [Network Group demo application](https://github.com/CleverCloud/network-groups-example) + +We've natively integrated Network Groups to our Keycloak and Otoroshi operators. Thus, you can (de)activate a high-availability Keycloak service with two instance synced over a Network Group. It just needs one API call (and soon one Clever Tools command): + +```bash +curl -XPOST -H "Authorization: Bearer [API_TOKEN]" \ + https://api-bridge.clever-cloud.com/v4/addon-providers/addon-keycloak/addons/keycloak_id/networkgroup + +curl -XDELETE -H "Authorization: Bearer [API_TOKEN]" \ + https://api-bridge.clever-cloud.com/v4/addon-providers/addon-keycloak/addons/keycloak_id/networkgroup +``` + +{{< callout type="info" >}} +If you activate multi-instances Keycloak feature, you'll be billed for two Java instances. Network Groups are free of charge. +{{< /callout >}} + +With Otoroshi, activating a Network Group links the underlying Java application to it. Thus, you can easily add other applications to the same Network Group and use Otoroshi as a gateway to protect the access to your applications through API keys, Biscuits, WAF, etc. + +```bash +curl -XPOST -H "Authorization: Bearer [API_TOKEN]" \ + https://api-bridge.clever-cloud.com/v4/addon-providers/addon-otoroshi/addons/otoroshi_id/networkgroup + +curl -XDELETE -H "Authorization: Bearer [API_TOKEN]" \ + https://api-bridge.clever-cloud.com/v4/addon-providers/addon-otoroshi/addons/otoroshi_id/networkgroup +``` + +As this beta feature evolves, we'll add demos, documentations and videos to help you to fully take advantage of Network Groups. + +- [Learn more about Network Groups](/developers/doc/develop/network-groups/) +- [Give your feedback about Network Groups](https://github.com/CleverCloud/Community/discussions/categories/network-groups) + +## How to upgrade +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2025/03-07-rust-sdk-0.13.md b/content/changelog/2025/03-07-rust-sdk-0.13.md new file mode 100644 index 000000000..f9af8a969 --- /dev/null +++ b/content/changelog/2025/03-07-rust-sdk-0.13.md @@ -0,0 +1,18 @@ +--- +title: Rust SDK v0.13 is available +date: 2025-03-07 +tags: + - client + - rust +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: New Auth solutions for your Rust applications +excludeSearch: true +--- + +[Rust SDK v0.13](https://github.com/CleverCloud/clevercloud-sdk-rust/releases/tag/v0.13.1) is available, uses Rust 1.85 and can now use [API tokens](/developers/api/howto/) or get credentials from [Clever Tools](https://github.com/CleverCloud/clever-tools/) configuration file if present in the system. diff --git a/content/changelog/2025/03-12-images-update.md b/content/changelog/2025/03-12-images-update.md new file mode 100644 index 000000000..de3169d5f --- /dev/null +++ b/content/changelog/2025/03-12-images-update.md @@ -0,0 +1,30 @@ +--- +title: "Images update: Go 1.24 and Node.js 22.14" +description: Update cycle getting faster +date: 2025-03-12 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +excludeSearch: true +--- + +We deployed and updated all our images, except Java and Ruby, with no impact for our users. + +* **Common:** + * Linux kernel 6.13.6 +* **Docker:** + * Update to 28.0.1 +* **Elixir:** + * Update to 1.18.3 + * Erlang 27.3 +* **Go:** + * Update to 1.24.1 +* **Node.js:** + * Update to 22.14.0 +* **Python:** + * pip 25.0.1 + * uv 0.6.4 diff --git a/content/changelog/2025/03-12-materia-kv-json.md b/content/changelog/2025/03-12-materia-kv-json.md new file mode 100644 index 000000000..753e6f31d --- /dev/null +++ b/content/changelog/2025/03-12-materia-kv-json.md @@ -0,0 +1,23 @@ +--- +title: Materia KV with JSON commands (GET/SET/DEL) +description: Added JSON functions to Materia KV +date: 2025-03-12 +tags: + - Materia KV + - JSON +authors: + - name: Enora Broudic + link: https://github.com/RaspY737 + image: https://github.com/RaspY737.png?size=40 + - name: Pierre Zemb + link: https://github.com/pierrez + image: https://github.com/pierrez.png?size=40 +excludeSearch: true +--- + +Materia KV now supports some `JSON` commands : +- `JSON.SET`: sets JSON value at path in key +- `JSON.GET`: gets JSON value at path from key +- `JSON.DEL`: deletes JSON value at path from key + +These commands are available for new and already deployed add-ons, with no additional configuration. For detailed examples and usage, see [Materia KV documentation](/developers/doc/addons/materia-kv/#json-commands). If you have any questions or feedback, let's discuss it on our [GitHub Community](https://github.com/CleverCloud/Community/discussions/categories/materia). diff --git a/content/changelog/2025/03-18-images-update-ruby-unified.md b/content/changelog/2025/03-18-images-update-ruby-unified.md new file mode 100644 index 000000000..a562da904 --- /dev/null +++ b/content/changelog/2025/03-18-images-update-ruby-unified.md @@ -0,0 +1,30 @@ +--- +title: "Images update: PHP 8.4.5, Ruby in unified image stack" +date: 2025-03-18 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: New week, new release! +excludeSearch: true +--- + +We deployed and updated all our images, except Java, with no impact for our users. It now includes Ruby as part as our new unified image stack. + +* **Common:** + * Linux kernel 6.13.7 +* **PHP:** + * Update to 8.4.5 + * Apache 2.4.63 +* **Python:** + * uv 0.6.6 + * nginx 1.26.3 +* **Ruby:** + * Update to 3.4.2 + * Bundler 2.6.5 + * nginx 1.26.3 + +Note that Ruby 3.4 is the default only in Ruby applications. Ruby 3.2 is still default on other runtimes, use [rbenv](https://github.com/rbenv/rbenv) and `RBENV_VERSION` to switch to Ruby 3.4 for now. diff --git a/content/changelog/2025/03-18-mysql-update.md b/content/changelog/2025/03-18-mysql-update.md new file mode 100644 index 000000000..23b61c733 --- /dev/null +++ b/content/changelog/2025/03-18-mysql-update.md @@ -0,0 +1,19 @@ +--- +title: MySQL 8.4.3-3 and 8.0.41-32 are available +date: 2025-03-18 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Get new features and improvements +excludeSearch: true +--- + +We updated MySQL images 8.0 and 8.4 from Percona Server. They're now available for add-ons creation and migration. + +* [Learn more about MySQL on Clever Cloud](/developers/doc/addons/mysql/) +* [Learn more about MySQL 8.0.41-32](https://docs.percona.com/percona-server/8.0/release-notes/8.0.41-32.html) +* [Learn more about MySQL 8.4.3-3](https://docs.percona.com/percona-server/8.4/release-notes/8.4.3-3.html) diff --git a/content/changelog/2025/03-18-postgresql-16-17.md b/content/changelog/2025/03-18-postgresql-16-17.md new file mode 100644 index 000000000..5f4a0e152 --- /dev/null +++ b/content/changelog/2025/03-18-postgresql-16-17.md @@ -0,0 +1,20 @@ +--- +title: PostgreSQL 16 and 17 are available +date: 2025-03-18 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: It's time to prepare for PostgreSQL 18! +excludeSearch: true +--- + +PostgreSQL 16.8 and 17.4 are now available for add-on creation and migration. Some extensions were removed of these releases: `plcoffee`, `plls`, `plv8` starting PostgreSQL 16 and `pgadmin` which is not available starting PostgreSQL 17. They won't be available after a migration. If you used any of them, the process could fail and your database will be kept in its current version. + +We also updated PostgreSQL 15 to release 15.12, PostgreSQL 14 to release 14.17, PostgreSQL 13 to release 13.20. Migrate your database to the desired major version to get the latest release. + +* [Learn more about PostgreSQL on Clever Cloud](/developers/doc/addons/postgresql/) +* [PostgreSQL release notes](https://www.postgresql.org/docs/release/) diff --git a/content/changelog/2025/03-19-paris-hds.md b/content/changelog/2025/03-19-paris-hds.md new file mode 100644 index 000000000..4eee99715 --- /dev/null +++ b/content/changelog/2025/03-19-paris-hds.md @@ -0,0 +1,18 @@ +--- +title: Paris HDS zone is available +date: 2025-03-19 +tags: + - hds + - zone +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Host your health data in Paris with HDS certification +excludeSearch: true +--- + +Clever Cloud is HDS-certified for [all six activities](https://www.clever-cloud.com/fr/hebergement-donnees-de-sante/) and you can now deploy on `parhds` zone from the [API](/developers/api/), [Clever Tools](/developers/doc/cli/) or the [Console](https://console.clever-cloud.com). To benefit from certified hosting for health data, you need to deploy in an HDS zone and to sign up to a specific contract. This begins with [an initial discussion with our team](https://www.clever-cloud.com/fr/hebergement-donnees-de-sante/contact-hds/). + +* [Learn more about Clever Cloud HDS certification](https://www.clever-cloud.com/fr/hebergement-donnees-de-sante/) +* [Learn more about HDS hosting on Clever Cloud](https://www.clever-cloud.com/fr/blog/entreprise/2025/03/19/cloud-hds-avec-clever-cloud/) diff --git a/content/changelog/2025/03-19-terraform-0.7-resources-update.md b/content/changelog/2025/03-19-terraform-0.7-resources-update.md new file mode 100644 index 000000000..05a9e63fe --- /dev/null +++ b/content/changelog/2025/03-19-terraform-0.7-resources-update.md @@ -0,0 +1,20 @@ +--- +title: Terraform provider 0.7.0 is available with more resources you can update +description: Yet more to come +date: 2025-03-19 +tags: + - addons + - terraform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +excludeSearch: true +--- + +With [0.6.0 release](/developers/changelog/2025/02-19-terraform-0.6-redis/) of the Clever Cloud Terraform provider (compatible with OpenTofu), we introduced the support of resource update. Starting with [0.7.0](https://github.com/CleverCloud/terraform-provider-clevercloud/releases/tag/v0.7.0) you can now apply a new plan without destroying and recreating the resource on Docker, Java, Python, Scala and Static applications. + +* Learn more about [our Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs) diff --git a/content/changelog/2025/03-21-matomo-5.3.1.md b/content/changelog/2025/03-21-matomo-5.3.1.md new file mode 100644 index 000000000..7c9a15df7 --- /dev/null +++ b/content/changelog/2025/03-21-matomo-5.3.1.md @@ -0,0 +1,22 @@ +--- +title: Matomo v5.3.1 is available +date: 2025-03-21 +tags: + - addons + - matomo +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Upgraded with no effort needed +excludeSearch: true +--- + +Our [Matomo](https://matomo.org/) add-on has been updated to version `v5.3.1` which is now used by default. You can deploy this latest release from our [Console](https://console.clever-cloud.com) or [Clever Tools](/developers/doc/cli/). Existing customers add-ons are already up-to-date. + +- [Learn more about Matomo 5.3](https://matomo.org/changelog/matomo-5-3-0/) +- [Learn more about Matomo 5.3.1](https://matomo.org/changelog/matomo-5-3-1/) +- [Learn more about Matomo on Clever Cloud](/developers/doc/addons/matomo/) diff --git a/content/changelog/2025/03-21-php-version-management-update.md b/content/changelog/2025/03-21-php-version-management-update.md new file mode 100644 index 000000000..3301fe649 --- /dev/null +++ b/content/changelog/2025/03-21-php-version-management-update.md @@ -0,0 +1,24 @@ +--- +title: "Some changes in PHP version management" +date: 2025-03-21 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: And now, let's prepare for PHP 8.5 +excludeSearch: true +--- + +Starting today, PHP applications on Clever Cloud are created with `CC_PHP_VERSION=8` environment variable and using default minor PHP version for branch `8`. Nothing changes on already deployed applications. + +Starting april 30th, the default minor PHP version for branch `8` will move from `8.3` to `8.4`, released last November. If you need to keep using PHP 8.3, just set `CC_PHP_VERSION=8.3` in your environment variables from the Console or with Clever Tools: + +``` +clever env set CC_PHP_VERSION 8.3 --app +``` + +* [Learn more about PHP on Clever Cloud](/developers/doc/applications/php/) +* [Learn more about environment variables on Clever Cloud](/developers/doc/reference/reference-environment-variables/) diff --git a/content/changelog/2025/03-24-otoroshi-update-biscuit-studio-0.10.md b/content/changelog/2025/03-24-otoroshi-update-biscuit-studio-0.10.md new file mode 100644 index 000000000..d7cc29d31 --- /dev/null +++ b/content/changelog/2025/03-24-otoroshi-update-biscuit-studio-0.10.md @@ -0,0 +1,24 @@ +--- +title: "Otoroshi update, with new LLM features and Biscuit Studio 0.10" +date: 2025-03-24 +tags: + - addons + - otoroshi +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Biscuit everything! +excludeSearch: true +--- + +Otoroshi `v16.24.0_1742549915` is available. It includes LLM extension [v0.0.42](https://github.com/cloud-apim/otoroshi-llm-extension/releases/tag/0.0.42) with multiple bug fixes, model management improvements, more guardrails features and per-provider context introduced in [v0.0.39](https://github.com/cloud-apim/otoroshi-llm-extension/releases/tag/0.0.39). + +Biscuit Studio [0.0.10](https://github.com/cloud-apim/otoroshi-biscuit-studio/releases/tag/0.0.10) is also included with multiple bug fixes, but also public key pair exposition, Biscuit verifiers chaining, Biscuit token and connected user extraction introduced in [v0.0.8](https://github.com/cloud-apim/otoroshi-biscuit-studio/releases/tag/0.0.8). + +To update just set `CC_OTOROSHI_VERSION` of the add-on's Java application to `v16.24.0_1742549915` and rebuild it. You can also delete `CC_OTOROSHI_APIM_VERSION`, `CC_OTOROSHI_SECRET` variables from the Java application, they are not used anymore. + +- [Learn more about Otoroshi with LLM on Clever Cloud](/developers/doc/addons/otoroshi/) diff --git a/content/changelog/2025/03-24-postgresql-11-12-eol.md b/content/changelog/2025/03-24-postgresql-11-12-eol.md new file mode 100644 index 000000000..93fdb0085 --- /dev/null +++ b/content/changelog/2025/03-24-postgresql-11-12-eol.md @@ -0,0 +1,22 @@ +--- +title: Update on PostgreSQL 11 and 12 support on Clever Cloud +date: 2025-03-24 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: It's time to upgrade! +excludeSearch: true +--- + +As [PostgreSQL 16 and 17 are now available](/developers/changelog/2025/03-18-postgresql-16-17/) on Clever Cloud, we'll start to limit access to end-of-life releases: PostgreSQL 11 and 12. **Starting April 30th**, you won't be able to create new PostgreSQL 11 or 12 add-ons. Note that: +* PG11/12 databases deployed before April 30th will still be available after this deadline +* Customers will still be able to manage their existing PG11/12 databases after this deadline + +But **we recommend you to migrate to an actively supported version**. You can do it easily using our included migration tool in your add-on parameters. In the coming weeks, you'll start to see warnings in [the Console](https://console.clever-cloud.com) if you are still using PostgreSQL 12 or a lower version. + +* [PostgreSQL versioning policy](https://www.postgresql.org/support/versioning/) +* [Learn more about PostgreSQL on Clever Cloud](/developers/doc/addons/postgresql/) diff --git a/content/changelog/2025/03-25-js-client-10.0.0.md b/content/changelog/2025/03-25-js-client-10.0.0.md new file mode 100644 index 000000000..222f71dde --- /dev/null +++ b/content/changelog/2025/03-25-js-client-10.0.0.md @@ -0,0 +1,18 @@ +--- +title: 'JS Client 10.0.0 is available' +date: 2025-03-25 +tags: + - client + - javascript +authors: + - name: Pierre De Soyres + link: https://github.com/pdesoyres-cc + image: https://github.com/pdesoyres-cc.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Preparing new features +excludeSearch: true +--- + +[Clever Cloud JS client 10.0.0](https://github.com/CleverCloud/clever-client.js/blob/master/CHANGELOG.md#1000-2025-03-25) is available. In this release, we cleaned up lots of legacy code and no longer generate CommonJS client as we moved to ECMAScript modules (ESM). `eslint`, `prettier` and `typecheck` are now included and used as part of our quality code check and release process. `ResourceLogStream` class is available to manage for new SSE add-ons logs. diff --git a/content/changelog/2025/03-25-python-3.8-eol.md b/content/changelog/2025/03-25-python-3.8-eol.md new file mode 100644 index 000000000..fa800afc6 --- /dev/null +++ b/content/changelog/2025/03-25-python-3.8-eol.md @@ -0,0 +1,22 @@ +--- +title: "Python 3.8 end of life" +description: Python 3.9 is next, prepare to Python 3.14 update +date: 2025-03-25 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +excludeSearch: true +--- + +[As announced last year](/developers/changelog/2024/10-01-python-image-changes/), our new update process is getting closer to [the official Python release cycle](https://devguide.python.org/versions/#python-release-cycle), which is 5 years of support. Starting April 30th, we'll remove Python 3.8, released in 2019 and end-of-life since last October, from our images. + +To upgrade to a more recent version of Python, you only need to update `CC_PYTHON_VERSION` of your applications and rebuild them. Use `3` as value to always get the latest release available on Clever Cloud. + +If you need to keep Python 3.8 for legacy reasons, you can [use uv](https://docs.astral.sh/uv/guides/install-python/#installing-a-specific-version) or [Mise](https://mise.jdx.dev/lang/python.html) which are available in all our recently updated images. + +* [Learn more about Python on Clever Cloud](/developers/doc/applications/python/) +* [Learn more about environment variables on Clever Cloud](/developers/doc/reference/reference-environment-variables/) diff --git a/content/changelog/2025/03-27-postgresql-default.md b/content/changelog/2025/03-27-postgresql-default.md new file mode 100644 index 000000000..a38543ffe --- /dev/null +++ b/content/changelog/2025/03-27-postgresql-default.md @@ -0,0 +1,18 @@ +--- +title: PostgreSQL 17 is now the default on Clever Cloud +date: 2025-03-27 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Let the magic happen! +excludeSearch: true +--- + +As [PostgreSQL 16 and 17 are available](/developers/changelog/2025/03-18-postgresql-16-17/) on Clever Cloud, we start using PostgreSQL 17 as the default version for new add-ons. **Starting today**, when you create a new PostgreSQL database, it will be setup with PostgreSQL 17. + +* [PostgreSQL versioning policy](https://www.postgresql.org/support/versioning/) +* [Learn more about PostgreSQL on Clever Cloud](/developers/doc/addons/postgresql/) diff --git a/content/changelog/2025/03-28-frankenphp-runtime.md b/content/changelog/2025/03-28-frankenphp-runtime.md new file mode 100644 index 000000000..e12f8d0a9 --- /dev/null +++ b/content/changelog/2025/03-28-frankenphp-runtime.md @@ -0,0 +1,38 @@ +--- +title: "FrankenPHP is available as a runtime on Clever Cloud" +description: Use it, help us to improve +date: 2025-03-28 +tags: + - images + - frankenphp +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +excludeSearch: true +--- + +[As announced last year](https://www.clever-cloud.com/blog/company/2024/10/09/news-php-on-clever-cloud/), we worked to make FrankenPHP available on Clever Cloud as simple as we can. + +First, we started to document how to deploy it with practical examples. Then, we packaged it and included it in our images to make some tests internally and with customers. Starting today, anyone can deploy a PHP application using FrankenPHP on Clever Cloud without needing any Docker container or complex configuration. + +Just create a FrankenPHP application [from API](/developers/api), [Console](https://console.clever-cloud.com) or with [Clever Tools](/developers/doc/cli) and deploy it: + +```bash +echo ' index.php +git init +git add . +git commit -m "Initial FrankenPHP release" + +clever create --type frankenphp +clever deploy +clever open +``` + +FrankenPHP on Clever Cloud comes with [lots of extensions](/developers/doc/applications/frankenphp/#included-extensions) included and we simplified many aspects of application management: if a `composer.json` file is present at the root of your project it's automatically used to install dependencies, you can also use your own `composer.phar` file, Composer flags, define where are the files to serve, define a script to use with FrankenPHP worker feature or a custom run command with environment variables. + +As it's a new image, help us improve it by reporting any issue or suggestion on the [Clever Cloud Community](https://github.com/CleverCloud/Community/discussions/categories/frankenphp). + +* [FrankenPHP and Materia KV example](https://github.com/CleverCloud/frankenphp-kv-json-example) +* [Learn more about FrankenPHP on Clever Cloud](/developers/doc/applications/frankenphp/) +* [Learn more about environment variables on Clever Cloud](/developers/doc/reference/reference-environment-variables/) diff --git a/content/changelog/2025/03-28-keycloak-26.1.4.md b/content/changelog/2025/03-28-keycloak-26.1.4.md new file mode 100644 index 000000000..70d9d462c --- /dev/null +++ b/content/changelog/2025/03-28-keycloak-26.1.4.md @@ -0,0 +1,22 @@ +--- +title: "Keycloak 26.1.4 is available" +date: 2025-03-28 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: With automatic client provisioning +excludeSearch: true +--- + +The release `26.1.4` of Keycloak is available on Clever Cloud. [It fixes](https://github.com/keycloak/keycloak/releases/26.1.4) some bugs, upgrades to Infinispan 15.0.14 and allows administrator to disable automatic refresh of event views `admin/ui`. In this release we also introduce automatic client provisioning. + +To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.1.4` and rebuild it. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak) diff --git a/content/changelog/2025/03-31-kunernetes-operator-0.7.0.md b/content/changelog/2025/03-31-kunernetes-operator-0.7.0.md new file mode 100644 index 000000000..2afcfef05 --- /dev/null +++ b/content/changelog/2025/03-31-kunernetes-operator-0.7.0.md @@ -0,0 +1,19 @@ +--- +title: 'Clever Kubernetes Operator v0.7.0 with wider products support' +date: 2025-03-31 +tags: + - kubernetes + - operator +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florentin Dubois + link: https://github.com/FlorentinDUBOIS + image: https://github.com/FlorentinDUBOIS.png?size=40 +description: Deploy Azimutt, Cellar, Keycloak, Matomo and Otoroshi on Clever Cloud from Kubernetes +excludeSearch: true +--- +[Clever Kubernetes Operator v0.7.0](https://github.com/CleverCloud/clever-kubernetes-operator/releases/tag/v0.6.0) is available. It now uses [clevercloud-sdk-rust v0.15.0](https://github.com/CleverCloud/clevercloud-sdk-rust/releases/tag/v0.15.0) and [oauth10a v2.1.1](https://github.com/CleverCloud/oauth10a-rust/releases/tag/v2.1.1). It fixes some bugs, comes with updated documentation and PostgreSQL versions. If you're connected to [Clever Tools](/developers/doc/cli), credentials are automatically detected and used with this release. [Azimutt](https://azimutt.app/docs), [Cellar](/developers/doc/addons/cellar), [Keycloak](/developers/doc/addons/keycloak), [Matomo](/developers/doc/addons/matomo) and [Otoroshi](/developers/doc/addons/otoroshi) can now be deployed as custom resources. + +- [Learn more about Clever Kubernetes Operator](/developers/guides/kubernetes-operator) diff --git a/content/changelog/2025/04-01-images-update.md b/content/changelog/2025/04-01-images-update.md new file mode 100644 index 000000000..19bac28e9 --- /dev/null +++ b/content/changelog/2025/04-01-images-update.md @@ -0,0 +1,23 @@ +--- +title: "Images update: Rust 1.85.1" +date: 2025-04-01 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: New week, new release! +excludeSearch: true +--- + +We deployed and updated all our images, except Docker and Java, with no impact for our users. + +* **Common:** + * Linux kernel 6.13.8 + * Mise 2025.3.11 +* **Python:** + * uv 0.6.11 +* **Rust:** + * Update to 1.85.1 diff --git a/content/changelog/2025/04-01-otoroshi-17.md b/content/changelog/2025/04-01-otoroshi-17.md new file mode 100644 index 000000000..a738debb9 --- /dev/null +++ b/content/changelog/2025/04-01-otoroshi-17.md @@ -0,0 +1,26 @@ +--- +title: "Otoroshi v17.0.0 is available: OpenAI web search and ecological impact/cost tracking in LLM extension" +date: 2025-04-01 +tags: + - addons + - otoroshi +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: The feature easily in your hands +excludeSearch: true +--- + +[Otoroshi v17.0.0](https://github.com/MAIF/otoroshi/releases/tag/v17.0.0) is available. It fixes some bugs, adds target failover support and allows OpenAPI to be consumed as YAML. This release also brings the new API management feature, providing a way to create an API, flows, routes, backends, consumers and subscriptions. An API is created as draft, can be tested and deployed with lifecycle and version management. This feature is alpha and some functionalities are still early or yet to come. Share your feedback in [Otoroshi's GitHub discussions](https://github.com/MAIF/otoroshi/discussions). + +Biscuit Studio [0.0.12](https://github.com/cloud-apim/otoroshi-biscuit-studio/releases/tag/0.0.12) is included with enhancements from [0.11](https://github.com/cloud-apim/otoroshi-biscuit-studio/releases/tag/0.0.11) release: Distributed revocation, a plugin to fetch a Biscuit from a remote location, new Biscuit extractor types and new admin API routes. + +LLM Extension [0.0.43](https://github.com/cloud-apim/otoroshi-llm-extension/releases/tag/0.0.43) brings support for OpenAI web search and new ecological impact/cost tracking data linked to each request sent to an AI service provider. [The documentation](https://cloud-apim.github.io/otoroshi-llm-extension/docs/overview/) has been updated to reflect these changes. + +To update just set `CC_OTOROSHI_VERSION` of the add-on's Java application to `v17.0.0_1743436155` and rebuild it. You can also delete `CC_OTOROSHI_APIM_VERSION`, `CC_OTOROSHI_SECRET` variables from the Java application, they are not used anymore. + +- [Learn more about Otoroshi with LLM on Clever Cloud](/developers/doc/addons/otoroshi/) diff --git a/content/changelog/2025/04-02-postgresql-replicas.md b/content/changelog/2025/04-02-postgresql-replicas.md new file mode 100644 index 000000000..8db70a950 --- /dev/null +++ b/content/changelog/2025/04-02-postgresql-replicas.md @@ -0,0 +1,20 @@ +--- +title: Manage existing PosgreSQL replicas from the Console +date: 2025-04-02 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Better handle your PostgreSQL replicas +excludeSearch: true +--- + +PostgreSQL dashboard in [the Clever Cloud Console](https://console.clever-cloud.com) now shows if a database is a standalone server or a replica. For PostgreSQL 12+ add-ons, you can promote a read-only replica as a read-write standalone server. + +To set up replicas, ask your sales representative or [contact support](https://console.clever-cloud.com/ticket-center-choice). + +* [Learn more about PostgreSQL replication](/developers/doc/addons/postgresql#replication) +* [Learn more about PostgreSQL on Clever Cloud](/developers/doc/addons/postgresql/) diff --git a/content/changelog/2025/04-03-images-update.md b/content/changelog/2025/04-03-images-update.md new file mode 100644 index 000000000..d86d488f4 --- /dev/null +++ b/content/changelog/2025/04-03-images-update.md @@ -0,0 +1,30 @@ +--- +title: "Images update: news for Tailscale, SQL Server extensions for PHP" +date: 2025-04-03 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Multiple new features and a fix for this week! +excludeSearch: true +--- + +We deployed and updated all our images, with no impact for our users. + +* **Common:** + * Fix an issue with scaling feature + * Linux kernel 6.13.9 + * Mise 2025.3.11 + * Tailscale 1.82.0 +* **Go:** + * Update to 1.24.2 + +SQL Server extensions (`sqlsrv` and `pdo_sqlsrv`) are now available for PHP 8.1 to 8.4. To enable them, add `ENABLE_SQLSRV=true` or `ENABLE_PDO_SQLSRV=true` environment variables to your application. + +We enhanced our Tailscale native integration. It now supports `--accept-dns` and `--accept-routes` [flags](https://tailscale.com/kb/1072/client-preferences?q=accept-route#use-tailscale-dns-settings). To disable or enable them, set `TAILSCALE_ACCEPT_DNS` and `TAILSCALE_ACCEPT_ROUTES` environment variables to `false` or `true` in your application. + +- [Learn more about Tailscale on Clever Cloud](/developers/doc/reference/reference-environment-variables/#tailscale-support) +- [Learn more about PHP with Apache on Clever Cloud](/developers/doc/applications/php/) diff --git a/content/changelog/2025/04-04-postgresql-locale.md b/content/changelog/2025/04-04-postgresql-locale.md new file mode 100644 index 000000000..0c8ee538a --- /dev/null +++ b/content/changelog/2025/04-04-postgresql-locale.md @@ -0,0 +1,24 @@ +--- +title: PostgreSQL locale support at database creation +date: 2025-04-04 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Choose the locale of your PostgreSQL database at creation +excludeSearch: true +--- + +You can now define the locale of your PostgreSQL database when creating a new add-on with [Clever Tools](/developers/doc/cli): + +```bash +clever addon create postgresql-addon pgLocaleTest --plan xxs_sml --option locale=en_US +``` + +This will create a PostgreSQL database with the `en_US` locale instead of the default `en_GB` locale. + +* [PostgreSQL versioning policy](https://www.postgresql.org/support/versioning/) +* [Learn more about PostgreSQL on Clever Cloud](/developers/doc/addons/postgresql/) diff --git a/content/changelog/2025/04-10-mysql-8.4.4-update.md b/content/changelog/2025/04-10-mysql-8.4.4-update.md new file mode 100644 index 000000000..27ebd6776 --- /dev/null +++ b/content/changelog/2025/04-10-mysql-8.4.4-update.md @@ -0,0 +1,18 @@ +--- +title: MySQL 8.4.4-4 is available +date: 2025-04-10 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Get new features and improvements +excludeSearch: true +--- + +We updated MySQL 8.4 from Percona Server. They're now available for add-ons creation and migration. + +* [Learn more about MySQL on Clever Cloud](/developers/doc/addons/mysql/) +* [Learn more about MySQL 8.4.4-4](https://docs.percona.com/percona-server/8.4/release-notes/8.4.4-4.html) diff --git a/content/changelog/2025/04-16-images-update.md b/content/changelog/2025/04-16-images-update.md new file mode 100644 index 000000000..a43eb4c71 --- /dev/null +++ b/content/changelog/2025/04-16-images-update.md @@ -0,0 +1,34 @@ +--- +title: "Images update: Bun included, Rust 1.86" +date: 2025-04-16 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Native support for Bun incoming +excludeSearch: true +--- + +We updated all our images, except Java. Deployment is in progress for all our users. + +* **Common:** + * Linux kernel 6.14.2 + * Mise 2025.4.2 + * OpenSSH 10.0p2 + * OpenSSL 3.5.0 + * Tailscale 1.82.0 +* **Node.js:** + * Bun 1.2.9 +* **PHP:** + * Update to 8.4.6 + * Composer 2.8.8 +* **Python:** + * Update to 3.13.3 + * uv 0.6.14 +* **Rust:** + * Update to 1.86.0 + +Bun is now part of our included tools, and will be natively supported in an upcoming release of our Node.js runtime. diff --git a/content/changelog/2025/04-22-metabase-54.md b/content/changelog/2025/04-22-metabase-54.md new file mode 100644 index 000000000..423bf663c --- /dev/null +++ b/content/changelog/2025/04-22-metabase-54.md @@ -0,0 +1,23 @@ +--- +title: "Metabase 54 is available" +date: 2025-04-22 +tags: + - addons + - metabase +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Faster, with more features +excludeSearch: true +--- + +The `x.54` branch of Metabase is now available on Clever Cloud. It brings new custom expression editor, better table visualization, simplified data picker for embedding, support of BigInteger values, multiple enhancements and bug fixes. To update, just set `CC_METABASE_VERSION` of the add-on's Java application to `0.54` for the community edition or `1.54` for the enterprise edition (EE). + +- [Learn more about Metabase 54](https://www.metabase.com/releases/metabase-54) +- [Learn more about Metabase on Clever Cloud](/developers/doc/addons/metabase/) + +{{< youtube id="ew20x0refcs" >}} diff --git a/content/changelog/2025/04-24-keycloak-26.2.1-grafana.md b/content/changelog/2025/04-24-keycloak-26.2.1-grafana.md new file mode 100644 index 000000000..4c94236be --- /dev/null +++ b/content/changelog/2025/04-24-keycloak-26.2.1-grafana.md @@ -0,0 +1,35 @@ +--- +title: "Keycloak 26.2.1 is available with new features and a Grafana dashboard" +date: 2025-04-24 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Thanks to Clever Cloud's native Grafana experience +excludeSearch: true +--- + +The release `26.2.1` of Keycloak is available on Clever Cloud. [This new branch fixes](https://github.com/keycloak/keycloak/releases?q=26.2&expanded=true) some bugs, supports Standard Token Exchange according to [Token exchange specification](https://datatracker.ietf.org/doc/html/rfc8693), brings ECS (Elastic Common Schema) JSON format [for logs](https://www.keycloak.org/server/logging), fine-grained admin permissions, etc. To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.2.1` and rebuild it. + +## Grafana dashboard + +Each Clever Cloud account organisation [comes with a pre-configured Grafana service](/developers/doc/metrics/#publish-your-own-metrics). With recent Keycloak enhancements on metrics and observability, we've worked on a Grafana dashboard ready to import: +- Go to the `Metrics in Grafana` section of your organisation or personal space in [Console](https://console.clever-cloud.com/) +- Open Grafana, click on the `+` icon in the upper right corner and select `Import` dashboard +- Import this [JSON file](https://cc-keycloak.cellar-c2.services.clever-cloud.com/keycloak-grafana-dashboard.json) + +Then you'll have a `Keycloak dashboard` in your Grafana folders. Just select your Keycloak add-on in the `runtime section`, you'll automatically get instance's information, metrics, cache and performance data, etc. + +## New features and settings + +Starting with this release, Keycloak add-ons on Clever Cloud come with `admin-cli` client disabled by default. If you need it for provisioning through a `direct access grant`, you must enable it first. + +You can now set up a new client with the `admin` role for `master` realm during build using `CC_KEYCLOAK_BOOTSTRAP_ADMIN_CLIENT_ID` and `CC_KEYCLOAK_BOOTSTRAP_ADMIN_CLIENT_SECRET` environment variables. Once created, delete them from your application. Bootstrap client [should be temporary](https://www.keycloak.org/server/bootstrap-admin-recovery) and is mostly necessary for provisioning. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak) diff --git a/content/changelog/2025/04-25-otoroshi-biscuit-studio-0.0.13.md b/content/changelog/2025/04-25-otoroshi-biscuit-studio-0.0.13.md new file mode 100644 index 000000000..41fb0eeba --- /dev/null +++ b/content/changelog/2025/04-25-otoroshi-biscuit-studio-0.0.13.md @@ -0,0 +1,22 @@ +--- +title: "Otoroshi update with Biscuit Studio 0.0.13" +date: 2025-04-25 +tags: + - addons + - otoroshi +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Use Biscuits, end-to-end +excludeSearch: true +--- + +[Otoroshi v17.0.0](https://github.com/MAIF/otoroshi/releases/tag/v17.0.0) is available with Biscuit Studio [0.0.13](https://github.com/cloud-apim/otoroshi-biscuit-studio/releases/tag/0.0.13) which enhance `BiscuitUserExtractor` plugin capabilities. + +To update just set `CC_OTOROSHI_VERSION` of the add-on's Java application to `v17.0.0_1745325312` and rebuild it. You can also delete `CC_OTOROSHI_APIM_VERSION`, `CC_OTOROSHI_SECRET` variables from the Java application, they are not used anymore. + +- [Learn more about Otoroshi with LLM on Clever Cloud](/developers/doc/addons/otoroshi/) diff --git a/content/changelog/2025/04-30-keycloak-26.2.2-security.md b/content/changelog/2025/04-30-keycloak-26.2.2-security.md new file mode 100644 index 000000000..577a809ef --- /dev/null +++ b/content/changelog/2025/04-30-keycloak-26.2.2-security.md @@ -0,0 +1,22 @@ +--- +title: "Keycloak 26.2.2 is available (security update)" +date: 2025-04-30 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Two CVE fixed +excludeSearch: true +--- + +The release `26.2.2` of Keycloak is available on Clever Cloud. [It fixes](https://github.com/keycloak/keycloak/releases/26.2.2) some bugs, [CVE-2025-3501](https://nvd.nist.gov/vuln/detail/CVE-2025-3501) and[CVE-2025-3910](https://nvd.nist.gov/vuln/detail/CVE-2025-3910). + +To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.2.2` and rebuild it. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak) diff --git a/content/changelog/2025/05-06-images-update.md b/content/changelog/2025/05-06-images-update.md new file mode 100644 index 000000000..2d9c85a7a --- /dev/null +++ b/content/changelog/2025/05-06-images-update.md @@ -0,0 +1,34 @@ +--- +title: "Images update: PHP 8.4 is now default, some cleanup" +date: 2025-05-06 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Node.js 18 and Ruby 3.1 are now EOL +excludeSearch: true +--- + +We updated all our images. Deployment is in progress for all our users. + +* **Common:** + * Linux kernel 6.14.4 + * Mise 2025.5.0 + * Redis 8.0.0 + * Tailscale 1.82.5 +* **Go:** + * Update to 1.24.2 +* **Node.js:** + * Update to 22.15 (npm 10.9.2) +* **Python:** + * uv 0.7.2 + +As previously announced, Python 3.8 [is not available in our images anymore](/developers/changelog/2025/03-25-python-3.8-eol/) and PHP 8.4 [is now used as default](/developers/changelog/2025/03-21-php-version-management-update/) for `CC_PHP_VERSION=8`. As Node.js 18 and Ruby 3.1 are now end-of-life, you'll get a warning if you use them. + +- [Learn more about Node.js release cycle](https://nodejs.org/en/about/releases/) +- [Learn more about PHP release cycle](https://www.php.net/supported-versions.php) +- [Learn more about Python release cycle](https://devguide.python.org/versions/#python-release-cycle) +- [Learn more about Ruby release cycle](https://www.ruby-lang.org/en/downloads/branches/) diff --git a/content/changelog/2025/05-06-keycloak-26.2.3.md b/content/changelog/2025/05-06-keycloak-26.2.3.md new file mode 100644 index 000000000..2c08895b8 --- /dev/null +++ b/content/changelog/2025/05-06-keycloak-26.2.3.md @@ -0,0 +1,22 @@ +--- +title: "Keycloak 26.2.3 is available" +date: 2025-05-06 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: With a bug fix for Clever Cloud module +excludeSearch: true +--- + +The release `26.2.3` of Keycloak is available on Clever Cloud. [It fixes](https://github.com/keycloak/keycloak/releases/26.2.3) some bugs and brings possibility to log details and representation to the jboss-logging listener. We updated the Clever Cloud module to comply with the new Keycloak API for 26.x releases. + +To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.2.3` and rebuild it. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak). diff --git a/content/changelog/2025/05-06-redis-8.0.0.md b/content/changelog/2025/05-06-redis-8.0.0.md new file mode 100644 index 000000000..d0292503c --- /dev/null +++ b/content/changelog/2025/05-06-redis-8.0.0.md @@ -0,0 +1,23 @@ +--- +title: Redis 8.0.0 is available +date: 2025-05-06 +tags: + - addons + - redis +authors: + - name: Aurélien Hébert + link: https://github.com/aurrelhebert + image: https://github.com/aurrelhebert.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Welcome back to open source +excludeSearch: true +--- + +As Redis™ is [open source again](https://antirez.com/news/151), we're able to provide release `8.0.0`. It's now available for each new deployment. You can easily migrate an existing instance from [Console](https://console.clever-cloud.com). This new branch brings performance improvements, new features, and bug fixes. + +- [Learn more about Redis™ 8](https://redis.io/blog/redis-8-ga/) +- [Learn more about Redis™ on Clever Cloud](/developers/doc/addons/redis/) + +{{< youtube id="EeSckl2L3Xs" >}} diff --git a/content/changelog/2025/05-07-node-24.md b/content/changelog/2025/05-07-node-24.md new file mode 100644 index 000000000..e7f989c4b --- /dev/null +++ b/content/changelog/2025/05-07-node-24.md @@ -0,0 +1,26 @@ +--- +title: "Node.js 24.0 is available, will be LTS and used by default in October" +description: Prepare your applications +date: 2025-05-07 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +excludeSearch: true +--- + +2025 is an important year for Node.js ecosystem with big changes for multiple branches: +- 18.x LTS is end-of-life since April 30th and won't receive any new security updates +- 20.x LTS is in maintenance mode and will receive security updates until April 30th, 2026 +- 22.x LTS, will enter maintenance mode in October and will receive security updates until April 30th, 2027 +- 23.x is in maintenance mode and will receive security updates until June 1st +- 24.x [is now available](https://nodejs.org/en/blog/release/v24.0.0) as the "Current" release. It will be LTS starting October and supported until April 2028 + +In Clever Cloud runtimes, we use the latest LTS version by default. Thus, it's currently 22.x, and we'll move to 24.x in October. Until then you can use 24.x branch by setting the `CC_NODE_VERSION` environment variable to `^24`, `24` or `24.0`, for example: + +* [Learn more about Node.js release cycle](https://nodejs.org/en/about/releases/) +* [Learn more about Node.js on Clever Cloud](/developers/doc/applications/nodejs/) +* [Learn more about environment variables on Clever Cloud](/developers/doc/reference/reference-environment-variables/) diff --git a/content/changelog/2025/05-12-keycloak-26.2.4.md b/content/changelog/2025/05-12-keycloak-26.2.4.md new file mode 100644 index 000000000..063e6cb68 --- /dev/null +++ b/content/changelog/2025/05-12-keycloak-26.2.4.md @@ -0,0 +1,22 @@ +--- +title: "Keycloak 26.2.4 is available" +date: 2025-05-12 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: bug fix release +excludeSearch: true +--- + +The release `26.2.4` of Keycloak is available on Clever Cloud which [fixes](https://github.com/keycloak/keycloak/releases/26.2.4) some bugs. + +To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.2.4` and rebuild it. + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak) diff --git a/content/changelog/2025/05-13-images-update.md b/content/changelog/2025/05-13-images-update.md new file mode 100644 index 000000000..984d081b9 --- /dev/null +++ b/content/changelog/2025/05-13-images-update.md @@ -0,0 +1,31 @@ +--- +title: "Images update: Go 1.24.3, PHP 8.4.7" +date: 2025-05-13 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Lots of patch updates +excludeSearch: true +--- + +We updated all our images. Deployment is in progress for all our users. + +* **Common:** + * Linux kernel 6.14.6 +* **Docker:** + * Update to 28.11.1 +* **Elixir** + * Erlang 25.3.2.21 + * Erlang 26.2.5.12 + * Erlang 27.3.4 +* **Go:** + * Update to 1.24.3 +* **PHP:** + * Update to 8.3.21 + * Update to 8.4.7 +* **Python:** + * uv 0.7.3 diff --git a/content/changelog/2025/05-14-otoroshi-api-env-vars.md b/content/changelog/2025/05-14-otoroshi-api-env-vars.md new file mode 100644 index 000000000..2438586c7 --- /dev/null +++ b/content/changelog/2025/05-14-otoroshi-api-env-vars.md @@ -0,0 +1,29 @@ +--- +title: "Link Otoroshi API credentials to your applications" +date: 2025-05-14 +tags: + - addons + - otoroshi +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: +excludeSearch: true +--- + +Starting today, new Otoroshi add-ons deployed on Clever Cloud will expose API related environment variables as service dependencies: + +- `CC_OTOROSHI_API_URL`: the base URL of the Otoroshi API +- `CC_OTOROSHI_API_CLIENT_ID`: the API key to query the Otoroshi API +- `CC_OTOROSHI_API_CLIENT_SECRET`: the API secret to query the Otoroshi API + +Thus, you'll be able to link the add-on to an application and get the API URL and credentials as environment variables. + +`ADMIN_API_CLIENT_ID` and `ADMIN_API_CLIENT_SECRET` environment variables of the Java application are replaced by `CC_OTOROSHI_API_CLIENT_ID` and `CC_OTOROSHI_API_CLIENT_SECRET` but are still supported during deployment for legacy reasons. The `CC_OTOROSHI_SSO_URL` is removed from service dependencies on new add-ons as it's not useful here. + +- [Learn more about service dependencies](/developers/doc/administrate/service-dependencies/) +- [Learn more about Otoroshi on Clever Cloud](/developers/doc/addons/otoroshi/) diff --git a/content/changelog/2025/05-15-redis-8.0.1.md b/content/changelog/2025/05-15-redis-8.0.1.md new file mode 100644 index 000000000..660521e7f --- /dev/null +++ b/content/changelog/2025/05-15-redis-8.0.1.md @@ -0,0 +1,20 @@ +--- +title: Redis 8.0.1 is available +date: 2025-05-15 +tags: + - addons + - redis +authors: + - name: Aurélien Hébert + link: https://github.com/aurrelhebert + image: https://github.com/aurrelhebert.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Some fixes and stability improvements +excludeSearch: true +--- + +We updated Redis™ to [release 8.0.1](https://github.com/redis/redis/releases/tag/8.0.1) with kernel `6.14.6` to fix some stability issues. It's available for add-ons creation and migration. + +- [Learn more about Redis™ on Clever Cloud](/developers/doc/addons/redis/) diff --git a/content/changelog/2025/05-16-images-update.md b/content/changelog/2025/05-16-images-update.md new file mode 100644 index 000000000..bf036eb59 --- /dev/null +++ b/content/changelog/2025/05-16-images-update.md @@ -0,0 +1,37 @@ +--- +title: "Images update: Composer 2.8.9, Node.js 22.15.1, Rust 1.87.0" +date: 2025-05-16 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: With CC_NODE_VERSION supported in all runtimes +excludeSearch: true +--- + +We updated all our images. Deployment is in progress for all our users. + +* **Common:** + * Linux kernel 6.14.6 with stability fix + * Mise 2025.5.3 + * Redis 8.0.1 + * SQLite 3.49.2 +* **Node.js:** + * Update to 22.15.1 (npm 10.9.2) + * Bun 1.2.9 +* **PHP:** + * Composer 2.8.9 +* **Ruby:** + * Update to 3.1.7 + * Update to 3.2.8 + * Update to 3.3.8 + * Update to 3.4.3 +* **Rust:** + * Update to 1.87.0 + +This release introduces `CC_NODE_VERSION` support [for Node.js applications](/developers/changelog/2025/05-16-node-versions/). When an application is restarted for image update, it won't appear as `Maintenance` anymore, but as `Maintenance/ImageUpdate` + +- [Learn more about Node.js on Clever Cloud](/developers/doc/applications/nodejs) diff --git a/content/changelog/2025/05-16-node-versions.md b/content/changelog/2025/05-16-node-versions.md new file mode 100644 index 000000000..f139cb3e9 --- /dev/null +++ b/content/changelog/2025/05-16-node-versions.md @@ -0,0 +1,17 @@ +--- +title: "Simpler Node.js version management" +date: 2025-05-16 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: One rule to rule them all +excludeSearch: true +--- + +Until now, to set Node.js version on Clever Cloud, you had to use the `engines.node` field in `package.json` for Node.js applications, or the `CC_NODE_VERSION` environment variable for all other runtimes. Now, you can use `CC_NODE_VERSION` for Node.js applications too. It won't change anything for existing applications, but we recommend you to switch for such behavior. + +- [Learn more about Node.js on Clever Cloud](/developers/doc/applications/nodejs) diff --git a/content/changelog/2025/05-16-terraform-0.8.md b/content/changelog/2025/05-16-terraform-0.8.md new file mode 100644 index 000000000..bdb6ed19b --- /dev/null +++ b/content/changelog/2025/05-16-terraform-0.8.md @@ -0,0 +1,20 @@ +--- +title: Terraform provider 0.8.0 is available +description: FS Buckets support and Cellar add-ons update +date: 2025-05-16 +tags: + - addons + - terraform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +excludeSearch: true +--- + +The [0.8.0 release](https://github.com/CleverCloud/terraform-provider-clevercloud/releases/tag/v0.8.0) of the Clever Cloud Terraform provider introduces support for [FS Buckets](/developers/doc/addons/fs-bucket/) and update for [Cellar add-ons](/developers/doc/addons/cellar/) + +* Learn more about [our Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs) diff --git a/content/changelog/2025/05-19-otoroshi-17.1.1.md b/content/changelog/2025/05-19-otoroshi-17.1.1.md new file mode 100644 index 000000000..6ad962141 --- /dev/null +++ b/content/changelog/2025/05-19-otoroshi-17.1.1.md @@ -0,0 +1,24 @@ +--- +title: "Otoroshi 17.1 is available, audio and image models supported by LLM extension" +date: 2025-05-19 +tags: + - addons + - otoroshi +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Use Biscuits, end-to-end +excludeSearch: true +aliases: +- /changelog/2025/19-05-otoroshi-17.1.1/ +--- + +[Otoroshi v17.1](https://github.com/MAIF/otoroshi/releases?q=v17.1&expanded=true) is available with multiple improvements, bug fixes and a new canary mode plugin with autonomous rollout. LLM extension is updated to [0.0.46 release](https://github.com/cloud-apim/otoroshi-llm-extension/releases/tag/0.0.46) which brings new OVHcloud endpoints, user provided data for ecological/cost tracking, support of multiple models for audio (speech-to-text, text-to-speech), image generation and moderation. + +To update just set `CC_OTOROSHI_VERSION` of the add-on's Java application to `v17.1.1_1747324564` and rebuild it. + +- [Learn more about Otoroshi with LLM on Clever Cloud](/developers/doc/addons/otoroshi/) diff --git a/content/changelog/2025/05-20-matomo-5.3.2.md b/content/changelog/2025/05-20-matomo-5.3.2.md new file mode 100644 index 000000000..7f3d4fe1b --- /dev/null +++ b/content/changelog/2025/05-20-matomo-5.3.2.md @@ -0,0 +1,21 @@ +--- +title: Matomo v5.3.2 is available +date: 2025-05-20 +tags: + - addons + - matomo +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Upgraded with no effort needed +excludeSearch: true +--- + +Our [Matomo](https://matomo.org/) add-on has been updated to version `v5.3.2` which is now used by default. You can deploy this latest release from our [Console](https://console.clever-cloud.com) or [Clever Tools](/developers/doc/cli/). Existing customers add-ons are already up-to-date. + +- [Learn more about Matomo 5.3.2](https://matomo.org/changelog/matomo-5-3-2/) +- [Learn more about Matomo on Clever Cloud](/developers/doc/addons/matomo/) diff --git a/content/changelog/2025/05-20-pg-update-17.5.md b/content/changelog/2025/05-20-pg-update-17.5.md new file mode 100644 index 000000000..2f0fc76e5 --- /dev/null +++ b/content/changelog/2025/05-20-pg-update-17.5.md @@ -0,0 +1,24 @@ +--- +title: PostgreSQL 17.5, 16.9, 15.13, 14.18 and 13.21 are available (security update) +date: 2025-05-20 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Migrate to the latest PostgreSQL versions +excludeSearch: true +--- + +New PostgreSQL versions are available for new add-ons and migration: +* PostgreSQL 17.5 +* PostgreSQL 16.9 +* PostgreSQL 15.13 +* PostgreSQL 14.18 +* PostgreSQL 13.21 + +It includes [fixes and improvements](https://www.postgresql.org/about/news/postgresql-175-169-1513-1418-and-1321-released-3072/), including a security patch for [CVE-2025-4207](https://nvd.nist.gov/vuln/detail/CVE-2025-4207). + +* [Learn more about PostgreSQL on Clever Cloud](/developers/doc/addons/postgresql/) diff --git a/content/changelog/2025/05-28-oauth-consumer-new-interface.md b/content/changelog/2025/05-28-oauth-consumer-new-interface.md new file mode 100644 index 000000000..2b38ada15 --- /dev/null +++ b/content/changelog/2025/05-28-oauth-consumer-new-interface.md @@ -0,0 +1,22 @@ +--- +title: 'New look for OAuth consumers management' +date: 2025-05-28 +tags: + - console + - oauth +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: You like new pages? Wait for the next one! +excludeSearch: true +--- + +A new interface is available [in Clever Cloud Console to create](https://console.clever-cloud.com/users/me/oauth-consumers/new) and manage OAuth consumers. It's better, clearer, simpler, and uses our open source [web components](/developers/clever-components/). + +- [Learn more about OAuth consumers](/developers/api/howto/#oauth1) + +![New OAuth consumers interface](/images/new-oauth-consumer.webp) diff --git a/content/changelog/2025/06-03-images-update.md b/content/changelog/2025/06-03-images-update.md new file mode 100644 index 000000000..8f6322f17 --- /dev/null +++ b/content/changelog/2025/06-03-images-update.md @@ -0,0 +1,45 @@ +--- +title: "Images update: custom port for FrankenPHP, Erlang 28" +date: 2025-06-03 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: More flexible FrankenPHP, and more under the hood… +excludeSearch: true +--- + +We updated all our images. Deployment is in progress for all our users. + +* **Common:** + * Linux kernel 6.14.9 + * Mise 2025.5.17 + * Redis 8.0.2 + * SQLite 3.50.0 +* **Elixir:** + * Update to 1.18.4 + * Erlang 28.0 +* **FrankenPHP:** + * Update to 1.6.2 +* **Go:** + * Update to 1.24.3 +* **Node.js:** + * Update to 22.16.0 (npm 10.9.2) + * Bun 1.2.15 +* **Python:** + * uv 0.7.9 +* **Ruby:** + * Update to 3.4.4 + +## Bun native support +This release introduces [Bun](https://bun.sh) native support on Clever Cloud, with auto-detection of `bun.lock` file. + +- [Learn more about Bun support on Clever Cloud](/developers/changelog/2025/06-03-native-bun-support/) + +## FrankenPHP custom port +You can also set `CC_FRANKENPHP_PORT` to use a different port than the default `8080`. It allows you to use services in front of your FrankenPHP application such as [Redirection.io](/developers/doc/reference/reference-environment-variables/#use-redirectionio-as-a-proxy) for example. + +- [Learn more about FrankenPHP on Clever Cloud](/developers/doc/applications/frankenphp/) diff --git a/content/changelog/2025/06-03-native-bun-support.md b/content/changelog/2025/06-03-native-bun-support.md new file mode 100644 index 000000000..d0ca629d8 --- /dev/null +++ b/content/changelog/2025/06-03-native-bun-support.md @@ -0,0 +1,38 @@ +--- +title: "Bun native support on Clever Cloud" +description: Run Bun without any efforts +date: 2025-06-03 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +excludeSearch: true +--- + +[Since April](/developers/changelog/2025/04-16-images-update/), Bun is included in our images. It helped customers to deploy their applications faster, profit from its native [Redis®](https://bun.sh/docs/api/redis) and [object storage](https://bun.sh/docs/api/s3) support. Starting today, you can deploy your Bun applications on Clever Cloud without any efforts. + +If a `bun.lock` file is detected at the root of your project, and you didn't ask for another JavaScript runtime or package manager, your application will be deployed with [Bun](https://bun.sh) as a package manager and runtime. You can also ask for Bun explicitly by setting the `CC_NODE_BUILD_TOOL` environment variable to `bun`. + +Want to give it a try? Just launch these commands with Bun and [Clever Tools CLI](/developers/doc/cli/install) installed on your system: + +``` +mkdir bunDemo +cd bunDemo + +git init +bun init --yes --react + +git add . +git commit -m "Initial commit" + +clever create --type node +clever deploy +clever open +``` + +You'll get a basic React application running on Bun, deployed on Clever Cloud. + +* [Learn more about Bun & Node.js on Clever Cloud](/developers/doc/applications/nodejs) diff --git a/content/changelog/2025/06-03-terraform-0.9.md b/content/changelog/2025/06-03-terraform-0.9.md new file mode 100644 index 000000000..1be536d9e --- /dev/null +++ b/content/changelog/2025/06-03-terraform-0.9.md @@ -0,0 +1,20 @@ +--- +title: Terraform provider 0.9.0 is available +description: Application restart, git local repositories, and Play 2 support +date: 2025-06-03 +tags: + - addons + - terraform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +excludeSearch: true +--- + +The [0.9.0 release](https://github.com/CleverCloud/terraform-provider-clevercloud/releases/tag/v0.9.0) of the Clever Cloud Terraform provider introduces support for `play2` applications and git local repositories. Starting with this release, if you change an application environment variable, it will be restarted automatically. + +* Learn more about [our Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs) diff --git a/content/changelog/2025/06-04-redis-8.0.2.md b/content/changelog/2025/06-04-redis-8.0.2.md new file mode 100644 index 000000000..13cc53ae4 --- /dev/null +++ b/content/changelog/2025/06-04-redis-8.0.2.md @@ -0,0 +1,20 @@ +--- +title: Redis 8.0.2 is available (security update) +date: 2025-06-04 +tags: + - addons + - redis +authors: + - name: Aurélien Hébert + link: https://github.com/aurrelhebert + image: https://github.com/aurrelhebert.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Upgrade your database in a snap +excludeSearch: true +--- + +We updated Redis™ to [release 8.0.2](https://github.com/redis/redis/releases/tag/8.0.2) which fixes [CVE-2025-27151](https://nvd.nist.gov/vuln/detail/CVE-2025-27151). It's available for add-ons creation and migration. + +- [Learn more about Redis™ on Clever Cloud](/developers/doc/addons/redis/) diff --git a/content/changelog/2025/06-05-api-tokens-console-tips.md b/content/changelog/2025/06-05-api-tokens-console-tips.md new file mode 100644 index 000000000..d3044286d --- /dev/null +++ b/content/changelog/2025/06-05-api-tokens-console-tips.md @@ -0,0 +1,37 @@ +--- +title: 'API tokens in Console… with API and Clever Tools tips' +date: 2025-06-05 +tags: + - console + - tokens +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florian Sanders + link: https://github.com/florian-sanders-cc + image: https://github.com/florian-sanders-cc.png?size=40 +description: API tokens and tips everywhere! +excludeSearch: true +--- + +With [Clever Tools 3.12](/developers/changelog/2025/03-07-clever-tools-3.12/), we've introduced a new way to query Clever Cloud's API, with [the API bridge and API tokens](/developers/api/howto/#api-tokens). Starting today, you can create, edit and revoke API tokens directly [from your Clever Cloud profile page](https://console.clever-cloud.com/users/me/api-tokens). + +## API tokens in the Clever Cloud Console + +This interface also shows the token name, description, public ID, creation and expiration date. + +To create an API token, you need to provide: + +- Your current password +- Your 2FA code if active (activate it [here](https://console.clever-cloud.com/users/me/authentication)) + +If you created your Clever Cloud account through the GitHub integration, you'll be asked to set a password first. + +![Manage API tokens in Clever Cloud Console](/images/console-api-tokens.webp) + +## Clever Tools and API tips in the Console + +This interface also introduces a new [Web Component](https://www.clever.cloud/developers/clever-components/) to show Clever Tools commands and API requests related to the page you visit. In the coming weeks, we'll add more of these tips over the Clever Cloud Console. + +![API Tokens API & Clever Tools Tips](/images/console-api-tokens-tips.webp) diff --git a/content/changelog/2025/06-05-mysql-8.0.42-8.4.5.md b/content/changelog/2025/06-05-mysql-8.0.42-8.4.5.md new file mode 100644 index 000000000..fe22e5a12 --- /dev/null +++ b/content/changelog/2025/06-05-mysql-8.0.42-8.4.5.md @@ -0,0 +1,19 @@ +--- +title: MySQL 8.0.42 and 8.4.5 are available +date: 2025-06-05 +tags: + - addons + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Get new features and improvements +excludeSearch: true +--- + +We updated MySQL 8.0 and 8.4 from Percona Server. They're now available for add-ons creation and migration. + +* [Learn more about MySQL on Clever Cloud](/developers/doc/addons/mysql/) +* [Learn more about MySQL 8.0.42](https://docs.percona.com/percona-server/8.0/release-notes/8.0.42-33.html) +* [Learn more about MySQL 8.4.5](https://docs.percona.com/percona-server/8.4/release-notes/8.4.5-5.html) diff --git a/content/changelog/2025/06-05-oauth-tokens-new-interface.md b/content/changelog/2025/06-05-oauth-tokens-new-interface.md new file mode 100644 index 000000000..4c45727e8 --- /dev/null +++ b/content/changelog/2025/06-05-oauth-tokens-new-interface.md @@ -0,0 +1,24 @@ +--- +title: 'New look for OAuth tokens management' +date: 2025-06-05 +tags: + - console + - oauth +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florian Sanders + link: https://github.com/florian-sanders-cc + image: https://github.com/florian-sanders-cc.png?size=40 +description: Bye bye old OAuth tokens interface! +excludeSearch: true +--- + +After [renewing OAuth consumers management](/developers/changelog/2025/05-28-oauth-consumer-new-interface/), we've just updated the [OAuth tokens section](https://console.clever-cloud.com/users/me/oauth-tokens) of users profile. It's where you can see applications linked to your Clever Cloud account: Clever Tools, the Console or those linked to other OAuth consumers. You can still see creation and expiration date, last usage, revoke any or all of them… but in a clearer interface. + +We also added a link to Clever Cloud's OAuth tokens documentation. + +- [Learn more about OAuth tokens](/api/howto/#oauth1) + +![New OAuth tokens interface](/images/console-new-oauth-tokens.webp) diff --git a/content/changelog/2025/06-05-web-sessions-console.md b/content/changelog/2025/06-05-web-sessions-console.md new file mode 100644 index 000000000..a2b5364d8 --- /dev/null +++ b/content/changelog/2025/06-05-web-sessions-console.md @@ -0,0 +1,20 @@ +--- +title: 'List and revoke your active Console sessions' +date: 2025-06-05 +tags: + - console + - sessions +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Florian Sanders + link: https://github.com/florian-sanders-cc + image: https://github.com/florian-sanders-cc.png?size=40 +description: More security data from the Console +excludeSearch: true +--- + +There is now a dedicated page [to list web sessions in the Clever Cloud Console](https://console.clever-cloud.com/users/me/session-tokens). It shows all the sessions currently active across your devices and browsers with creation/expiration date, last activity. You can revoke any sessions, except the current one (disconnect from the Console to revoke it). + +![Manage sessions in Clever Cloud Console](/images/console-sessions.webp) diff --git a/content/changelog/2025/06-10-clever-tools-3.13.md b/content/changelog/2025/06-10-clever-tools-3.13.md new file mode 100644 index 000000000..a202d92a1 --- /dev/null +++ b/content/changelog/2025/06-10-clever-tools-3.13.md @@ -0,0 +1,81 @@ +--- +date: 2025-06-10 +title: 'Clever Tools 3.13: emails, operators, SSH keys, better UX' +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: Manage more things in a better way +excludeSearch: true +--- + +[Clever Tools 3.13](https://github.com/CleverCloud/clever-tools/releases/tag/3.13.0) is available. It includes some bug fixes and a new interface for application management commands. Our goal here is to start making Clever Tools more user-friendly with more useful information, tips and a better look. It paves the way for next major releases. [Let us know what you think](https://github.com/CleverCloud/clever-tools/issues) about it to help us to design the future of Clever Tools. + +The `clever tokens` command is not experimental anymore, as [API tokens are now available](/developers/changelog/2025/06-05-api-tokens-console-tips/) through the Clever Cloud Console. + +![New clever create command](/images/clever-tools-new-create.webp) + +## Operators + +The `operators` experimental feature adds direct commands for services deployed and managed through our Operators, such as Keycloak, Matomo, Metabase and Otoroshi. You can now get useful information about these services once deployed, restart, rebuild or update them, open their dashboard or web management interface, activate features such as Network Groups, etc. + +```bash +clever features enable operators + +clever keycloak get myKeycloak +clever keycloak enable-ng myKeycloak + +clever matomo open webui myMatomo +clever metabase rebuild metabase_id +clever otoroshi version update otoroshi_id +``` + +- [Learn more about Operators commands in Clever Tools](/developers/doc/cli/operators/) + +![Check Metabase Version command](/images/clever-tools-metabase-version-check.webp) + +## Emails and public SSH keys + +Manage your Clever Cloud account's emails and public SSH keys with the new `clever emails` and `clever ssh-keys` commands: + +``` +clever emails +clever ssh-keys -F json + +clever emails add email@example.com +clever emails primary email@example.com +clever ssh-keys add myNewPublicKey ~/.ssh/id_ecdsa.pub + +clever emails remove-all +clever ssh-keys remove-all +``` + +- [Learn more about emails and ssh-keys commands in Clever Tools](/developers/doc/cli/#emails) + +## Application configuration as Clever Task + +You can also use `clever config` to set an application as a [Clever Task](/developers/doc/develop/tasks/) after its creation of get this option configuration: + +``` +clever config get task +clever config set task true +clever config set task false +clever config update --name "My new task name" --enable-task +``` + +- [Learn more about config command in Clever Tools](/developers/doc/cli/applications/configuration/) + +## How to upgrade + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install/). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2025/06-11-metabase-55.md b/content/changelog/2025/06-11-metabase-55.md new file mode 100644 index 000000000..9090c03d4 --- /dev/null +++ b/content/changelog/2025/06-11-metabase-55.md @@ -0,0 +1,33 @@ +--- +title: "Metabase 55 is available" +date: 2025-06-11 +tags: + - addons + - metabase +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Faster, with more features +excludeSearch: true +--- + +The `x.55` branch of Metabase is now available on Clever Cloud. It brings a new visualizer, faster and easier to use, database routing, the new search algorithm as default and many more features. To update, just set `CC_METABASE_VERSION` of the add-on's Java application to `0.55` for the community edition or `1.55` for the enterprise edition (EE). + +You can also use [the new Clever Tools commands](/developers/doc/cli/operators/), introduced in `3.13.0` release: + +```bash +clever features enable operators + +clever metabase version check yourMetabaseNameOrId +clever metabase version update yourMetabaseNameOrId +clever metabase version update yourMetabaseNameOrId 0.55 +``` + +- [Learn more about Metabase 55](https://www.metabase.com/releases/metabase-55) +- [Learn more about Metabase on Clever Cloud](/developers/doc/addons/metabase/) + +{{< youtube id="0wKoZR0zJ6Q" >}} diff --git a/content/changelog/2025/06-17-images-update.md b/content/changelog/2025/06-17-images-update.md new file mode 100644 index 000000000..f874042e7 --- /dev/null +++ b/content/changelog/2025/06-17-images-update.md @@ -0,0 +1,44 @@ +--- +title: "Images update: FrankenPHP 1.7, Docker buildx" +date: 2025-06-17 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: And more new features for runtimes to come… +excludeSearch: true +--- + +We updated all our images. Deployment is in progress for all our users. + +* **Common:** + * Linux kernel 6.14.11 + * Mise 2025.6.4 +* **Docker:** + * Update to 28.2.2 + * Buildx 0.24.0 +* **FrankenPHP:** + * Update to 1.7.0 (PHP 8.4.8) +* **Go:** + * Update to 1.24.4 +* **Node.js:** + * Bun 1.2.16 +* **Python:** + * Update to 3.13.4 + * Update to 3.12.11 + * Update to 3.11.13 + * Update to 3.10.18 + * Update to 3.9.23 + * uv 0.7.13 + +## Other changes + +- Multiple fixes for logs +- [Varnish support](/developers/doc/administrate/cache/) for FrankenPHP, [upcoming Linux, Static and V runtimes](https://github.com/CleverCloud/Community/discussions/66) +- Astro, Docusaurus, MkDocs autobuild support for [upcoming static runtime](https://github.com/CleverCloud/Community/discussions/66) +- `-x -race` flags are added to `go install` if `CC_TROUBLESHOOT` is set to `true` in Go runtime +- `proxy_fcgi` is now default in PHP with Apache if `CC_CGI_IMPLEMENTATION` environment variable is not set +- Try `buildx` support in Docker by setting `CC_DOCKER_BUILDX` to `true` (it will become the default in some weeks) diff --git a/content/changelog/2025/06-20-keycloak-26.2.5.md b/content/changelog/2025/06-20-keycloak-26.2.5.md new file mode 100644 index 000000000..e2f98471f --- /dev/null +++ b/content/changelog/2025/06-20-keycloak-26.2.5.md @@ -0,0 +1,30 @@ +--- +title: "Keycloak 26.2.5 is available, with two new plugins" +date: 2025-06-20 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: bug fix release +excludeSearch: true +--- + +The release `26.2.5` of Keycloak is available on Clever Cloud which [fixes](https://github.com/keycloak/keycloak/releases/26.2.5) some bugs. Starting with this release, we provide Keycloak with [2fa-email-authenticator](https://github.com/please-openit/keycloak-2fa-email-authenticator) and [Limit user agents](https://github.com/please-openit/keycloak-authenticator-limit-user-agents) plugins. + +To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.2.5` and rebuild it. You can also use [the new Clever Tools commands](/developers/doc/cli/operators/), introduced in `3.13.0` release: + +```bash +clever features enable operators + +clever keycloak version check yourKeycloakNameOrId +clever keycloak version update yourKeycloakNameOrId +clever keycloak version update yourKeycloakNameOrId 26.2.5 +``` + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak) diff --git a/content/changelog/2025/07-01-images-update.md b/content/changelog/2025/07-01-images-update.md new file mode 100644 index 000000000..08cf973b6 --- /dev/null +++ b/content/changelog/2025/07-01-images-update.md @@ -0,0 +1,60 @@ +--- +title: "Images update: easier Varnish, Redirection.io, uv native support" +date: 2025-07-01 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Last mile before new runtimes public release +excludeSearch: true +--- + +We updated all our images. Deployment is in progress for all our users. + +* **Common:** + * Linux kernel 6.14.11 + * Mise 2025.6.6 + * SQLite 3.50.1 +* **Docker:** + * Update to 28.3 + * Buildx 0.25.0 +* **Node.js:** + * Update to 22.17.0 + * Bun 1.2.17 +* **Python:** + * Update to 3.13.5 + * uv 0.7.17 +* **Rust:** + * Update to 1.88.0 +* **V:** + * Update to 0.4.11 + +## Linux, Static and V runtimes + +- Better V dependencies management +- Better support of Astro in the `static` auto build feature +- `static` runtime auto-build supports Nuxt.js, Storybook, Vitepress and Zola +- If a Mise `build` or `run` task is defined, it's used in build/run phase in `linux` runtime + +These runtimes are in early access, let us know what you think about it, [your suggestions and feedback are welcome](https://github.com/CleverCloud/Community/discussions/66). + +## Preliminary native uv support in Python applications + +`uv` is now natively supported for deploying Python applications on Clever Cloud. Using `uv` bypass all the legacy Python deployment process. There is no mandatory `nginx` server and your application should listen on the port `8080`. Thus, you can use it with Varnish and easy to configure services such as Redirection.io. We'll progressively enhance the `uv` experience on Clever Cloud. + +`uv` native support is still preliminary, let us know what you think about it, [your suggestions and feedback are welcome](https://github.com/CleverCloud/Community/discussions/67). + +- [Learn more about uv](https://docs.astral.sh/uv/) +- [Learn more about Python on Clever Cloud](/developers/doc/applications/python) +- [A ready to deploy Python with uv application](https://github.com/CleverCloud/python-fastapi-uv-example) + +## Other changes + +- `CC_GIT_FULL_CLONE=false` enables shallow cloning (`--depth 1`), it will become the default in some weeks +- `CC_VARNISH_FILE` allows to set a custom location for `varnish.vcl`, relative to your application (for example `/varnish.vcl`) +- Port auto-configuration for `frankenphp` and `static` when a Varnish file is present or set with `CC_VARNISH_FILE` +- Port auto-configuration for `frankenphp` and `static` when [Redirection.io is enabled](/developers/doc/reference/reference-environment-variables/#redirectionio-support) +- You can now disable Mise package manager by setting `CC_DISABLE_MISE` to `true` diff --git a/content/changelog/2025/07-01-ionos-london-region.md b/content/changelog/2025/07-01-ionos-london-region.md new file mode 100644 index 000000000..12ca695f0 --- /dev/null +++ b/content/changelog/2025/07-01-ionos-london-region.md @@ -0,0 +1,21 @@ +--- +title: New London region, based on Ionos infrastructure +date: 2025-07-01 +tags: + - addons + - applications + - platform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: A new European partner, more choices for our customers +excludeSearch: true +--- + +You can now deploy your applications and add-ons in London, England. This region uses `ldn` code within our [API](/developers/api), [Clever Tools](/developers/doc/cli) and various integrations. You can choose it for new or existing services from the [Console](https://console.clever-cloud.com), just adapt your domain configuration. + +The London region was created in collaboration with a new European partner, [Ionos](https://www.ionos.co.uk/). Our teams have installed and are operating Clever Cloud within its infrastructure in order to offer you this new service. + +- [Learn more about our infrastructure and partners](/infrastructure/) +- [Learn more about domain configuration on Clever Cloud](/developers/doc/administrate/domain-names/#configuring-domain-names-by-region) diff --git a/content/changelog/2025/07-02-js-client-11.0.md b/content/changelog/2025/07-02-js-client-11.0.md new file mode 100644 index 000000000..86d04dfd1 --- /dev/null +++ b/content/changelog/2025/07-02-js-client-11.0.md @@ -0,0 +1,18 @@ +--- +title: 'JS Client 11.0 is available' +date: 2025-07-02 +tags: + - client + - javascript +authors: + - name: Pierre De Soyres + link: https://github.com/pdesoyres-cc + image: https://github.com/pdesoyres-cc.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Some cleaning before big changes +excludeSearch: true +--- + +[Clever Cloud JS client 11.0](https://github.com/CleverCloud/clever-client.js/blob/master/CHANGELOG.md#1101-2025-06-30) is available. It adds API call analysis scripts, uses native WebSocket support and OAuth plaintext instead of HMAC512. Thus, we removed `oauth-1.0a` dependency. Note that if you use the event API, you need Node.js 21+. diff --git a/content/changelog/2025/07-02-terraform-0.10.md b/content/changelog/2025/07-02-terraform-0.10.md new file mode 100644 index 000000000..60b128904 --- /dev/null +++ b/content/changelog/2025/07-02-terraform-0.10.md @@ -0,0 +1,20 @@ +--- +title: Terraform provider 0.10.0 is available +description: Network Groups and Pulsar support, PostgreSQL add-on version +date: 2025-07-02 +tags: + - addons + - terraform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +excludeSearch: true +--- + +The [0.10.0 release](https://github.com/CleverCloud/terraform-provider-clevercloud/releases/tag/v0.10.0) of the Clever Cloud Terraform provider is available. It fixes some bugs, introduces support for [Network Groups](/developers/doc/develop/network-groups/) and [Pulsar](/developers/doc/addons/pulsar/). You can set a version for a [PostgreSQL add-on](/developers/doc/addons/postgresql/). + +* Learn more about [our Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs) diff --git a/content/changelog/2025/07-04-linux-static-v-runtimes.md b/content/changelog/2025/07-04-linux-static-v-runtimes.md new file mode 100644 index 000000000..a112c6535 --- /dev/null +++ b/content/changelog/2025/07-04-linux-static-v-runtimes.md @@ -0,0 +1,26 @@ +--- +title: "New runtimes: Linux, Static and V" +description: Use it, help us to improve +date: 2025-07-04 +tags: + - images + - linux + - static + - v +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +excludeSearch: true +--- + +You can now deploy your applications using the new `linux`, `static` and `v` runtimes on Clever Cloud: +- `linux` is a general purpose runtime that supports any language, and fully takes advantage of the [Mise package manager](https://mise.jdx.dev/) +- `static` is a lightweight runtime for static sites, with auto-build for many static site generators (SSG) +- `v` is a runtime for applications written in the [V programming language](https://vlang.io/) + +As they are new runtimes, help us improve it by reporting any issue or suggestion on the [Clever Cloud Community](https://github.com/CleverCloud/Community/discussions/categories/paas-runtimes). + +* [Learn more about the Linux runtime](/developers/doc/applications/linux/) +* [Learn more about the Static runtime](/developers/doc/applications/static/) +* [Learn more about the V runtime](/developers/doc/applications/v/) diff --git a/content/changelog/2025/07-08-terraform-0.11.md b/content/changelog/2025/07-08-terraform-0.11.md new file mode 100644 index 000000000..616a8f245 --- /dev/null +++ b/content/changelog/2025/07-08-terraform-0.11.md @@ -0,0 +1,20 @@ +--- +title: Terraform provider 0.11.0 is available +description: Disable PostgreSQL backups +date: 2025-07-08 +tags: + - addons + - terraform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +excludeSearch: true +--- + +The [0.11.0 release](https://github.com/CleverCloud/terraform-provider-clevercloud/releases/tag/v0.11.0) of the Clever Cloud Terraform provider is available. It allows disabling backups for a [PostgreSQL add-on](/developers/doc/addons/postgresql/). + +* Learn more about [our Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs) diff --git a/content/changelog/2025/07-09-images-update.md b/content/changelog/2025/07-09-images-update.md new file mode 100644 index 000000000..ddea8ce80 --- /dev/null +++ b/content/changelog/2025/07-09-images-update.md @@ -0,0 +1,50 @@ +--- +title: "Images update: FrankenPHP 1.8, Java 24, Storybook auto-build" +date: 2025-07-09 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Welcome Java in the unified image! +excludeSearch: true +--- + +We updated all our images, except PHP with Apache. Deployment is in progress for all our users. + +* **Common:** + * Linux kernel 6.15.5 + * Hugo 0.148.0 + * Mise 2025.7.1 + * SQLite 3.50.2 + * Redis 8.0.3 +* **Docker:** + * Update to 28.3.1 +* **FrankenPHP:** + * Update to 1.8.0 (PHP 8.4.10, Caddy 2.10.0) +* **Java:** + * Now part of the unified image + * Java 24 support + * GraalVM CE 23.0.2 (Java 17) + * GraalVM CE 23.1.2 (Java 21) + * Gradle 8.14.3 + * Maven 3.9.10 +* **Node.js:** + * Bun 1.2.18 +* **Python:** + * uv 0.7.19 + +## FrankenPHP, Linux, Static and V runtimes + +- You can define `build` and `run` commands with `build:` and `run:` targets in a `Makefile` in `linux` runtime +- You can now set `CC_STATIC_AUTOBUILD_OUTDIR` in `static` runtime to specify the output directory for auto-build +- `v install` command is executed in the build phase if a `v.mod` file is present +- Storybook auto-build is now supported in the `static` runtime +- Easier `uv` activation in the `python` runtime +- `APP_FOLDER` support in new runtimes + +## Other changes + +- Authentication to a npm registry is now also supported through the `CC_NPM_BASIC_AUTH` environment variable diff --git a/content/changelog/2025/07-10-redis-8.0.3.md b/content/changelog/2025/07-10-redis-8.0.3.md new file mode 100644 index 000000000..97bc54097 --- /dev/null +++ b/content/changelog/2025/07-10-redis-8.0.3.md @@ -0,0 +1,18 @@ +--- +title: Redis 8.0.3 is available, with JSON module +date: 2025-07-10 +tags: + - addons + - redis +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Have fun with structured data +excludeSearch: true +--- + +We updated Redis™ to [release 8.0.3](https://github.com/redis/redis/releases/tag/8.0.3) which fixes [CVE-2025-32023](https://nvd.nist.gov/vuln/detail/CVE-2025-32023) and [CVE-2025-48367](https://nvd.nist.gov/vuln/detail/CVE-2025-48367). It's available for add-ons creation and migration. Starting this release, Redis™ on Clever Cloud comes with the JSON module enabled. + +- [Learn more about Redis™ on Clever Cloud](/developers/doc/addons/redis/) +- [Learn more about Redis™ JSON data type](https://redis.io/docs/latest/develop/data-types/json/) diff --git a/content/changelog/2025/07-17-request-flow.md b/content/changelog/2025/07-17-request-flow.md new file mode 100644 index 000000000..6c1135161 --- /dev/null +++ b/content/changelog/2025/07-17-request-flow.md @@ -0,0 +1,53 @@ +--- +title: 'Introducing Request Flow: use Redirection.io, Varnish, reverse proxy with no effort' +date: 2025-07-17 +tags: + - runtimes + - configuration +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: Ease your reverse proxy configuration more and more +excludeSearch: true +--- + +Clever Cloud exists to ease developers' life. For many years, you can use [Varnish in front of your application](/developers/doc/administrate/cache/) just by adding a `varnish.vcl` file in your repository. For some months, you can also use [Redirection.io](/developers/doc/reference/reference-environment-variables/#use-redirectionio-as-a-proxy) as a reverse proxy to handle redirects, rewrites, and more. In our latest release, we've gone a step further with Request Flow, available in new runtimes first : + +- `frankenphp` +- `linux` +- `python` with `uv` +- `static` +- `v` + +## Easier Redirection.io and Varnish activation + +First, we've removed some barriers to use Redirection.io and Varnish: +- To setup Varnish add a `clevercloud/varnish.vcl` file or define it with `CC_VARNISH_FILE` environment variable +- To setup Redirection.io, `CC_REDIRECTIONIO_PROJECT_KEY` is now the only required environment variable + +## Request Flow: automatic port configuration, easy ordering + +In recent runtimes where Clever Cloud manage the port configuration (`frankenphp`, `static`), nothing else is needed. By default, Clever Cloud will configure the reverse proxy to listen on port `8080` and redirect to port `9000`. So in runtimes where the user controls the port configuration, the application must listen on port `9000` once Redirection.io or Varnish is activated. + +If both are activated: +- Varnish is exposed first: listens on port `8080`, forward to Redirection.io on port `8081` +- Redirection.io listens on port `8081`, forward to the application on port `9000` + +If you prefer to invert the order and expose Redirection.io first, set `CC_REQUEST_FLOW` environment variable to `redirectionio,varnish`. + +## Use any reverse proxy with Request Flow + +Last but not least, you can use any other middleware in the Request Flow. Just add `custom` value in the `CC_REQUEST_FLOW` chain and ports will be automatically configured accordingly. For example, if you set `CC_REQUEST_FLOW=redirectionio,custom,varnish`: + +- Redirection.io listens on port `8080`, forward to custom middleware on port `8081` +- Custom middleware must listen on port `8081`, forward to Varnish on port `8082` +- Varnish listens on port `8082`, forward to the application on port `9000` + +You can define the custom middleware command to start with `CC_REQUEST_FLOW_CUSTOM` environment variable, for example: + +```bash +CC_REQUEST_FLOW_CUSTOM="./custom_reverse_proxy --listen @@LISTEN_PORT@@ --forward @@FORWARD_PORT@@" +``` + +As Request Flow is a new feature on Clever Cloud, feel free to [give us feedback](https://github.com/CleverCloud/Community/discussions/categories/paas-runtimes). diff --git a/content/changelog/2025/07-28-keycloak-metabase-otoroshi-version-creation.md b/content/changelog/2025/07-28-keycloak-metabase-otoroshi-version-creation.md new file mode 100644 index 000000000..71965ffda --- /dev/null +++ b/content/changelog/2025/07-28-keycloak-metabase-otoroshi-version-creation.md @@ -0,0 +1,24 @@ +--- +title: Set Keycloak, Metabase and Otoroshi version at creation +description: More flexibility, and soon a great dashboard +date: 2025-07-28 +tags: + - operators + - version +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +excludeSearch: true +--- + +You can now set the version of Keycloak, Metabase and Otoroshi at creation time, from a list of supported and tested releases. It works from the [Clever Cloud Console](https://console.clever-cloud.com/), [API](/developers/api) and [Clever Tools](/developers/doc/cli). For example: + +```bash +clever addon create keycloak --addon-version 26.2.5 myKeycloak +``` + +If you don't provide a valid version, supported values are printed in the error message. diff --git a/content/changelog/2025/07-29-clever-tools-3.14.md b/content/changelog/2025/07-29-clever-tools-3.14.md new file mode 100644 index 000000000..4e0a921b4 --- /dev/null +++ b/content/changelog/2025/07-29-clever-tools-3.14.md @@ -0,0 +1,36 @@ +--- +date: 2025-07-29 +title: 'Clever Tools 3.14: call it with npx' +tags: + - clever-tools + - cli +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Hubert Sablonnière + link: https://github.com/hsablonniere + image: https://github.com/hsablonniere.png?size=40 +description: One-off usages are now simpler +excludeSearch: true +--- + +[Clever Tools 3.14](https://github.com/CleverCloud/clever-tools/releases/tag/3.14.0) is available. It includes some bug fixes for operators options and `service` command. It also introduces `clever-tools` as an available binary after installation. + +This allows you to use Clever Tools directly with `npx` or `npm exec`, which is useful in scripts or CI/CD pipelines: + +```bash +# Set/Export CLEVER_TOKEN and CLEVER_SECRET to login with a given account +# --yes is used to skip the interactive prompts +npx --yes clever-tools@latest version +npm exec -- clever-tools@3.14 profile --format json +``` + +## How to upgrade + +To upgrade Clever Tools, [use your favorite package manager](/developers/doc/cli/install/). For example with `npm`: + +``` +npm update -g clever-tools +clever version +``` diff --git a/content/changelog/2025/07-29-images-update.md b/content/changelog/2025/07-29-images-update.md new file mode 100644 index 000000000..f4c22b462 --- /dev/null +++ b/content/changelog/2025/07-29-images-update.md @@ -0,0 +1,54 @@ +--- +title: "Images update: FrankenPHP 1.9, Static Web Server 2.38, uv 0.8" +date: 2025-07-29 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: And soon native pnpm, yarn-berry support! +excludeSearch: true +--- + +We updated all our images, except Node.js & Bun. Deployment is in progress for all our users. + +* **Common:** + * Linux kernel 6.15.8 + * Mise 2025.7.29 + * Tailscale 1.86.0 +* **Docker:** + * Update to 28.3.2 + * Buildx 0.26.1 +* **Erlang:** + * Update to 27.3.4.2 + * Update to 28.0.2 +* **Go:** + * Update to 1.24.5 +* **Java:** + * Update to 8.0.462 + * Update to 11.0.28 + * Update to 17.0.16 + * Update to 21.0.8 + * Update to 24.0.2 + * Maven 3.9.11 +* **FrankenPHP:** + * Update to 1.9.0 (PHP 8.4.10, Caddy v2.10.0) +* **PHP:** + * Update to 8.1.33 + * Update to 8.2.29 + * Update to 8.3.23 + * Update to 8.4.10 + * Apache 2.4.64 + * Composer 2.8.10 +* **Python:** + * uv 0.8.3 +* **Ruby:** + * Update to 3.2.9 + * Update to 3.3.9 + * Update to 3.4.5 +* **Static:** + * Hugo 0.148.2 + * Static Web Server 2.38.0 + * Zola 0.21.0 diff --git a/content/changelog/2025/07-29-terraform-1.0.md b/content/changelog/2025/07-29-terraform-1.0.md new file mode 100644 index 000000000..f875653ba --- /dev/null +++ b/content/changelog/2025/07-29-terraform-1.0.md @@ -0,0 +1,20 @@ +--- +title: Terraform provider 1.0.0 is available +description: Rust and real IDs +date: 2025-07-29 +tags: + - addons + - terraform +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 + - name: Rémi Collignon-Ducret + link: https://github.com/miton18 + image: https://github.com/miton18.png?size=40 +excludeSearch: true +--- + +The [1.0.0 release](https://github.com/CleverCloud/terraform-provider-clevercloud/releases/tag/v1.0.0) of the Clever Cloud Terraform provider is available. It fixes some bugs, supports [Rust runtime](/developers/doc/applications/rust/) and uses real ID instead of add-on ID for add-ons. + +* Learn more about [our Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs) diff --git a/content/changelog/2025/07-31-keycloak-26.3.2.md b/content/changelog/2025/07-31-keycloak-26.3.2.md new file mode 100644 index 000000000..e88d44a2e --- /dev/null +++ b/content/changelog/2025/07-31-keycloak-26.3.2.md @@ -0,0 +1,30 @@ +--- +title: Keycloak 26.3.2 is available, including optimizations and new features +date: 2025-07-31 +tags: + - addons + - keycloak +authors: + - name: Sébastien Allemand + link: https://github.com/allemas + image: https://github.com/allemas.png?size=40 + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: with lots of new features +excludeSearch: true +--- + +[The release 26.3.2](https://github.com/keycloak/keycloak/releases/26.3.2) of Keycloak is available on Clever Cloud. The `26.3` branch [brings](https://github.com/keycloak/keycloak/releases/26.3.0) lots of new features, enhancements and bug fixes. We fine tuned it, adding a conditional IP range-based authentication and dynamic cache sizing that automatically scales based on instance size and user count in database. + +To update, just set `CC_KEYCLOAK_VERSION` of the add-on's Java application to `26.3.2` and rebuild it. You can also use [the new Clever Tools commands](/developers/doc/cli/operators/), introduced in `3.13.0` release: + +```bash +clever features enable operators + +clever keycloak version check yourKeycloakNameOrId +clever keycloak version update yourKeycloakNameOrId +clever keycloak version update yourKeycloakNameOrId 26.3.2 +``` + +- [Learn more about Keycloak on Clever Cloud](/developers/doc/addons/keycloak) diff --git a/content/changelog/2025/08-07-images-update.md b/content/changelog/2025/08-07-images-update.md new file mode 100644 index 000000000..77a2458a8 --- /dev/null +++ b/content/changelog/2025/08-07-images-update.md @@ -0,0 +1,32 @@ +--- +title: "Images update: .Net 9.0, Mise 2025.8" +date: 2025-08-07 +tags: + - images + - update +authors: + - name: David Legrand + link: https://github.com/davlgd + image: https://github.com/davlgd.png?size=40 +description: And a great surprise for Node.js users, stay tuned! +excludeSearch: true +--- + +We updated all our images. Deployment is in progress for all our users. + +* **Common:** + * Linux kernel 6.15.9 + * Mise 2025.8.4 + * SQLite 3.50.3 + * Tailscale 1.86.2 +* **.Net:** + * Update to 9.0.108 +* **Docker:** + * Update to 28.3.3 +* **Node.js & Bun:** + * Bun 1.2.19 + * Node.js 22.18.0 (npm 10.9.3) +* **Python:** + * uv 0.8.4 + +In the [.Net runtime](/developers/doc/applications/dotnet), you can now use `CC_DOTNET_VERSION=9.0`. diff --git a/content/changelog/_index.md b/content/changelog/_index.md new file mode 100644 index 000000000..dea91204f --- /dev/null +++ b/content/changelog/_index.md @@ -0,0 +1,17 @@ +--- +title: Changelog +width: normal +description: Additions and changes to the Clever Cloud platform +aliases: +- /changelog/2026 +- /changelog/2025 +- /changelog/2024 +- /changelog/2023 +--- + +Additions and changes to the Clever Cloud platform. + +{{< hextra/hero-badge link="/developers/changelog/index.xml" style="margin:10px 0 0 0">}} + Feed + {{< icon name="rss" attributes="height=14" >}} +{{< /hextra/hero-badge >}} diff --git a/content/doc/_index.md b/content/doc/_index.md new file mode 100644 index 000000000..644dd6ac0 --- /dev/null +++ b/content/doc/_index.md @@ -0,0 +1,65 @@ +--- +weight: 2 +title: Clever Cloud Documentation +type: docs +comments: false +linkTitle: Documentation +aliases: +- /clever-cloud-overview +- /doc/clever +- /doc/en +- /doc/get +- /doc/site +- /doc. +- /doci +- /docs +- /documentation +- /documentation-old +--- + +{{< hextra/hero-subtitle >}} + Everything you need to know for your Clever Cloud journey +{{< /hextra/hero-subtitle >}} + +{{< cards >}} + {{< card link="/developers/doc/quickstart" title="Getting Started" subtitle="Get ready to deploy and app in 5 minutes" icon="arrow-circle-right" >}} + {{< card link="/developers/doc/develop" title="Develop" subtitle="Best practices on Cloud deployments, sheduling jobs, etc." icon="code" >}} + {{< card link="/developers/doc/administrate" title="Administrate" subtitle="Access metrics, logs, manage domains, set up scalability…" icon="library" >}} + {{< card link="/developers/doc/applications" title="Deploy" subtitle="Deploy any app on Clever Cloud." icon="rocket-launch" >}} + {{< card link="/developers/doc/addons" title="Connect an add-on" subtitle="Connect a managed database and set up cloud storage." icon="plug" >}} + {{< card link="/developers/doc/find-help" title="Find help" subtitle="Lost? See how to get help." icon="support" >}} + {{< card link="/developers/doc/marketplace" title="Marketplace" subtitle="Integrate your own service on Clever Cloud" icon="puzzle" >}} + {{< card link="/developers/doc/cli" title="Clever Tools CLI" subtitle="Deploy and manage your applications and dependencies from your terminal." icon="command-line" >}} + {{< card link="/developers/doc/ci-cd" title="CI/CD" subtitle="Deploy to Clever Cloud from GitHub or GitLab." icon="gitlab" >}} + + {{< card link="/developers/doc/reference" title="References" subtitle="List of environment variables your can use on Clever Clever Cloud, common configuration an all instances… " icon="collection" >}} + {{< card link="/developers/doc/account" title="User Account" subtitle="Set up your account, collaborate and manage permissions." icon="user-circle" >}} + {{< card link="/developers/doc/billing" title="Billing" subtitle="Find invoices, analyse consumption and understand pricing." icon="credit-card" >}} + {{< card link="/developers/doc/contribute" title="Contribute" subtitle="See how to contribute to this documentation." icon="pencil-alt" >}} +{{< /cards >}} + +{{< hextra/hero-subtitle style="margin:20px 0">}} + See our step by step tutorials +{{< /hextra/hero-subtitle >}} + +{{< hextra/feature-grid >}} + {{< hextra/feature-card + title="Find your framework" + subtitle="Deploy your favorite framework with our step by step guides." + link="/developers/guides" + style="background: radial-gradient(ellipse at 50% 80%,rgba(203, 28, 66, 0.15),hsla(0,0%,100%,0));" + >}} + {{< hextra/feature-card + title="Starter tutorials" + subtitle="Make a starter app and deploy it on Clever Cloud." + link="/developers/guides/#starter-tutorials" + style="background: radial-gradient(ellipse at 50% 80%,rgba(58, 56, 113, 0.15),hsla(0,0%,100%,0));" + >}} + {{< hextra/feature-card + title="Add-ons guides" + subtitle="Take your dependencies management to the next level." + link="/developers/guides/#level-up-your-add-ons" + style="background: radial-gradient(ellipse at 50% 80%,rgba(165, 16, 80, 0.15),hsla(0,0%,100%,0));" + >}} + +{{< /hextra/feature-grid >}} diff --git a/content/doc/account/_index.md b/content/doc/account/_index.md new file mode 100644 index 000000000..45844df59 --- /dev/null +++ b/content/doc/account/_index.md @@ -0,0 +1,19 @@ +--- +weight: 11 +type: docs +title: User Account +description: Learn how to manage your account on Clever Cloud. Discover detailed instructions for account creation, organisation administration, and more in our PaaS platform. +comments: false +aliases: +- /account +--- + +{{< cards >}} + {{< card link="/developers/doc/account/create-account" title="Create an account" icon="user-circle" >}} + {{< card link="/developers/doc/account/manage-account" title="Manage your account" icon="wrench-screwdriver" >}} + {{< card link="/developers/doc/account/administrate-organisation" title="Manage an organisation" icon="building-library" >}} + {{< card link="/developers/doc/account/organisations" title="Roles and organisations" icon="user-group" >}} + {{< card link="/developers/doc/account/notifications" title="Manage notifications" icon="bell" >}} + {{< card link="/developers/doc/account/ssh-keys-management" title="Manage SSH keys" icon="key" >}} + {{< card link="/developers/doc/account/delete-account" title="Delete an account" icon="trash" >}} +{{< /cards >}} diff --git a/content/doc/account/administrate-organisation.md b/content/doc/account/administrate-organisation.md new file mode 100644 index 000000000..d03f254e0 --- /dev/null +++ b/content/doc/account/administrate-organisation.md @@ -0,0 +1,40 @@ +--- +type: docs +weight: 3 +title: Manage an organisation +description: Learn how to effectively administrate organisations on your Clever Cloud account. This guide provides step-by-step instructions for managing members, payments, invoices, and settings in our PaaS environment. +tags: +- account +keywords: +- preferences +- organisation +aliases: +- /doc/account/administrate-organization +--- + +After you create an account, your account is tied to a first organisation named as 'Personal Space'. You can use the Personal Space for individual projects or personal use, but only you as a user can access it. + +To collaborate with others, manage team access, or handle separate billing for a group, you need to create an organisation. + +## Create an organisation + +In the Clever Cloud Web Console, select **Add an organisation** in the left menu. + +Give it a name, description, specify if it's a company and add billing information. + +## Administrate an organisation + +By clicking on you application name, a new left menu open. + +- **Overview**: Simple metrics about your applications within this organisation +- **Information**: See and edit organisation's name, description, billing address and image. That also is where you can delete your organisation. +- **Members**: Manage team members. Team members must have a Clever Cloud account. On this page you can add and remove team members. You can also edit their roles to manage their permissions. +- **Shared software**: It's a section displaying third party software, like [Heptapod](/developers/doc/addons/heptapod/) +- **Payment methods**: Manage provisioning of your organisation, manage credit cards and add here potential discount codes or coupons. +- **Invoices**: See your recent invoices. +- **Notifications**: Manage email notifications and web hooks for team members. +- **Consumption**: See metrics about your organisation's consumptions. + +## Delete an organisation + +In the **Information** page, click the *remove this organisation* button. You're then prompted to enter the name of the organisation to confirm the organisation deletion. diff --git a/content/doc/account/create-account.md b/content/doc/account/create-account.md new file mode 100644 index 000000000..863c3f9d0 --- /dev/null +++ b/content/doc/account/create-account.md @@ -0,0 +1,48 @@ +--- +type: docs +weight: 1 +title: Create an Account +description: Start your journey with Clever Cloud by creating an account. Follow this easy guide to sign up and access a wide range of cloud computing resources on our PaaS platform. +tags: +- account +keywords: +- profile +- preferences +- user +- creation +aliases: +- /doc/account-setup +- /doc/getting-started/authentication +--- + + +The API of Clever Cloud uses OAuth 1 to perform authentication actions. +There are two ways to sign up to Clever Cloud: **email** or **GitHub login**. + +## Email + +This kind of auth requires a valid and non-temporary disposable e-mail, and a password having at least 6 characters. + +Do not forget to validate your email by clicking the link you will receive. + +## GitHub + +The GitHub signup allows you to create an account or link your existing one to GitHub, in one click. + +This process asks the following permissions: + +* Read your Public Key +* Read User Repositories + +The "repository permission" is used to deploy your GitHub apps directly to Clever Cloud, with a simple step. + +If you need to give access to Clever Cloud's API to a specific GitHub organisation, you +can [do it here](https://github.com/settings/connections/applications/d96bd8fd996d2ca783cc). + +Go to the [Clever Cloud Console](https://console.clever-cloud.com/) and select the method you prefer. + +### 🔐 Two Factor Authentication (2FA) + +Clever Cloud supports 2FA. You can enable it here: + +Please, backup your recovery codes, we won't be able to restore access to your account if you lose access to your regular codes. diff --git a/content/doc/account/delete-account.md b/content/doc/account/delete-account.md new file mode 100644 index 000000000..9e24d3e77 --- /dev/null +++ b/content/doc/account/delete-account.md @@ -0,0 +1,22 @@ +--- +type: docs +weight: 7 +title: Delete an account +description: Need to delete your Clever Cloud account? Our guide walks you through the process, ensuring a smooth and secure account termination on our PaaS service. +tags: +- account +keywords: +- profile +- preferences +- user +- delete +--- + +To delete your account: + +1. Open the Clever Cloud Web Console. +2. Select **Profile** in the bottom left menu. +3. Select **Delete my account** in the top menu of the freshly opened page. +4. Click the red **Send me a confirmation email** button. + +You will get an email with a link you must click to confirm your account deletion. diff --git a/content/doc/account/manage-account.md b/content/doc/account/manage-account.md new file mode 100644 index 000000000..7e37bd823 --- /dev/null +++ b/content/doc/account/manage-account.md @@ -0,0 +1,23 @@ +--- +type: docs +weight: 2 +title: Manage your account +description: Master the account management on Clever Cloud. This section covers everything from updating personal information to modifying email,SSH keys or tokens on our PaaS platform. +tags: +- account +keywords: +- profile +- preferences +- user +--- + +In the Clever Cloud Web Console, select **Profile** in the bottom left menu. + +You see several menu entries. + +- **Information**: on that page you can edit your name, address, phone number, profile picture, manage the link between your Clever Cloud and GitHub account and select the language of your Clever Cloud web console. +- **Emails**: manage your linked email addresses. +- **Authentication**: Change your password, enable or turn off Two Factor Authentication. +- **SSH keys**: add or remove your SSH keys, manage your GitHub SSH keys if you have linked your GitHub account. +- **Oauth tokens**: See and revoke your access tokens +- **Delete my account**: Delete your Clever Cloud account diff --git a/content/doc/account/notifications.md b/content/doc/account/notifications.md new file mode 100644 index 000000000..a324cb5c4 --- /dev/null +++ b/content/doc/account/notifications.md @@ -0,0 +1,89 @@ +--- +type: docs +title: Notifications +weight: 5 +description: Learn how to customize notifications for account and deployment activity on Clever Cloud, service updates, and more on our PaaS service +tags: +- admin-console +keywords: +- notification +- webhook +- e-mail +- email +- slack +- flowdock +aliases: +- /doc/admin-console/notifications +--- + +The *Notifications* service allows you to choose the events of interest to you +and decide where to send corresponding notifications. + +## E-mails + +Historically and by default, deployment result e-mails (deployment succeeded or +failed) were always sent to the owners of an application, namely the user +themselves or the organisation's members. + +To disable the deployment result e-mails or restrict it to only some applications: + +1. Go in **organisation Manager** > **Notifications** panel. +2. Delete the hook named *Default deployment result e-mails*. +3. Add a new one. +4. Set it to your liking. + +In the future, this service will also handle credits warning notifications and +others to come. You will be able to choose wether or not to receive an e-mail +and/or for these events to be forwarded to a web service via a *webhook*. + +## Webhooks + +From Wikipedia: + +> A webhook in web development is a method of augmenting or altering the +> behavior of a web page, or web application, with custom callbacks. These +> callbacks may be maintained, modified, and managed by third-party users and +> developers who may not necessarily be affiliated with the originating website +> or application. + +In practical terms, this means that you can choose to receive all deployment +result events on an endpoint of your application without having to listen to +all events via the Websocket API. No more lost events and having to reconnect +to the websocket if and when it fails. + +To create a webhook stay on the **Notifications** panel: + +1. Click on **Webhooks** button at the top of the Notifications window. +2. Add a new one. +3. Choose the URL which will receive the data through a *POST* request and the format it will be sent as. + +As of now, you can choose between 3 formats: *raw*, *slack* and *flowdock*. The *raw* format is the Clever Cloud internal representation of events, it is identical to events sent by the Websocket API. *Slack* and *Flowdock* formats are to be used with the corresponding services. + +You can also choose which events you want and restrict notifications to a list +of applications and add-ons. + +### Example: Slack deployment results Webhook + +First, you will have to create the *Incoming WebHooks* integration on Slack: + +Let's go to the [custom integrations +page](https://slack.com/apps/manage/custom-integrations), once there go to +*Incoming WebHooks*. + +You will find an *Add Configuration* button on the left which will take you to +the page where you need to configure the integration. You just need to select +the channel where you want the notifications to be posted, then it will show +you the Webhook URL, it starts with `https://hooks.slack.com/services/`. Copy +that URL. + +Now, let's create the Webhook! + +You should already have a tab opened on the Webhook creation page; if it's not +the case, follow the *Webhooks* section above. + +There, you just need to paste the URL you copied before in the Webhook URL +field, then select *Result of deployments (success/fail)* in the *Only send +notification for these events* menu. + +You can now push your application or restart it and you will see +the result of the deployment in your Slack channel. diff --git a/content/doc/account/organisations.md b/content/doc/account/organisations.md new file mode 100644 index 000000000..6330fcb7c --- /dev/null +++ b/content/doc/account/organisations.md @@ -0,0 +1,48 @@ +--- +type: docs +title: Roles and organisations +weight: 4 +description: Discover how to manage organisations within your Clever Cloud account. This guide covers creation of organisations and roles in our PaaS platform. +tags: +- dashboard-setup +keyworkds: +- roles +- users +- accounts +- organisations +- organisations +- collaboration +aliases: +- /account/organizations +- /doc/account/organizations +- /doc/admin-console/organizations +- /doc/organizations +--- + +In order to improve team collaboration between developers, accountants, managers and admins, we have introduced organisations. Each organisation has its own billing, leaning that you can create as much as orgnanization you'd like. Most use-cases include the billing separation of private and business applications, several businesses or business units (within one company, for instance). + +Once you create an organisation, you can add collaborators and assign them [roles](#roles-and-privileges) which gives them rights. + +Each organisation have its own identifier looking like `orga_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. + +## Add an organisation + +organisation names are unique. It means that you cannot use an already used organisation name. + +In order to add an organisation, just click on "Add an organisation" in the top left sidebar. + +## Roles and privileges + +The table below describes rights assigned to roles: + +Role | Admin | Manager | Developer | Accountant | +-----|-------|---------|-----------|------------| +Add Member | ✓ | ✓ | | | +Remove Member | ✓ | ✓ | | | +Add Application | ✓ | ✓ | ✓ | | +Remove Application | ✓ | ✓ | | | +Add / Remove add-on | ✓ | ✓ | | | +Edit organisation | ✓ | ✓ | | | +Delete organisation | ✓ | | | | +Access Bills & Receive Invoices | ✓ | | | ✓ | +Access Repositories | ✓ | ✓ | ✓ | | diff --git a/content/doc/account/ssh-keys-management.md b/content/doc/account/ssh-keys-management.md new file mode 100644 index 000000000..a42f6188e --- /dev/null +++ b/content/doc/account/ssh-keys-management.md @@ -0,0 +1,199 @@ +--- +type: docs +title: SSH Keys +weight: 6 +description: Secure your PaaS deployments with SSH key management on Clever Cloud. Learn how to generate, add, and manage SSH keys for secure access to your services. +tags: +- account-setup +keywords: +- git +- deploy +- deployment +- push +- ssh +- sshkeys +- private ssh +aliases: +- /account/ssh-keys-management +- /doc/account/ssh-keys-management +- /doc/getting-started/ssh-keys +--- + +You need to add a SSH key to your Clever Cloud's account to deploy via Git. +SSH keys are used to establish a secure connection between your computer and Clever Cloud. A user can have multiple SSH keys. + +{{< callout type="warning">}} + + Accounts cannot share the same SSH key. A SSH key is used to identify the actions made by a user and must be + associated with only one account. **If a key is used by more than one account, a warning will be displayed in the console**. + +{{< /callout >}} + +## How to add your SSH key on Clever Cloud? + +{{% steps %}} + +### Generate the key + +In your Terminal, enter the following bash line: + +```bash +ssh-keygen -t ed25519 -C "your_email@youremail.com" +``` + +This command creates a new SSH key using the provided email, so that the owner of the key can be identified. + +### Save the key + +When prompted in which file you want to save the key, just press enter. +If it says that the file already exists, enter `n` for `no`. +Type `ls`, verify the presence of the file and jump to [Add your SSH key on Clever Cloud](#add-a-public-ssh-key-on-clever-cloud). + +### Enter a passphrase + +When asked, enter a passphrase: + +```bash +Generating public/private ed25519 key pair. +Enter file in which to save the key (/your_home_path/.ssh/id_ed25519): +# Now you should enter a passphrase. +Enter passphrase (empty for no passphrase): [Type a passphrase] +Enter same passphrase again: [Type passphrase again] +``` + +Which should give you something like this: + +```bash +Your identification has been saved in /your_home_path/.ssh/id_ed25519. +Your public key has been saved in /your_home_path/.ssh/id_ed25519.pub. +The key fingerprint is: +01:0e:e5:2d:ab:98:d6:17:a1:6d:f0:68:9f:d0:a2:db your_email@youremail.com +``` + +{{% /steps %}} + +## Add a FIDO/U2F SSH key + +Since [OpenSSH 8.2](https://www.openssh.com/txt/release-8.2 ), generated keys can require a security device compatible with the FIDO/U2F standards (such as Nitrokeys, Solokeys or Yubikeys) to complete the authentication process. To generate such key, plug the device to your machine and enter this command: + +```bash +ssh-keygen -t ed25519-sk -C "your_email@youremail.com" +``` + +Under macOS, you may need to install [Homebrew](https://brew.sh/), an OpenSSH version including full FIDO/U2F support, and use [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key format: + +```bash +brew install openssh +ssh-keygen -t ecdsa-sk -C "your_email@youremail.com" +``` + +{{< callout type="info" >}} + You can use options related to security devices adding them with the `-O` argument (for example `-O resident`). They're detailed in [ssh-keygen's man page](https://man.openbsd.org/ssh-keygen#FIDO_AUTHENTICATOR). +{{< /callout >}} + +## Checking of existing SSH keys + +### GitHub account and SSH key on Clever Cloud + +If your account is linked to GitHub, a panel with your GitHub SSH keys will appear in the "SSH Keys" tab. +You can add any key already present in your GitHub account by clicking on the import button next to it. + +### Finding SSH key locally + +You may already have an SSH key and so do not need to generate a new one. To check if you have one, follow these steps: + +{{< tabs items="Linux and macOS,Windows" >}} + +{{< tab >}} + +1. Whether you use macOS or Linux, open your Terminal application. +2. Run `cd ~/.ssh/` in your Terminal. +3. If the folder exists, run `ls` and check if a pair of key exists : *id_ed25519* and *id_ed25519.pub*. +Using *id_rsa* and *id_rsa.pub* is fine too. The recommendation here is to consider using *ed25519* instead. +Smaller to copy and way stronger than 2048-bit RSA keys. +If you can find them, you do not need to generate a new one, simply go to the following +"Add your key on Clever Cloud" part! + +{{< /tab >}} + +{{< tab >}}1. If you don't have it, download [Git for Windows](https://git-for-windows.GitHub.io/) and install it. +2. Run **Git Bash** (from the *Start Menu* or from the *Explorer* with the contextual menu (right click)). +3. Run `cd ~/.ssh/` in your Terminal. +4. If the folder exists, run `ls` and check if a pair of key exists : *id_ed25519* and *id_ed25519.pub* or *id_rsa* and *id_rsa.pub*. We would recommend using *ed25519* keys. Smaller to copy and way stronger than 2048-bit RSA keys. If you can find them, you do not need to generate a new one, simply go to the following "Add your key on Clever Cloud" part! +{{< /tab >}} + +{{< /tabs >}} + +## Add a public SSH key on Clever Cloud + +### From the Console + +To declare your **public SSH Key** on Clever Cloud, in the [Console](https://console.clever-cloud.com)'s left navigation bar, go in "Profile" and in the "SSH Keys" tab. + +Add the key by entering a name and the public SSH key. The key is the entire contents of the **id_[ed25519/rsa].pub** file including the `id_ed25519/ssh-rsa` part and your email. + +{{< callout type="warning">}} +Your public SSH key must be associated with only one account. +{{< /callout >}} + +If you see "*access denied*" or "*password:*" when you [push on Clever Cloud](/developers/doc/quickstart/#choose-how-to-deploy), your SSH keys may be invalid or not available on Clever Cloud. Please check that you SSH key is present and valid in your profile. + +### Through CC API or Clever cURL + +You can also add a **public SSH key** from the command line with a simple cURL request to [our API](/developers/api). The simpler way to do that is to use our CLI, [Clever Tools](https://github.com/CleverCloud/clever-tools), and its `clever curl` command once logged in: + +```bash +clever curl -X PUT -H "Content-Type: application/json" --data "\"$(cat ~/.ssh/yourkey.pub)\"" https://api.clever-cloud.com/v2/self/keys/newkeyname +``` + +## Use a private SSH key in an application + +If you want to clone a repository from a private repository, you can add a [private SSH key](/developers/doc/reference/common-configuration#private-ssh-key) to an application by creating a folder clevercloud at the root of your application and creating the file `clevercloud/ssh.json` with the following content: + +```json{filename="clevercloud/ssh.json"} +{ + "privateKeyFile": "path/to/file" +} +``` + +Of course you need to provide a valid path to a file that contains a valid key and that you will push on the Clever Cloud git remote. + +## Check your SSH configuration + +To check if your SSH key is correctly configured, you can try to run: + +```bash +ssh git@push.clever-cloud.com +``` + +The first time, you may have to type "yes" to continue. + +If you see: + +```text +git@push-par-clevercloud-customers.services.clever-cloud.com: Permission denied (publickey). +fatal: Could not read from remote repository. +Please make sure you have the correct access rights +and the repository exists. +``` + +This error can occur when your SSH agent has not be configured to use your SSH key. + +Most of the time, it is due to the presence of multiple SSH keys generated by 3rd party software, like GitHub for macOS. +To fix this you will need to configure your SSH agent. + +## Configure your SSH agent + +You can add those lines into your `~/.ssh/config` file. It tells your SSH agent which key to pick for a given hostname. Update your Clever Cloud SSH key path accordingly. + +```bash {filename= "~/.ssh/config"} +Host push-*.services.clever-cloud.com + User git + IdentityFile ~/.ssh/id_ed25519_clevercloud + IdentitiesOnly yes +``` + +{{< callout type="info" >}} +Need help about SSH keys? +Contact [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice) or you can read more about SSH Keys [on the official Git Documentation ↗](https://git-scm.com/book/en/Git-on-the-Server-Generating-Your-SSH-Public-Key). +{{< /callout >}} diff --git a/content/doc/addons/_index.md b/content/doc/addons/_index.md new file mode 100644 index 000000000..e17ee9102 --- /dev/null +++ b/content/doc/addons/_index.md @@ -0,0 +1,54 @@ +--- +type: docs +weight: 3 +title: Add-ons +description: Use add-ons on Clever Cloud +tags: +- applications +keywords: +- deploy +aliases: +- /addons +- /doc/addons/clever-cloud-addons +- /doc/administrate/addons +- /doc/clever-cloud-overview/intro-to-addons +- /doc/deploy/addon +- /doc/extend +- /doc/getting-started/dbaas +comments: false +--- + +Connect your application to an add-on: + +## Databases + +{{< cards >}} + {{< card link="/developers/doc/addons/materia-kv" title="Materia KV" subtitle="Serverless & distributed key-value database" icon="materia" tag="Alpha" >}} + {{< card link="/developers/doc/addons/mongodb" title="MongoDB" subtitle="The NoSQL document-oriented database" icon= "mongo">}} + {{< card link="/developers/doc/addons/mysql" title="MySQL" icon="mysql" subtitle="Your managed relational database" >}} + {{< card link="/developers/doc/addons/postgresql" title="PostgreSQL" icon="pg" subtitle="The not-only-SQL managed database" >}} + {{< card link="/developers/doc/addons/elastic" title="Elastic Stack" subtitle="Deploy your Elastic Stack in one click" icon="elastic" >}} + + {{< card link="/developers/doc/addons/redis" title="Redis" subtitle="Managed key-value database" icon="redis" >}} +{{< /cards >}} + +## Storage & Messaging + +{{< cards >}} + {{< card link="/developers/doc/addons/cellar" title="Cellar" subtitle="Object storage, compatible with S3 API" icon="cellar" >}} + {{< card link="/developers/doc/addons/fs-bucket" title="FS Bucket" subtitle="Persistent external file system for your apps" icon="fsbucket" >}} + {{< card link="/developers/doc/addons/pulsar" title="Pulsar" subtitle="Open source, distributed messaging and streaming platform built for the cloud" icon="pulsar" tag="Beta" >}} +{{< /cards >}} + +## Services & Tools + +{{< cards >}} + {{< card link="/developers/doc/addons/config-provider" title="Config Provider" subtitle="More freedom to manage, import and inject your configurations and credentials" icon="creds" >}} + {{< card link="/developers/doc/addons/heptapod" title="Heptapod" subtitle="The friendly fork of GitLab Community Edition that adds support for Mercurial" icon="git" >}} + {{< card link="/developers/doc/addons/jenkins" title="Jenkins" subtitle="The leading open source automation server" icon="jenkins" >}} + {{< card link="/developers/doc/addons/keycloak" title="Keycloak" subtitle="Single sign-on with Identity and Access Management solution" icon="keycloak" >}} + {{< card link="/developers/doc/addons/mailpace" title="Mailpace" subtitle="Fast and reliable transactional email" icon="mail" >}} + {{< card link="/developers/doc/addons/matomo" title="Matomo" subtitle="A web analytics application as a service, the best Google Analytics alternative" icon="matomo" >}} + {{< card link="/developers/doc/addons/metabase" title="Metabase" subtitle="An easy business intelligence tool to query and visualize data" icon="metabase" >}} + {{< card link="/developers/doc/addons/otoroshi" title="Otoroshi with LLM" subtitle="Simple API management based on a modern reverse proxy with preconigured plugins" icon="endpoints" >}} +{{< /cards >}} diff --git a/content/doc/addons/cellar.md b/content/doc/addons/cellar.md new file mode 100644 index 000000000..4af7a5786 --- /dev/null +++ b/content/doc/addons/cellar.md @@ -0,0 +1,726 @@ +--- +type: docs +title: Cellar, S3-compatible object storage service +linkTitle: Cellar Object Storage +description: Cellar is an Amazon S3-compatible file storage system created and hosted by Clever Cloud +tags: +- addons +keywords: +- S3 +- amazon +- Storage +- file +- files +- s3cmd +- aws +aliases: +- /addons/cellar +- /deploy/addon/cellar +- /doc/cellar +- /doc/deploy/addon/cellar +--- +{{< hextra/hero-subtitle >}} + Cellar is a S3-compatible online file storage web service. Use it with your favorite S3 client, or download the `s3cmd` configuration file from the add-on dashboard in Clever Cloud console. + +{{< /hextra/hero-subtitle >}} + +## Creating a bucket + +Cellar stores files in buckets. When you create a Cellar add-on, no bucket exists yet. + +### From Clever Cloud Console + +{{% steps %}} + +#### Go to Cellar options + +Click on your Cellar add-on in your deployed services list to see its menu. + +#### Name your bucket + +From **Add-on Dashboard**, insert the name of your bucket. + +{{< callout type="info">}} + Buckets' names are global for every region. **You can't give the same name to two different buckets in the same region**, because the URL already exists in the Cellar cluster on this region. bucket names can't use underscores `(_)`. +{{< /callout >}} + +#### Create bucket + +Click on **Create bucket**. Your new bucket should appear in the list below. + +{{% /steps %}} + +### With s3cmd + +{{% steps %}} + +#### Install s3cmd + +Install s3cmd on your machine following [these recommendations](https://s3tools.org/s3cmd). + +#### Download the configuration file + +Go to your add-on menu in the Clever Cloud console. Under the **Add-on Dashboard**, click the *Download a pre-filled s3cfg file.* link. This provides you a configuration file that you need to add to your home on your machine. + +#### Create a bucket + +To create a bucket, you can use this s3cmd command: + +```bash +s3cmd mb s3://bucket-name +``` + +The bucket is now be available at `https://.cellar-c2.services.clever-cloud.com/`. + +{{% /steps %}} + +{{< callout type="warning">}} + `ws-*` and `cf*` commands aren't available with a Cellar add-on. +{{< /callout >}} + +### With AWS CLI + +You can use the official [AWS cli](https://aws.amazon.com/cli/) with Cellar. Configure the `aws_access_key_id`, `aws_secret_access_key` and endpoint. + +```bash +aws configure set aws_access_key_id $CELLAR_ADDON_KEY_ID +aws configure set aws_secret_access_key $CELLAR_ADDON_KEY_SECRET +``` + +Global endpoint configuration isn't available, so include the parameter each time you use the `aws` cli. Here's an example to create a bucket: + +```bash +aws s3api create-bucket --bucket myBucket --acl public-read --endpoint-url https://cellar-c2.services.clever-cloud.com +``` + +To simplify this, you may want to configure an alias like so: + +```bash +alias aws="aws --endpoint-url https://cellar-c2.services.clever-cloud.com" +``` + +## Managing your buckets + +There are several ways to manage your buckets, find in this section a list of options. + +### Using S3 clients + +Some clients allows you to upload files, list them, delete them, etc, like: + +- [Cyberduck](https://cyberduck.io) +- [Filestash](https://www.filestash.app/) +- [MinIO](https://min.io/docs/minio/linux/reference/minio-mc.html) +- [S3 Browser](https://s3browser.com/) +- [WinSCP](https://winscp.net) + +This list isn't exhaustive. Feel free to [suggest other clients that you would like to see in this documentation](https://github.com/CleverCloud/documentation/discussions/new?category=general). + +### Using s3cmd command line tools + +`s3cmd` allows you to manage your buckets using its commands, after [configuring it on your machine](#with-s3cmd) + +{{< tabs items="Upload,List" >}} + + {{< tab >}} + You can upload files (`--acl-public` makes the file publicly readable) with: + + ```bash + s3cmd put --acl-public image.jpg s3://bucket-name + ``` + + The file is then publicly available at `https://.cellar-c2.services.clever-cloud.com/image.jpg`. + {{< /tab >}} + + {{< tab >}} + You can list the files in your bucket, you should see the `image.png` file: + + ```bash + s3cmd ls s3://bucket-name + ``` + + {{< /tab >}} + +{{< /tabs >}} + +#### Custom domain + +If you want to use a custom domain, for example `cdn.example.com`, you need to create a bucket named exactly like your domain: + +```bash +s3cmd --host-bucket=cellar-c2.services.clever-cloud.com mb s3://cdn.example.com +``` + +Then, create a CNAME record on your domain pointing to `cellar-c2.services.clever-cloud.com.`. + +## Using AWS SDK + +To use cellar from your applications, you can use the [AWS SDK](https://aws.amazon.com/tools/#sdk). +You only need to specify a custom endpoint (eg `cellar-c2.services.clever-cloud.com`). + +{{< tabs items="Node.js,Java,Python,Ruby" >}} + + {{< tab >}} + **Node.js** + + ```javascript + // Load the AWS SDK for Node.js + const AWS = require('aws-sdk'); + + // Set up config + AWS.config.update({ + accessKeyId: '', + secretAccessKey: '' + }); + + // Create S3 service object + const s3 = new AWS.S3({ endpoint: '' }); + + // Create the parameters for calling createBucket + const bucketParams = { + Bucket : '', + CreateBucketConfiguration: { + LocationConstraint: '' + } + }; + + // call S3 to create the bucket + s3.createBucket(bucketParams, function(err, data) { + // handle results + }); + + // Call S3 to list the buckets + s3.listBuckets(function(err, res) { + // handle results + }); + + /* In order to share access to access non-public files via HTTP, you need to get a presigned url for a specific key + * the example above present a 'getObject' presigned URL. If you want to put a object in the bucket via HTTP, + * you'll need to use 'putObject' instead. + * see doc : https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#getSignedUrl-property + */ + s3.getSignedUrl('getObject', {Bucket: '', Key: ''}) + ``` + + {{< /tab >}} + + {{< tab >}} + **Java** + + Import the AWS SDK S3 library. Maven uses the following dependency to do so : + + ```xml + + software.amazon.awssdk + s3 + 2.21.35 + + ``` + + Make sure to use latest version of the `2.X`, new versions are released regularly. See [the AWS Java SDK Documentation](https://github.com/aws/aws-sdk-java-v2/#using-the-sdk) for more details. + + Below is a sample Java class, written in Java 21, listing the objects of all buckets : + + ```java + import software.amazon.awssdk.auth.credentials.AwsBasicCredentials; + import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider; + import software.amazon.awssdk.services.s3.S3Client; + import software.amazon.awssdk.services.s3.model.Bucket; + import software.amazon.awssdk.services.s3.model.ListObjectsRequest; + + import java.net.URI; + import java.util.List; + + public class CleverCloudCellarDemoApplication { + + // replace those values with your own keys, load them from properties or env vars + private static final String CELLAR_HOST = ""; + private static final String CELLAR_KEY_ID = ""; + private static final String CELLAR_KEY_SECRET = ""; + + public static void main(String[] args) { + // initialize credentials with Cellar Key ID and Secret + // you can also use `EnvironmentVariableCredentialsProvider` by setting AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY env vars + var credentialsProvider = StaticCredentialsProvider.create(AwsBasicCredentials.create(CELLAR_KEY_ID, CELLAR_KEY_SECRET)); + + // create a client builder + var s3ClientBuilder = S3Client.builder() + // override the S3 endpoint with the cellar Host (starting with 'https://' + .endpointOverride(URI.create(CELLAR_HOST)) + .credentialsProvider(credentialsProvider); + + // initialize the s3 client + try (S3Client s3 = s3ClientBuilder.build()) { + // list buckets + List buckets = s3.listBuckets().buckets(); + buckets.forEach(bucket -> { + // list bucket objects + var listObjectsRequest = ListObjectsRequest.builder().bucket(bucket.name()).build(); + var objects = s3.listObjects(listObjectsRequest).contents(); + // handle results + }); + + } + } + } + ``` + + See the [AWS Java SDK code examples for S3](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3) for more example use cases. + {{< /tab >}} + +{{< tab >}} + **Python** + + Tested with Python 3.6. + + This script uses boto, the old implementation of the aws-sdk in python. The host endpoint is `cellar-c2.services.clever-cloud.com` (verify the `CELLAR_ADDON_HOST` variable value in the Clever Cloud console, from the **Information** option). + + ```python + from boto.s3.key import Key + from boto.s3.connection import S3Connection + from boto.s3.connection import OrdinaryCallingFormat + + apikey='' + secretkey='' + host='' + + cf=OrdinaryCallingFormat() # This mean that you _can't_ use upper case name + conn=S3Connection(aws_access_key_id=apikey, aws_secret_access_key=secretkey, host=host, calling_format=cf) + + b = conn.get_all_buckets() + print(b) + + """ + In order to share access to non-public files via HTTP, you need to get a presigned url for a specific key + the example above present a 'getObject' presigned URL. If you want to put a object in the bucket via HTTP, + you'll need to use 'putObject' instead. + see doc : https://docs.pythonboto.org/en/latest/ref/s3.html#boto.s3.bucket.Bucket.generate_url + """ + b[0].generate_url(60) + ``` + + {{< /tab >}} + + {{< tab >}} + **Active Storage (Ruby On Rails)** + + [Active Storage](https://guides.rubyonrails.org/active_storage_overview.html) can manage various cloud storage services like Amazon S3, Google Cloud Storage, or Microsoft Azure Storage. To use Cellar, + you must configure a S3 service with a custom endpoint. + + Use this configuration in your `config/storage.yml`: + + ```yaml {filename="config/storage.yml"} + cellar: + service: S3 + access_key_id: <%= ENV.fetch('CELLAR_ADDON_KEY_ID') %> + secret_access_key: <%= ENV.fetch('CELLAR_ADDON_KEY_SECRET') %> + endpoint: https://<%= ENV.fetch('CELLAR_ADDON_HOST') %> + region: 'us-west-1' + force_path_style: true + bucket: mybucket + ``` + + Although the `region` parameter appears, it's not used by Cellar. The region value serves to satisfy ActiveStorage and the aws-sdk-s3 gem. Without a region option, an exception would raise : `missing keyword: region (ArgumentError)`. If region is an empty string you will get the following error: `missing region; use :region option or export region name to ENV['AWS_REGION'] (Aws::Errors::MissingRegionError)`. + + Set `force_path_style` to `true` as described in the [Ruby S3 Client documentation](https://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Client.html). + {{< /tab >}} + +{{< /tabs >}} + +## Policies + +Cellar allows you to create policies to control the actions on your buckets. Find below two policies examples, and [further documentation](https://docs.ceph.com/en/latest/radosgw/bucketpolicy/). + +### Public bucket policy + +You can upload all your objects with a public ACL, but you can also make your whole bucket publicly available in read mode. No one can access the write permission without authentication. + +{{< callout type="warning" >}} + This makes all of your bucket's objects publicly readable. Be careful that there aren't objects you don't want publicly exposed. +{{< /callout >}} + +To set your bucket as public, you have to apply the following policy which you can save in a file named `policy.json`: + +```json +{ + "Id": "Policy1587216857769", + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "Stmt1587216727444", + "Action": [ + "s3:GetObject" + ], + "Effect": "Allow", + "Resource": "arn:aws:s3:::/*", + "Principal": "*" + } + ] +} +``` + +Replace the `` with your bucket name in the policy file. Don't change the `Version` field to the current date, keep it as is. + +Now, you can set the policy to your bucket using s3cmd: + +```bash +s3cmd setpolicy ./policy.json s3:// +``` + +💡 If you encounter errors, you might need to specify the [configuration file path](#download-the-configuration-file): + +```bash +s3cmd setpolicy ./policy.json -c path/to/s3cfg.txt s3:// +``` + +All of your objects should now be publicly accessible. + +If needed, you can delete this policy by using: + +```bash +s3cmd delpolicy s3:// +``` + +The original ACL should apply to all of your objects after that. + + +### IP restrictions + +If you need to restrict your S3 Cellar to certain IPs, you can use a policy. +To do so, you can use the template below in a `policy.json` file. This example show how to block actions from any IP that isn't `192.168.1.6`. + +- Replace the `` with your bucket name in the policy file. +- Change the `Effect` to `Allow` or `Deny` depending on your needs. +- Change the IP address under `Condition` to select which IP should trigger the rule. + +```json {filename="IP-restriction-policy.json"} +{ + "Version": "2012-10-17", + "Id": "S3PolicyIPRestrict", + "Statement": [ + { + "Sid": "IPAllow", + "Effect": "Deny", + "Principal": { + "AWS": "*" + }, + "Action": "s3:*", + "Resource": [ + "arn:aws:s3:::", + "arn:aws:s3:::/*" + ], + "Condition" : { + "IpAddress" : { + "aws:SourceIp": ["0.0.0.0/0"] + }, + "NotIpAddress": { + "aws:SourceIp": ["192.168.1.6/32"] + } + } + } + ] +} +``` + +To apply the policy, use this command: +``` +s3cmd setpolicy ./policy.json s3:// +``` + +To delete the policy, use this command: +``` +s3cmd delpolicy ./policy.json s3:// +``` + +### User access + +Cellar doesn't natively support creating different user accesses for the same add-on. Granting access to your Cellar add-on grants full access to all of your buckets. To grant limited access to a bucket, do the following: + +1. Create your main Cellar add-on (we'll call it `Cellar-1`) +2. Download `Cellar 1` s3cfg file +3. Create a second Cellar add-on (we'll call it `Cellar-2`) +4. Get the `ADDON ID` from `Cellar-2` dashboard (it should look like `cellar_xxx`) +5. Create a policy for `Cellar-1` and inject the `ADDON ID` from `Cellar-2` as the user. + +Now, you can pass `Cellar-2` credentials to a third party to grant read-only access to `Cellar-1` buckets. + +#### Read-only policy example + +This policy example grants read-only access to a bucket for another user, using the preceding procedure. + +```json {filename="read-only-policy.json"} +{ + "Version": "2012-10-17", + "Statement": [ + { + "Action": [ + "s3:GetObject", + "s3:ListBucket" + ], + "Effect": "Allow", + "Resource": "arn:aws:s3:::/*", + "Principal": {"AWS": "arn:aws:iam::cellar_xxx"} + + } + ] + } + +``` + +Replace the `` with your bucket name in the policy file. + +Set the policy to your bucket using s3cmd: + +```bash +s3cmd --config= setpolicy ./policy.json s3:// +``` + +💡Download the [configuration file from Clever Cloud](#download-the-configuration-file): + +```bash +s3cmd setpolicy ./policy.json -c path/to/s3cfg.txt s3:// +```` + +## CORS Configuration + +You can set a [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) configuration on your buckets if you need to share resources on websites that don't have the same origin as the one you are using. + +Each CORS configuration can contain multiple rules, defined in an XML document: + +```xml + + + console.clever-cloud.com + PUT + POST + DELETE + * + ETag + + + * + GET + 3600 + + +``` + +Here this configuration has two `CORS` rules: + +- The first rule allows cross-origin requests from the `console.clever-cloud.com` origin. Allowed cross-origin request methods are `PUT`, `POST` and `DELETE`. Using `AllowedHeaders *` allows all headers specified in the preflight `OPTIONS` request in the `Access-Control-Request-Headers` header. At the end, the `ExposeHeader` allows the client to access the `ETag` header in the response it received. +- The second one allows cross-origin `GET` requests for all origins. The `MaxAgeSeconds` directive tells the browser how much time (in seconds) it should cache the response of a preflight `OPTIONS` request for this particular resource. + +{{< callout type="info" >}} + +**Updating the CORS configuration replaces the old one:** if you update your CORS configuration, the new configuration replaces the old one. Be sure to save it before you update it if you ever need to roll back. + +{{< /callout >}} + +{{% steps %}} + +### View and save your current CORS configuration + +To view and save your current CORS configuration, you can use `s3cmd info`: + +```bash +s3cmd -c s3cfg -s info s3://your-bucket +``` + +### Set the CORS configuration + +You can then set this CORS configuration using `s3cmd`: + +```bash +s3cmd -c s3cfg -s setcors ./cors.xml s3://your-bucket +``` + +If you need to **rollback**, you can either set the old configuration or completely drop it: + +```bash +s3cmd -c s3cfg -s delcors s3://your-bucket +``` + +{{% /steps %}} + +## Static hosting + +You can use a bucket to host your static website, this [blog post](https://www.clever-cloud.com/blog/engineering/2020/06/24/deploy-cellar-s3-static-site/) describes how to. Be aware that SPA applications won't work because Clever Cloud proxy serving the bucket needs to find an HTML file that match the route. + +For example if your path is `/login` you need to have a file `login.html` because the `index.html` isn't the default entrypoint to handle the path. + +You may use SSG (Static Site Generated) to dynamically generate your content during your build. + +## Versioning + +### What is bucket versioning + +Versioning enables you to store multiple versions of an object in your bucket. When you upload a file with the same name as an existing one, Cellar automatically saves the previous version of that object. This safeguards your data against accidental actions, such as deleting a file by mistake. + +Only the latest version of a file is visible, while previous versions remain hidden but securely stored in the bucket. This ensures you can easily restore an earlier version if needed. + +### How does versioning work + +Versioning can't be enabled for a single file: it will cover the entire bucket. +A bucket can be in one of three state : + + - Unversioned (The default) + - Versioning-enabled + - Versioning-suspended + +You enable and suspend versioning at the bucket level. Once you enable versioning on a bucket, it can never return to an unversioned state. But you can suspend versioning on that bucket at any time. +Once versioning is enabled, any object you add have a unique version ID. Object that were already existing before enabling versioning have a version ID of `null`. + +For that reason, we do recommend you to enable versioning when creating a new bucket. It will be easier to navigate through version IDs. + +> [!WARNING] +> Versioning can quickly take up a lot of space since multiple version of an object are stored in the bucket. + +{{< tabs items="MinIO, AWS CLI" >}} + + {{< tab >}} + + To use [minIO](https://min.io/docs/minio/linux/reference/minio-mc.html#command-mc), you must create an alias. + + ```sh + mc alias set https://cellar-c2.services.clever-cloud.com + ``` + + ### Activate versioning with MinIO + + To activate versioning, you can use MinIO and the following command. + + ```sh + mc version enable / + ``` + + If you want to suspend versioning, you can replace `enable` by `suspend` + + You can check that versioning is enabled for your bucket with : + + ```sh + mc version info / --json + ``` + + ### How to use versioning + +When versioning is enabled, the newly added object is automatically provided with a unique identifier. Only the latest version of an object is shown with a `mc ls /`. + + #### List versioned objects + + If you need to list all the object in your bucket, including the different versions of the files stored in it, you can run : + + ```sh + mc ls --versions --recursive / + ``` + + You can list all the version of a specific file with + + ```sh + mc ls --versions // + ``` + + #### Get a version of an object + + You can get the specific version of an object using its version ID obtained using the previous command. + + ```sh + mc get --vid // + ``` + + #### Delete a version of an object + + You can delete the specific version of an object using its version ID. + + ```sh + mc rm --vid // + ``` + + + {{< /tab >}} + + {{< tab >}} + + The following command assumes you have configured your AWS CLI and added an alias as shown earlier in the section [Creating a bucket with AWS CLI](/developers/doc/addons/cellar/#with-aws-cli) + + ### Activate versioning with AWS CLI + + To activate versioning, you can use AWS CLI. You can use the following command to enable it on a bucket. + + ```sh + aws s3api put-bucket-versioning --bucket --versioning-configuration Status=Enabled + ``` + + If you want to turn off versioning, you can use the following: + +```sh + aws s3api put-bucket-versioning --bucket --versioning-configuration Status=Suspended + + You can check if versioning is enabled on your bucket with : + + ```sh + aws s3api get-bucket-versioning --bucket + ``` + + ### How to use versioning + + When versioning is enabled, the added object automatically gets a versionID. Only the latest version of an object if shown. + + #### List all versioned Object + + If you need to list all the objects in your bucket, including the different versions of the files stored in it, you can use : + + ```sh + aws s3api list-object-versions --bucket + ``` + + #### List all the version of a specific Object + + If you want to check the different versions of a specific object, you can use the following command. In this example, we find the versions of test.txt : + + ```sh + aws s3api list-object-versions --bucket --prefix + ``` + + #### Get the version of an Object + + If you want to retrieve the previous version of an object, you need the versionID that you can get with any of the two previous command. You can use : + + ```sh + aws s3api get-object --bucket --version-id '' --key /path/to/save/file/copy/test.txt + ``` + + #### Delete the version of an object + + To remove a version of an object, you can use this command : + + ```sh + aws s3api delete-object --bucket --version-id '' --key + ``` + +{{< /tab >}} + +{{< /tabs >}} + +## Troubleshooting + +{{% details title="SSL error with s3cmd" closed="true" %}} + +If you created a bucket with a [custom domain name](#using-a-custom-domain) and use `s3cmd` to manipulate it, you will experience this error: + +```log +[SSL: SSLV3_ALERT_HANDSHAKE_FAILURE] sslv3 alert handshake failure (_ssl.c:1125) +``` + +The error comes from the host used to make the request, which is build like this `%s.cellar-c2.services.clever-cloud.com`. + +For example with a bucket named `blog.mycompany.com`: + +Clever Cloud certificate covers `*.cellar-c2.services.clever-cloud.com` but not `blog.mycompany.com.cellar-c2.services.clever-cloud.com`, which triggers the error. + +Solve it by **forcing s3cmd to use path style endpoint** with the option `--host-bucket=cellar-c2.services.clever-cloud.com`. +{{% /details %}} + +{{% details title="I can't delete a bucket/Cellar add-on" closed="true" %}} + +The buckets need to be empty before you can delete them. Solve this error by deleting the content of your bucket using a [bucket management option](#managing-your-buckets). + +{{% /details %}} diff --git a/content/doc/addons/config-provider.md b/content/doc/addons/config-provider.md new file mode 100644 index 000000000..9ed0d9dda --- /dev/null +++ b/content/doc/addons/config-provider.md @@ -0,0 +1,79 @@ +--- +type: docs +title: Configuration provider +description: Share configuration between apps +tags: +- addons +keywords: +- configuration +- environment variables +aliases: +- /addons/config-provider +- /deploy/addon/config-provider +- /doc/deploy/addon/config-provider +--- + +The configuration provider add-on helps you to create groups of environment variables that you can share with multiple applications. + +## Example + +Let's take an example with 2 Node.js applications exposing some REST APIs: `shipping-api` and `payment-api`. + +The `shipping-api` application needs the following environment variables: + +* `PULSAR_TOPIC=order` +* `USER_API_HOST=https://user.example.com/api` +* `ENABLE_PARTNERS=true` + +The `payment-api` application needs the following environment variables: + +* `PULSAR_TOPIC=order` +* `USER_API_HOST=https://user.example.com/api` +* `ENABLE_SEPA=false` + +![Two Node.js applications with their own environment variables](/images/schema-config-provider-01.svg "Two Node.js applications with their own environment variables") + +As you can see, we had to define `PULSAR_TOPIC` and `USER_API_HOST` in both applications with the same value. +If we ever need to change these values, we'll have to apply the updates in both apps and restart them. + +NOTE: This is a simple example, but we could have more than just 2 microservices and more than just 2 common variables. + +To simplify this process, we will create a configuration provider add-on. +It will allow us to define those common variables in one place and inject them in our 2 applications. + +![Two Node.js applications with their own environment variables](/images/schema-config-provider-02.svg "Two Node.js applications with their own environment variables") + +Think of a configuration provider as a way to group a set of environment variables and share them with any application. + +![One application overriding the environment variable value for PULSAR_TOPIC](/images/schema-config-provider-03.svg "One application overriding the environment variable value for PULSAR_TOPIC") + +If a variable is defined in a configuration provider **and** also in the application, the value defined in the application wins. + +## How to create a config provider + +In the console, go to the organisation where you have your applications. + +1. Click on **Create** and then on **an add-on** +2. You will see a list of add-ons, select **Configuration provider** +3. Select the first plan and click on **Next** +4. Toggle the **Link** for each application you need and then on **Next** +5. Define a name and click on **Next** + +Once you have your configuration provider, you can set the variables in the form. +You can find out more about rules and format in [this page](/developers/doc/develop/env-variables#environment-variables-rules-and-formats). + +{{< callout type="info" >}} +At any point, you can link/unlink an application from the configuration provider by going to the app's _"Service dependencies"_ page. +{{< /callout >}} + +## Details and behaviour + +* As with any other add-on, you can only link a configuration provider to applications that are in the same organisation. +* Variables defined directly in the application override the ones injected from the configuration provider. +* When you update the variables of a configuration provider, all applications linked to it will be automatically restarted. +* You can create multiple configuration providers in your organisation and link them to different applications. + +## Pricing + +This add-on is completely free. +No fee will be invoiced to you while using this kind of add-on. diff --git a/content/doc/addons/couchbase.md b/content/doc/addons/couchbase.md new file mode 100644 index 000000000..39017e129 --- /dev/null +++ b/content/doc/addons/couchbase.md @@ -0,0 +1,10 @@ +--- +type: docs +title: CouchBase +description: CouchBase is a database which automation is still in beta on Clever Cloud +aliases: +- /doc/databases-and-services/couchbase +--- + +CouchBase is a database wich automation is still in beta on Clever Cloud. +Please reach to our support if you would like to use this database, they will kindly assist you. diff --git a/content/doc/addons/elastic.md b/content/doc/addons/elastic.md new file mode 100644 index 000000000..7e87d77f7 --- /dev/null +++ b/content/doc/addons/elastic.md @@ -0,0 +1,200 @@ +--- +type: docs +title: Elastic Stack +description: The Elastic Stack is Elasticsearch, Kibana, Beats, and Logstash (also known as the ELK Stack) +tags: +- addons +keywords: +- fulltext +- elsaticsearch +- elastic +- kibana +- apm +comments: false +aliases: +- /addons/elastic +- /doc/deploy/addon/elastic/elastic +- /doc/deploy/addon/elastic +- /doc/elastic +- /doc/elasticsearch +- /doc/elasticsearch-hosting +--- + +The Elastic Stack is Elasticsearch, Kibana, Beats, and Logstash (also known as the ELK Stack). Reliably and securely take data from any source, in any format, then search, analyze, and visualize it in real time. Find out more about it on [Elastic's website](https://www.elastic.co/products/elastic-stack). + +Provisioning the Elastic Stack add-on on Clever Cloud will give you an Elasticsearch instance, Kibana and an APM server. + +## Versions + +The current versions supported at add-on creation are the following: +{{< software_versions_shared_dedicated elastic>}} + +## Elasticsearch + +Elasticsearch is a distributed, RESTful search and analytics engine capable of addressing a growing number of use cases. As the heart of the Elastic Stack, it centrally stores your data so you can discover the expected and uncover the unexpected. + +## Kibana + +Kibana lets you visualize your Elasticsearch data and navigate the Elastic Stack so you can do anything from tracking query load to understanding the way requests flow through your apps. + +It is available as an opt-in option of the Elastic add-on. It will be deployed and billed as a regular application. You can upscale/downscale/delete it at any time. This application will be updated by Clever Cloud on a regular basis. + +The created application name follow the pattern *Kibana - addon_eb464a6d-ce5f-4780-b595-6772ebe33d06*. The provisioning of this application might take up a minute to show up in your organisation. + +Learn more on [Kibana official documentation](https://www.elastic.co/guide/en/kibana/current/index.html). + +### Authentication + +Any member of the Clever Cloud organisation containing the Elastic add-on will be able to login to Kibana through an automatically configured SSO system. + +## Elastic APM + +Elastic APM is an Application performance management tool chain based on the Elastic Stack. See exactly where your application is spending time so you can quickly fix issues and feel good about the code you push. To use it you must install an *APM agent* to your application. In some cases, you'll need to add a configuration file, or add it as a dependency in you application. You can find configuration files examples in [our public repository](https://github.com/CleverCloud/Elastic-APM-example-configuration-files). + +Once both your application and APM server are running, you application with automatically send APM datas to the APM server which will send them to Elastic and once indexed they will be available in your Kibana dashboard (this process is really fast, you won't see it as a human). + +Currently, APM agents are available in the following languages: + +- [Go](https://www.elastic.co/guide/en/apm/agent/go/1.x/introduction.html) +- [Java](https://www.elastic.co/guide/en/apm/agent/java/1.x/intro.html) +- [Node.js](https://www.elastic.co/guide/en/apm/agent/nodejs/2.x/intro.html) +- [PHP](https://www.elastic.co/guide/en/apm/agent/php/current/index.html) +- [Python](https://www.elastic.co/guide/en/apm/agent/python/5.x/getting-started.html) +- [Ruby](https://www.elastic.co/guide/en/apm/agent/ruby/3.x/introduction.html) + +It is available as an opt-in option of the Elastic add-on. It will be deployed and billed as a regular application. You can upscale/downscale/delete it at any time. This application will be updated by Clever Cloud on a regular basis. + +The created application name follow the pattern *APM - addon_eb464a6d-ce5f-4780-b595-6772ebe33d06*. The provisioning of this application might take up a minute to show up in your organisation. + +Learn more on [APM official documentation](https://www.elastic.co/guide/en/apm/get-started/current/components.html). + +### How to setup APM + +Any applications linked to the APM application will have the right credentials and APM endpoint automatically available as environment variables. In some cases these variables will be picked up automatically by the APM agent you are using in your application and everything will work automatically. But in some other cases you have to configure it yourself. See for instance the [Rails documentation](https://www.elastic.co/guide/en/apm/agent/ruby/3.x/getting-started-rails.html#getting-started-rails). The list of agents configuration can be found on Elastic's [documentation](https://www.elastic.co/guide/en/apm/agent/index.html). + +### APM Server custom configuration + +The APM server is deployed as an application. As such it's configured as an application. Its default pre run hook is set to: + +`CC_PRE_RUN_HOOK="curl https://api.clever-cloud.com/v2/providers/es-addon/apm-server-setup/7 | sh"` + +You can change the URL to point to your own custom configuration. + +Here is a configuration example for RUM activation: + +```bash{filename="es-apm-serverconfig.sh"} +#!/bin/bash -l + +cat <apm-server.yml +apm-server: + host: "0.0.0.0:8080" + secret_token: "${ES_ADDON_APM_AUTH_TOKEN}" + +output.elasticsearch: + hosts: ["${ES_ADDON_HOST}:443"] + protocol: "https" + username: "${ES_ADDON_APM_USER}" + password: "${ES_ADDON_APM_PASSWORD}" + +path.home: "${APP_HOME}" + +logging: + to_syslog: true + to_files: false + +apm-server.rum.enabled: true +apm-server.rum.event_rate.limit: 300 +apm-server.rum.event_rate.lru_size: 1000 +apm-server.rum.allow_origins: ['*'] +apm-server.rum.library_pattern: "node_modules|bower_components|~" +apm-server.rum.exclude_from_grouping: "^/webpack" +apm-server.rum.source_mapping.enabled: true +apm-server.rum.source_mapping.cache.expiration: 5m +apm-server.rum.source_mapping.index_pattern: "apm-*-sourcemap*" +``` + +### Kibana custom configuration + +Kibana is deployed as an application. As such it's configured as an application. Its default pre run hook is set to: + +`CC_PRE_RUN_HOOK="curl https://api.clever-cloud.com/v2/providers/es-addon/kibana-setup/7 | sh"` + +You can change the URL to point to your own custom configuration. + +### Java APM agent + +You have multiple ways to use the APM agent. You can either add it in your dependencies and it should work out of the box or you can attach an agent to the JVM. If you prefer the last option, you have to define the following environment variable to attach the agent to the JVM: `CC_JAVA_APM_AGENT_ENABLE=true`. + +The agent will list all JVMs on the system and attach to all of them, only once. If you know that your application will spawn multiple JVM processes (not threads) over time and you want the agent to also monitor those processes, you can add this environment variable: `CC_JAVA_APM_AGENT_CONTINUOUS=true`. + +The agent will periodically scan for JVM processes and will attach to them if needed. + +## Plugins + +Elasticsearch managed by Clever Cloud comes with these plugins, you can activate at add-on creation: + +| Plugin | Description | +| ------ | ----------- | +| analysis-icu | Adds extended Unicode support using the ICU libraries | +| analysis-kuromoji | Advanced analysis of Japanese using the Kuromoji analyzer | +| analysis-nori | Morphological analysis of Korean using the Lucene Nori analyzer | +| analysis-phonetic | Analyzes tokens into their phonetic equivalent using Soundex, Metaphone, Caverphone, and other codecs | +| analysis-smartcn | An analyzer for Chinese or mixed Chinese-English text | +| analysis-stempel | Provides high quality stemming for Polish | +| analysis-ukrainian | Provides stemming for Ukrainian | +| discovery-ec2 | Uses the AWS API to identify the addresses of seed hosts | +| discovery-azure-classic | Uses the Azure Classic API to identify the addresses of seed hosts | +| discovery-gce | Uses the GCE API to identify the addresses of seed hosts | +| mapper-size | Provides the `_size` metadata field which, when enabled, indexes the size in bytes of the original `_source` field | +| mapper-murmur3 | Allows hashes to be computed at index-time and stored in the index for later use with the cardinality aggregation | +| mapper-annotated-text | Provides the ability to index text that is a combination of free-text and special markup | + +{{< callout type="info" >}} +Plugin activation is only available at add-on creation, through [API](/developers/api) or the `--option` flag of [Clever Tools](/developers/doc/cli/addons/#create--rename--delete). You must pass the option as a comma-separated list: `plugins=plugin1,plugin2`. To modify enabled plugins on an existing add-on, contact [support team](https://console.clever-cloud.com/ticket-center-choice). +{{< /callout >}} + +## Backups + +Your Elastic add-on backups are managed by Clever Cloud. When you provision the add-on, we automatically create a Cellar add-on instance named Backups. You will find it in your organisation. Backups are taken daily and are stored in this Cellar add-on instance. As such *additional credits will be consumed by your backups*. + +Backups can be managed under the *Backup* tab of the elastic add-on. You can restore, delete or open it directly under Kibana if you opted-in. + +{{< callout type="warning" >}} +If you are using Elasticsearch 6, backups are not deleted automatically, you will need to clean them up from time to time. +{{< /callout >}} + +## Create an index on Elasticsearch + +When creating an Elasticsearch add-on, a single node is setup. By default we apply `cc_singlenode_template` that forces the amount of data replication to zero. This index template is only available for data streams. + +If you are using a tool that requires native Elasticsearch indexes or are accessing them through the Elasticsearch API, you will need an index template. They can be created either using Kibana or the Elasticsearch API. For the latter, you can use a cURL request such as: + +```sh +curl 'https://${ELASTIC_SEARCH_HOST}/_index_template/test/' -u ${ELASTIC_SEARCH_USER} -H 'Content-Type: application/json' -X PUT -d' +{ + "index_patterns" : ["${ELASTIC_INDEX_PATTERN}*"], + "priority": 2, + "template": { + "settings" : { + "number_of_shards" : 1, + "number_of_replicas": 0 + } + } +} +' +``` + +It's important here to set `number_of_replicas` to zero to avoid triggering cluster problems. The priority must be greater than 1, as the `cc_singlenode_template` template has a default priority of 1. + +## 🔑 Rights and permissions + +Elastic Stack add-ons are **managed services**, with Clever Cloud in charge of configuring and maintaining native configuration files. Some operations like adding an oauth source to connect to Kibana can't be added, as well as some native settings modifications. This ensures optimal performances and security for managed services as configured by Clever Cloud. + +Most settings are available for modifications and update from Kibana or by API, for example: + +- Managing users permissions +- Frequencies of back-ups +- The lifecycle of backups indexes +- Backups destination + +If you think your system might require some customization (like some plugins activation), contact Clever Cloud support to explain your use case and we will work with you to find a solution. diff --git a/content/doc/addons/fs-bucket.md b/content/doc/addons/fs-bucket.md new file mode 100644 index 000000000..896031f00 --- /dev/null +++ b/content/doc/addons/fs-bucket.md @@ -0,0 +1,158 @@ +--- +type: docs +title: File System Buckets +description: This add-on allows applications to use a persistent file system, as git-based apps don't have one +tags: +- addons +keywords: +- nfs +- file system +- buckets +- fs buckets +- storage +aliases: +- /addons/fs_buckets +- /deploy/addon/fs-bucket +- /doc/addons/fs_buckets +- /doc/databases-and-services/fs-buckets +- /doc/deploy/addon/fs-bucket +- /doc/fs-bucket +--- + +When you deploy an application on Clever Cloud, like most PaaS, a new virtual machine is created, the previous one is deleted. If your application generates data, for example if you let users upload pictures and you don't store it on databases or object storage, you will lose anything on the local disk after a rebuild or a restart. + +Immutable infrastructure doesn't allow you to keep generated data files between deployments. To avoid this, you need **a persistent file system**. This is why we created File System Buckets, a network-based storage solution to retrieve data from a deployment to another. + +## Known Limitations + +FS Buckets are provided for application needing file-system backward compatibility, but there are not optimized for high-performance applications, especially those relying on caching. There are also some availability and features limitations: + +- FS Buckets are not available for Docker applications +- FS Buckets are note available in Health Data Hosting (HDS) Zone +- Clever Cloud provides automated backups every 24 hours, with only 72 hours of retention for FS Buckets (7 days for databases) + +> [!NOTE] PHP applications includes a default FS Bucket for session storage +> To deploy a PHP application on an HDS region, set [`CC_PHP_DISABLE_APP_BUCKET=true`](/developers/doc/applications/php/#speed-up-or-disable-the-session-fs-bucket). Consider using Redis to manage PHP sessions. + +## Configuring your application + +Buckets are configured using environment variables. Add the following to your application : + +```text +CC_FS_BUCKET=/some/empty/folder:bucket-xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-fsbucket.services.clever-cloud.com[:async] +``` + +Don't forget to replace the path of the mounted folder and the fs-bucket host with the targeted folder path (make sure the folder does not exists) and your fs-bucket host. + +Optionnally, you can add `:async` to the end of the environment variable. +This will make Clever Cloud mount the FS Bucket with the `async` option. +It will make the FS Bucket faster (sometimes up to 3 times faster), but in case of a network issue it may cause file +corruption. + +You can setup multiple buckets by appending a number at the end of the environment variable's name. + +```text +CC_FS_BUCKET=/some/empty/folder:fs_bucket_host +CC_FS_BUCKET_1=/some/otherempty/folder:fs_bucket_other_host:async +``` + +Note that the `async` parameter can be set per bucket. + +## Configuring your application with buckets.json (@deprecated) + +{{< callout emoji="🧹" >}} +**This method is deprecated** +This method is deprecated, we strongly recommend that you use environment variables. +If you want to switch from this method to the environment variables, you need to remove the `buckets.json` file. Otherwise, the environment variables will be ignored. +Also, this method does not support the `async` parameter. +{{< /callout >}} + +To configure your application to use buckets, use the +`clevercloud/buckets.json` file. +The `clevercloud` folder must be located at the root of your application. +The `buckets.json` file must contain the following structure: + +```javascript +[ + { + "bucket" : "bucketId", + "folder" : "/myFolder", + "apps" : ["app_id"] + + }, + { + "bucket_host" : "bucket-01234567-0123-0123-0123-012345678987-fsbucket.services.clever-cloud.com", + "folder" : "/myotherFolder", + "apps" : ["app_id_2"] + } +] +``` + +{{< callout type="info" >}} +You can find a pre-filled json object to copy in the dashboard of your FSBucket add-on, in the "Dashboard configuration" tab +{{< /callout >}} + +It's a json array containing objects with at least two fields: + +Usage | Field | Description +---------|--------------|-------------------------------------------------------------- +Required | bucket | The bucket id you can find in the console. It begins with `bucket_`. This is for "old-style" buckets (created before the 7 December 2015) +Required | bucket_host | The bucket host you can find in the console. It begins with `bucket-` and ends with `services.clever-cloud.com`. This is for "new-style" buckets. +Required | folder | The folder you want the bucket to be mounted in. Should start with `/`. Using the example *myFolder*, you can access your bucket via the *myFolder* folder at the root of your application (which absolute path is available in the `APP_HOME` environment variable) +Optional | apps | Whitelist of the applications allowed to mount this bucket. It's helpful if you need to deploy a *preprod* app and a *prod* app using the exact same codebase but different buckets + +The folder must not exist in your repository (or it needs to be empty). Otherwise, the mount of your bucket will be ignored. +You can mount the same bucket in different folders, but they will share the same content, so it's not the solution. You should prefer to mount the bucket in only one folder and then manage multiple subfolders in it. + +{{< callout type="warning" >}} +You cannot mount two buckets in the same folder for the same app. If you put the same "folder" value for two entries in your environment variables or the *buckets.json* array, **make sure** that the "apps" fields make the two buckets mutually exclusive upon deployment! +{{< /callout >}} + +## Accessing your data inside the FS Bucket + +### From your application + +Your bucket is mounted at the configured path, starting from your application's +root folder. + +If you want to use an absolute path, you can use the `APP_HOME` environment +variable, see [special environment variables](/developers/doc/develop/env-variables#special-environment-variables) + +### From the add-on dashboard + +The **File explorer** tab of the **add-on dashboard** gives you access to your files +in the FS bucket. + +### From your favorite SFTP client + +The **Add-on information** tab of your FS Bucket in [Clever Cloud Console](https://console.clever-cloud.com) displays information you need to connect using SSH File Transfer Protocol (SFTP). You can use the following SSH public keys to ensure the connection is authentic and trusted: + +| Algorithm | Key size | Fingerprint | +|-----------|----------|----------------------------------------------------| +| ED25519 | 256 | `SHA256:+ku6hhQb1O3OVzkZa2B+htPD+P+5K/X6QQYWXym/4Zo` | +| ED25519 | 256 | `SHA256:8tZzRvA3Fh9poG7g1bu8m0LQS819UBh7AYcEXJYiPqw` | +| ED25519 | 256 | `SHA256:HHGCP5cf0jQbQrIRXjiC9aYJGNQ+L9ijOmJUueLp+9A` | +| ED25519 | 256 | `SHA256:Hyt6ox+v2Lrvdfl29jwe1/dBq9zh2fmq2DO6rqurl7o` | +| ED25519 | 256 | `SHA256:drShQbl3Ox+sYYYP+urOCtuMiJFh7k1kECdvZ4hMuAE` | +| ED25519 | 256 | `SHA256:h1oUNRkYaIycchUsyAXPQHnu6MtTF2YUEYuisu+vnOE` | +| RSA | 4096 | `SHA256:+550bmBCNAHscjOmKrdweueVUz2E6h1KzmSV+0c0U7w` | +| RSA | 4096 | `SHA256:1O7d6cdmqj42Dw4nX90Y+6zIFTUI+aIwD0SLMQuj0ko` | +| RSA | 4096 | `SHA256:AkHQnQXJ1lFEtliLHl8hlG7NiIZZgVn/uuRMCZJOKJk` | +| RSA | 4096 | `SHA256:Atxhx7U0MOuZC7e4vs1tpyTJmNttB7d4+HNC5hiavFo` | +| RSA | 4096 | `SHA256:Bla7GeL6hggg+rf6iDlKMrzIhxEBYB3VL7Q6PYGJYt4` | +| RSA | 4096 | `SHA256:H5ZhQ/5JdMPSG49ojUNEhwSuRD663mnIJb/YDFFntyk` | +| RSA | 4096 | `SHA256:TZr6eFrzoJmn4RS55Tb6yTd+WV9lTGtW0q+uLVbI7IE` | +| RSA | 4096 | `SHA256:ZYFb1AsB+q++NRf7yW8E5rNOfxTRwjpJt6hqFP/NBNs` | +| RSA | 4096 | `SHA256:d+nTyowvYtcxF28mCUu1ilqPJuLMExGyJ16Sv/pvoVY` | +| RSA | 4096 | `SHA256:flpv4s3VxOrQFc/IG+BpR1s9dgDvR07A6zunNqO4Co0` | +| RSA | 4096 | `SHA256:hvZN8rgSG82weLOeMTXdh1VwhjuRv+MJNnUt/X9R39g` | +| RSA | 4096 | `SHA256:ls20B8C6Jdqx7RPQAjzVX7KmnrHizJum2sEvNhMcl60` | +| RSA | 4096 | `SHA256:u1AzFc2AdFmlPRdNIZsn0sQJ/CKbfC2ZmXnQfabPek4` | +| RSA | 4096 | `SHA256:wUPBX3X5gALgxXqD+IwG5qPRb0jbiOZ8/U1BOZeNhtk` | +| RSA | 4096 | `SHA256:yRHC/tAlBpHLlRZ5rwbZ1z+159Bj3yg0VxHf+hXINLg` | +| RSA | 4096 | `SHA256:yhn79aqxOGQZ+LXdN1/vIY+jwRIbBamlVT1+HdFoA6o` | + +### From your favorite FTP client + +The **Add-on information** tab of your FS Bucket add-on displays the information +you need to connect to your bucket using FTP. diff --git a/content/doc/addons/heptapod.md b/content/doc/addons/heptapod.md new file mode 100644 index 000000000..3147e8d8e --- /dev/null +++ b/content/doc/addons/heptapod.md @@ -0,0 +1,229 @@ +--- +type: docs +title: Heptapod +description: Heptapod Cloud is a software factory based on Gitlab Community Edition, managed and hosted on Clever Cloud +tags: +- addons +keywords: +- hepatpod +- git +- mercurial +aliases: +- /doc/heptapod +--- + +{{< hextra/hero-subtitle style="margin:.3rem 0 2rem 0">}} + Heptapod Cloud and Runner is a SaaS DevOps platform, managed by Clever Cloud. It is based on the open source Heptapod, a variation of GitLab Community Edition supporting Git and Mercurial. +{{< /hextra/hero-subtitle >}} + +## Overview + +The Heptapod DevOps platform is edited by [Octobus](https://octobus.net), a team of experts with experience in Mercurial and Rust, derived from Gitlab Community Edition. + +Clever Cloud users can benefit from **Heptapod Cloud** software, along with **Heptapod Runner** for CI/CD operations. + +![A diagram on how the Heptapod Cloud and Runners interact with Clever cloud](/images/clever-cloud-runners-basic-with-runtimes-alt.svg 'Heptapod and Runners') + +## Heptapod Cloud + +Heptapod Cloud comes with the following benefits: + +* **Cost Reduction**: No licensing or application maintenance costs, flexible and competitive usage-based pricing per active user. +* **Automatic Updates**: Heptapod aligns with the continuously evolving GitLab, ensuring you effortlessly benefit from the latest features and security patches. +* **Technical and Functional Support**: Whether for technical or functional questions, support teams are ready to answer all your queries. +* **Scalability**: As your team grows or you manage dozens or hundreds of small or large projects for testing and deployment, Heptapod Cloud is designed to handle it. Increase capacities or quantities of CI/CD runners associated with your projects, those of runtimes, storage, or databases managed by Clever Cloud, or adjust bandwidth to handle heavy loads. All these services are native and structured to meet your scaling needs with ease. + +Heptapod Cloud provides your team with a suite of collaborative tools for software or document production management: + +* **Team, Collaborators, and Access Rights:** Add and manage team members, organise roles and access rights based on projects. +* **Git and Mercurial Repository Management:** Heptapod provides a robust and intuitive repository management system for Git and Mercurial, allowing you to effortlessly create, manage, and collaborate on your codebase or documents. With advanced version control and branch management features, you can easily track changes, merge your code, and maintain the integrity and history of your private or public projects. +* **Project Management and Ticket Tracking:** The ticket tracking system allows you to efficiently manage tasks, incidents, and collaborate seamlessly with your team. Stay organized by setting milestones, qualifying with labels, and customising workflows for advanced control of your operations. +* **Collaboration and Code Review:** Heptapod provides a wide range of features for effective collaboration, code or document reviews, online comments, and real-time collaboration tools. Work seamlessly with your team, track exchanges, merge requests, and improve the overall quality of your projects. +* **Embedded Wiki and Documentation:** Knowledge sharing is crucial for high-performing teams. Easily create and maintain comprehensive documentation for your projects, centralise and share knowledge, and provide a smooth experience for new collaborators. + +## Accessing Heptapod Cloud + +{{< callout type="info" >}} + **Requirements** + Using Heptapod Cloud require a Clever Cloud account and an [organisation](/developers/doc/account/administrate-organisation). +{{< /callout >}} + +{{% steps %}} + +### Create an organisation + +You will need a **Heptapod group** to create your projects in. **Heptapod groups** are mapped to Clever Cloud [organisations](/developers/doc/account/administrate-organisation/). +Every organisation you have access to will have its corresponding group on the Heptapod Cloud instance. + +In the Clever Cloud console, click **Add an organisation** and fill the form to create one. +organisation are the way users collaborate and share applications. + +### Access to Heptapod via SSO + +Accessing to Heptapod Cloud is done with the built-in of Clever Cloud. +To launch Heptapod Cloud go to ****. + +### Usage and billing + +Heptapod Cloud is billed on a per-usage model, explained and simulated [on our product page](https://www.clever-cloud.com/fr/product/heptapod-cloud/). + +You can check your Heptapod Cloud usage of repositories and users in the **Shared Software** tab of your organisation. + +![A screen capture of the Heptapod billing section](/images/heptapod-billing.png "You can check your organisation's Heptapod usage in the Shared Software section") + +Clever Cloud Runners for Heptapod enable on-demand generation of Docker containers of different sizes (Flavors). Therefore Heptapod runners are billed in the same way of runtimes. The pricing is different, and shown on a per-1000 minutes in the [Heptapod Runner product page](https://www.clever-cloud.com/product/clever-cloud-runners-for-heptapod/). + +{{% /steps %}} + +## Heptapod Runner + +Clever Cloud Runners for Heptapod is a SaaS that automates the execution of tasks on machines of varying sizes and power to best match your continuous integration and deployment needs. +Fully integrated with Heptapod Cloud, the service can also be used from a self-managed Heptapod or GitLab instance, either managed by Clever Cloud or self-hosted on your infrastructure. + +### Integrated CI/CD + +Clever Cloud Runners for Heptapod comes with the following features: + +* **Quick activation:** Activate Clever Cloud Runners for Heptapod for your organisation with just one click. +* **Easy customization:** Easily define your pipelines using templates for the most popular languages. Edit and validate definitions from the interface or directly from the project file. +* **Integrated tracking:** Monitor the execution of your tasks in real time, receive notifications of pipeline success or failure, and view activity reports online. +* **[Components Catalog](/developers/doc/ci-cd/gitlab/#deploy-directly-from-heptapod):** Connect your repository to Clever Cloud and deploy on production, create review apps, and automate tasks. + +#### Provisioning + +With the Clever Cloud Runner, you may run a great number of parallel jobs, paying for your actual consumption without any threshold effect. + +Each time it takes a job, the Clever Cloud Runner spawns a virtual machine within your Clever Cloud organisation. + +While the job is running, the virtual machine is visible in the Clever Cloud console, in which each job corresponds to an Application having exactly one instance attached. The instance is the virtual machine running the job. + +The type of the instance is "Heptapod Docker Runner", and is identified by a Heptapod icon. The job number is included of the Application name, which looks like hpd-job-kvzWdEMo-275833. + +Both Application and Instance are removed as soon as the job completes, whatever end status was returned to the coordinator. You will be billed for the time the instance was up, with a 10-second granularity. + +The pricing will vary on the selected flavour (size, see also below), which is "M" by default. Check it out on the Clever Cloud pricing page, under the "Heptapod Runner" section. + +#### Activation + +On heptapod.host, the Shared Runners are disabled by default at Group creation time, and Projects created while they are disabled on the Group also will have them disabled. + +This is nothing but the standard GitLab mechanism. If you maintain your own Group or Project runners, this makes sure the Clever Cloud Runner does not steal jobs from them, as chances are high that they would require a specific setup. Also, this avoids billing users for a service that they did not ask for and may not be aware of. + +In order to have the Clever Cloud Runner take your jobs, simply activate the shared runners on the wished Groups and Projects: + +* Navigate to the Group Settings CI/CD page. +* Expand the Runners section. +* You will be able to activate the shared runners directly from there or allow Projects or sub-Groups to override the Group setting in case you don't want to activate on the full Group. +* Always check the resulting configuration in the Projects Settings CI/CD pages, and correct it if needed. Changes in the Group Settings are not always immediately taken into account on enclosed Projects. + +#### Running only the Clever Cloud Runner + +In case you'd like to make sure that your jobs are taken by the Clever Cloud Runner, only, you can flag them with the `clever-cloud` job tag. + +Here is an example where the tag is set on all the jobs in the CI/CD configuration in one stroke, thanks to the `default` global keyword: + +```yaml +default: + tags: + - clever-cloud + +lint: + script: + - ci/lint + +tests: + script: + - ci/run-all-tests +``` + +#### Working like any Docker-based Heptapod or GitLab Runner + +Except for provisioning, everything happens as if the job was launched by a standard Docker executor, with only a handful of differences (see the dedicated subsection). + +{{< callout type="warning" >}} + For Git projects, there is no difference between Heptapod Runner and GitLab Runner +{{< /callout >}} + +To simplify, you can create a Docker image containing the required dependencies. You might store it on registry.heptapod.host and then use it as the starting point for your job. + +The job can make use of services, which will run inside the same virtual machine as the main job. + +Here's a full example making use of a PostgreSQL database, relying on the base image built by our Demo Project for CI image to provide the PostgreSQL client utilities (psql, createdb, etc.) + +```yaml +tests: + image: registry.heptapod.host/heptapod/demos/ci-image:latest + services: + - name: postgres:14 # official Docker image for PostgreSQL on Docker Hub + alias: pgserver # (optional) service host name to use from the job + variables: + # All job environment variables are also set in service containers. + # This one has the effect that postgres will blindly authenticate any + # existing user without any password. + # (the `postgres` image has many more authentication options, + # this one being good enough for our purposes) + # Note: GitLab (Runner) 14.5 will allow setting variables on a + # per-service basis, see https://docs.gitlab.com/ce/ci/services/ + POSTGRES_HOST_AUTH_METHOD: trust + script: + - createuser -h pgserver -dSR -U postgres db_owner + - createdb -h pgserver -U db_owner mydb + # Now use the database. + # This query just lists schemas (namepaces) for the sake of example. + - psql -h pgserver -U db_owner -c "SELECT nspname FROM pg_catalog.pg_namespace" mydb +``` + +##### Differences with a Heptapod Runner using the standard Docker executor + +**Automatic Dependency Proxy** + + The Dependency Proxy is a standard GitLab Free feature that provides transparent caching of Docker Hub images to minimize bandwidth and avoid rate limiting problems. + + With the Clever Cloud Runner, all Docker images from Docker Hub get automatically retrieved from heptapod.host's Dependency Proxy, By contrast, this is an opt-in feature with the standard Docker executor. + + The automatic Dependency Proxy should be mostly transparent to users, except in case of services using a namespaced Docker image and not having an explicit alias. For these, we provide a single service network name whereas the standard executor provides two (replacing forward slashes either by double underscores or dashes). We chose the dash-based RFC compliant one. In short, use octobus-heptapod to reach a service whose Docker image is octobus/heptapod:sometag, or better, set your own explicit alias. + +**Job cache** +Currently, the job cache is discarded at the end of each job. +This is because we don't have offloading capabilities for the cache yet, and the entire virtual machine gets decommissioned at the end of the job. + +We're working on it and should have a solution soon (see the Persistent cache upcoming feature). + +#### Isolation + +Because each job runs in its own transient virtual machine, your jobs are effectively pretty private. + +Even if a malicious job were to break the sandboxing provided by Docker itself, it would find nothing to spy on within its Docker host. + +Even if your projects are public, this can be an important factor, for instance to protect package signing keys and upload credentials when doing Continuous Delivery. + +#### Docker host flavors + +While most of the public CI offering seems to have converged on running jobs on comparatively modest systems (e.g., 2 virtual cores with 7GB of RAM), and many testing frameworks have ways to partition big test suites in several jobs to run in parallel (sharding), this does not fit all needs: + +Jobs performing big compilation tasks (OS kernels, desktop applications) may benefit from in-job parallelization and may not be practical to cut in several parallel jobs. +At the opposite side of the spectrum, jobs for unit tests or fast linting of small projects may content themselves with a tiny system. +In other words, one size does not fit all. + +Jobs executed by the Clever Cloud Runner can specify the scale (flavour) of the Docker host it needs, using the `CI_CLEVER_CLOUD_FLAVOR` variable. + +```yaml{filename=".gitlab-ci.yml"} +small-job: + variables: + CI_CLEVER_CLOUD_FLAVOR: XS + script: + - ci/display-specs + - ci/lint + +bigger-job: + # our base image provides /usr/bin/make + image: registry.heptapod.host/heptapod/demos/ci-image:latest + variables: + CI_CLEVER_CLOUD_FLAVOR: XL + script: + - ci/display-specs + - make all + artifacts: + paths: + - out/binaries +``` diff --git a/content/doc/addons/jenkins.md b/content/doc/addons/jenkins.md new file mode 100644 index 000000000..416bd9223 --- /dev/null +++ b/content/doc/addons/jenkins.md @@ -0,0 +1,265 @@ +--- +type: docs +title: Jenkins +description: This add-on provides a Jenkins master instance with a list of preinstalled plugins +tags: +- addons +keywords: +- Jenkins +- continuous integration +- continuous deployment +- ci/cd +- runner +aliases: +- /doc/deploy/addon/jenkins +- /doc/jenkins +--- + +Jenkins is an an open source automation server which enables developers to build, test, and deploy their software. It facilitates continuous integration (CI) and continuous delivery (CD). +You can find out more about Jenkins on [their website](https://www.jenkins.io). + +Jenkins on Clever Cloud will allow your team to effortlessly setup CI/CD pipelines, executed on runners that deploy on Clever Cloud docker applications. This way, you will only pay for the CI/CD you really consume, to the second. You will also be able to access Jenkins interface by using the Clever Cloud SSO (Single Sign-On) Authentication. + +!['Jenkins Dashboard'](/images/jenkins/full-dashboard.png 'The Jenkins dashboard') + +## Create Jenkins add-on + +### Jenkins versions + +Jenkins has two releases pipelines: Weekly and LTS (Long-term support). By default, our add-ons are using the LTS version of Jenkins, those will include all security fixes needed. +The Weekly version isn't available during the creation, yet, but if you ever need it, feel free to ask our support team about it. + +To create a Jenkins add-on, you can either use our web console or our CLI: + +### Web console + +1. Create a new add-on by clicking on the **Create…** dropdown in the sidebar and then **an add-on**. +2. Select the Jenkins add-on. +3. Select the plan you need. +4. You can skip linking the add-on to an application, it won't be needed. +5. Enter the name of your Jenkins add-on and select the zone where you wish to deploy it. +6. Select the options you wish to enable on your Jenkins add-on. + +### CLI + +1. Make sure you have clever-tools installed locally. Report to the [getting started](/developers/doc/cli/) guide if needed. +2. List the available plans and options for Jenkins: `clever addon providers show jenkins`. +3. In your terminal, you can then run `clever addon create jenkins --region --org ` where `app-name` is the name you want for your add-on, `region` deployment region, and `org` the organisation ID the application will be created under. + +Refer to the [documentation](/developers/doc/cli/applications/) for more details on application creation with Clever Tools + +## Accessing the Jenkins interface + +Once you created your add-on, you should get to the dashboard. You should see a link named `Access Jenkins`. Opening that link will redirect you to our SSO +authentication. + +{{% content "single-sign-on" %}} + +## Configure your Jenkins instance + +Once you accessed your Jenkins interface, we can start configuring it. A custom Clever Cloud plugin is automatically installed on your instance during the provisioning. +This plugin will allow you to configure the runners Jenkins will start to execute your jobs. Those runners will be Docker applications provisioned directly on Clever Cloud, in your organisation. + +### Configure your runners + +Using our Jenkins plugin, you can configure multiple runners. Runners can have multiple configuration customized: + +- Label: Only Jobs that require this label will be able to use that runner. [More on that below](#labels). +- Docker image: Select which docker image your job will use to run. [More on that below](#docker-image-requirements). +- Virtual machine size: The size of the Clever Cloud scaler to use. + +Before configuring the runners themselves, we have to configure a new Cloud. To do so: + +- Open the left menu, open the `Manage Jenkins` link. +- Then, under `System configuration`, open the `Manage nodes and Clouds` item. +- On the left menu, open the `Configure Clouds` link. +- A dropdown named `Add a new Cloud` should be displayed, select `Clever Cloud`. +- In the `Name` input field, you can enter `Clever Cloud`. +- You can also define a custom Docker registry to use with the associated credentials. Even if you stick with the default one (Docker Hub), we encourage you to add your credentials to avoid +any rate limiting. + +From there, we will be able to create runner templates. You can have multiple runner templates for multiple workflows. For example, you might need two runner templates: + +- One for building and testing your Java Maven projects. +- One for building and testing your Frontend projects. + +Let's configure a runner template for Java Maven projects: + +- Click on `Add a runner template`. +- Name your runner template, for example `Jenkins maven agent`. +- Set `maven` as the label. Jobs that require a `maven` runner will then be able to execute on this runner. +- Set the docker image your jobs will use. For example `jenkins/jnlp-agent-maven`. Be sure to read the [section about Docker image requiremetns](#docker-image-requirements). +- Select the virtual machine size you need. For Java projects, let's use a M instance that has 4 vCPUs and 8 GiB of RAM. + +!['Jenkins cloud configuration'](/images/jenkins/cloud-configuration.png 'A Jenkins cloud configuration') + +Once you configured everything, click on `Save` at the end. You should now have a runner template ready for Java Maven projects. + +We can now start configuring a new Job that will execute on a runner that will be started using the template we used. + +#### Labels + +Label is a very important setting. Labels will restrict on which runners a given project can be run. + +For example, if you have two runners templates with the following labels: + +- maven +- nodejs + +And you have two jobs: + +- A first job that builds and test a Java Maven project +- A second job that builds and test a frontend application + +The first job will be configured to only use the `maven` runners. And the second one will be configured to use the `nodejs` runners. + +You might also want to only have one runner template for all of your jobs. If you omit this setting both in the runner template and in the jobs settings, then this runner template will be +picked up to execute your jobs. + +#### Docker image requirements + +As of today, only runners on Clever Cloud Docker applications are supported. The Docker image you provide **must** contain the Jenkins Inbound agent. + +By default, Jenkins provides a few Docker images that embed this agent. The agent will then connect to Jenkins to receive jobs orders. + +You can find more details on the default [Jenkins Inbound agent](https://hub.docker.com/r/jenkins/inbound-agent/) Docker image. Jenkins also +provides various base images with pre-installed tools for some CI workflows on [Docker Hub](https://hub.docker.com/u/jenkins). + +If you have specific needs, you must create your own Docker image with the Jenkins Inbound Agent. + +### Configure and run a Job + +Jenkins has a large variety of options to configure a job. This documentation won't cover them all, we will just go through a basic Shell Job. For more information, you can +read [Jenkin's documentation](https://www.jenkins.io/doc/). + +In this example, the job will execute on a runner using the maven runner template we created earlier. It will basically print `Hello world` and `sleep` a bit. + +First, on the left menu, click on `New item`. This will open the available jobs types: + +- Enter a name for your project, let's say `My Maven Project` +- Select the `Freestyle project` option and click `Ok` +- We will use a Maven runner template we previously configured to execute the job: Tick the `Restrict where this project can be run` option and enter `maven` in the text field +- At the end of the settings, click on `Add a build step`, select `Execute shell` +- In the command shell input field, enter: + +```bash +echo 'Hello World!' +sleep 60 +``` + +- Save the settings. + +Now that the job is configured, we can start it by clicking on the `Build now` button in the left menu. A message saying that the build has been scheduled should be printed. +You should also see after a few seconds a pending Job in the `Build history`, on your left. + +!['Jenkins jobs history'](/images/jenkins/jobs-history.png 'The Jenkins' jobs history') + +At the same time, a new application should have been created in your organisation, named `Jenkins agent `. The application should be deploying and once it gets deployed, the job +will start to be executed. + +!['Deploying Jenkins runner'](/images/jenkins/runner-deploying.png 'A Jenkins runner while deploying') + +At some point the application should have deployed and you should be able to click on the Job's number in the `build history` list. From there, you can open the `Console Output` +which is basically your job logs. + +Once your job has ended, after the 1 minute sleep, the application provisionned in your organisation will be stopped and deleted. + +You should now be able to start creating jobs that automatically build and test your projects on a Clever Cloud application. + +### Jenkins File example + +Here is an example of a Jenkins file. It should be at the root directory of your project for Jenkins to pick it up. It basically builds our CLI project and publish it to various platforms. + +```bash +pipeline { + agent { label 'cc-ci-agent' } + environment { + GIT_TAG_NAME = gitTagName() + S3_KEY_ID = credentials('CELLAR_CC_TOOLS_ACCESS_KEY_ID') + S3_SECRET_KEY = credentials('CELLAR_CC_TOOLS_SECRET_ACCESS_KEY') + BINTRAY_API_KEY = credentials('BINTRAY_CC_TOOLS_API_KEY') + NPM_TOKEN = credentials('NPM_TOKEN') + } + options { + buildDiscarder(logRotator(daysToKeepStr: '5', numToKeepStr: '10', artifactDaysToKeepStr: '5', artifactNumToKeepStr: '10')) + } + stages { + stage('build') { + steps { + sh 'npm ci' + sh 'node scripts/job-build.js' + } + } + stage('publish') { + when { + not { + environment name: 'GIT_TAG_NAME', value: '' + } + beforeAgent true + } + parallel { + stage('cellar') { + steps { + sh 'node scripts/job-publish-cellar.js' + } + } + stage('npm') { + steps { + sh 'node ./scripts/job-publish-npm.js' + } + } + } + } + } + post { + always { + archiveArtifacts artifacts: 'releases/**/*', fingerprint: true, onlyIfSuccessful: true + } + } +} + +@NonCPS +String gitTagName() { + return sh(script: 'git describe --tags --exact-match $(git rev-parse HEAD) || true', returnStdout: true)?.trim() +} +``` + +You can find more documentation about the Jenkins file syntax on [Jenkin's Documentation](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/) + +## Customize your Jenkins instance + +Jenkins can be customized following your needs with a multitude of plugins. You can go into `Manage Jenkins` and then `Manage plugins` to manage them. + +Plugins can be browsed from [Jenkins own plugin repository](https://plugins.jenkins.io/). + +## Security and updates + +Jenkins usually gets a lot of security releases as well as many plugins updates. It is important to keep your Jenkins up-to-date. Today that's not something we automatically manage +but this may evolve in the future. In the meantime, you have full rights to update your Jenkins instance and its plugins. Usually, when Jenkins has a security release available, +it will be displayed as a notification and as a message in the `Manage Jenkins` administration page. + +The Clever Cloud Jenkins dashboard also has an item informing you about available Jenkins updates. + +!['Available Jenkins update'](/images/jenkins/update-available-cc-dashboard.png 'A Jenkins update is available') + +After Jenkins or some plugins were updated, Jenkins will need to restart. + +### Update Jenkins + +To update Jenkins, you can go into the `Manage Jenkins` administration page. If an update is available, it should ask you if you want to install it with a message looking like this: + +!['Jenkins update message'](/images/jenkins/update-available.png 'A Jenkins update message') + +You can then click on the `Or upgrade automatically` button. It should start downloading and installing the update. You can enable the option `Restart Jenkins when installation is complete and no jobs are running` and Jenkins will restart automatically. After a few minutes, it should be available again. + +### Update Jenkins plugins + +Plugins can be updated by going into the plugin management page: `Manage Jenkins` and then `Manage plugins`. + +Plugins that need to be updated are listed in the `Updates` section. You can check the plugins you need to update or check them all and then click on `Download now and install after restart`. + +All plugins will be downloaded. You can enable the option `Restart Jenkins when installation is complete and no jobs are running` and Jenkins will restart automatically and install the plugins updates. After a few minutes, it should be available again. + +## Backup + +By default, Clever Cloud performs a backup every day, with a retention of seven days. Retention and frequency can be customized for Premium customers. Backups can be found in the Clever Cloud Console in the `backups` menu of your add-on. diff --git a/content/doc/addons/keycloak.md b/content/doc/addons/keycloak.md new file mode 100644 index 000000000..01b177afc --- /dev/null +++ b/content/doc/addons/keycloak.md @@ -0,0 +1,219 @@ +--- +type: docs +title: Keycloak +description: This add-on provides a one-click Keycloak single sign-on and identity and access management (IAM) solution hosted by Clever Cloud, built with Please open-it +tags: +- addons +keywords: +- Keycloak +- IAM +- Security +- Authentication +- Identity +- OAuth +- OpenID +aliases: +- /doc/deploy/addon/Keycloak +- /doc/keycloak +--- + +Keycloak is an open source identity and access management (IAM) solution that offers powerful authentication features for services and secure applications. Thanks to this add-on, you can deploy Keycloak in your organisation in just one click. It leverages all Clever Cloud features such as monitoring, scalability, high availability SLA, etc. + +To fit the most common needs, the Keycloak add-on comes with batteries included: sensible defaults, easy migration with realms import/export, Keycloak Metrics, default theme, etc. + +{{< callout type="info" >}}Share your feedback on Keycloak operator through [our community page](https://github.com/CleverCloud/Community/discussions/categories/keycloak){{< /callout >}} + +## Key features +Keycloak on Clever Cloud allows you to effortlessly set up a tailored authentication and access management solution, that you can adjust to your needs and workloads. It offers a wide panel of services such as: +- Secure Identity Management +- Single Sign-On (SSO) +- Centralized Administration +- Customizable Authentication (OAuth 2.0, LDAP, SAML, OpenID Connect, and more…) +- Easily load plugins and themes +- Multi Realms +- Monitoring and Logging +- Export and Import +- Support and Maintenance + +## Need expert advice? + +The Clever Cloud Keycloak add-on is designed to meet the most common needs, built with [Please Open-it](https://please-open.it/) and hosted on our services. For the most complex and loaded systems, our partner and Keycloak experts behind this add-on, can provide assistance: [contact us](mailto:sales@clever-cloud.com). + +## How it works? +When you create the Keycloak add-on, Clever Cloud automatically deploys: + +- A [Java](/developers/doc/applications/java/java-jar) instance with Keycloak pre-loaded and configured +- A [PostgreSQL](/developers/doc/addons/postgresql) database +- A [FS Bucket](/developers/doc/addons/fs-bucket) used for themes, plugins, and import/export storage needs + +## Security and updates +Since the Keycloak add-on is a fully managed application, you don't have to select a particular version. It's automatically upgraded and updated both for features and security. + +An add-on update might require a rebuild. + +> Required actions are notified by email + +## Plan sizing + +By default, Keycloak on Clever Cloud uses small-size resources, i.e: + +- S Java +- XXS Small Space PostgreSQL +- Less than 100 MB in FS Bucket + +They are dimensioned to suit a majority of needs. Even if this Keycloak add-on might handle heavy traffic and an important number of simultaneous connections, the default configuration should handle the following load (based on [Keycloak](https://www.keycloak.org/high-availability/concepts-memory-and-cpu-sizing) sizing recommendation): +- 5 logins by second +- 90 credential grants by the second +- 70 refresh tokens by second + +You can however manage and adjust them directly in the Console to fit your needs. You can for example change their settings, migrate to a larger storage database, etc. Vertical auto-scalability is available for this service. [Different plans for Java and PostgreSQL](https://www.clever-cloud.com/pricing/) are available on Clever Cloud. + +## Create a Keycloak add-on + +### From the Console +1. [Create a new add-on](https://console.clever-cloud.com/users/me/addons/new) by clicking the **Create…** dropdown in the sidebar and then **an add-on** +2. Select the Keycloak add-on +3. You can skip linking the add-on to an application, it won't be needed +4. Enter a name for your Keycloak add-on and select the zone where you want it to be deployed + +### Using the CLI + +Make sure you have `clever-tools` installed locally. Please refer to the [setup guide](/developers/doc/cli/install/) if needed. In your terminal, run `clever addon create keycloak --org ` (`--org` is optional). You'll get URLs to manage your Keycloak instance and the temporary credentials: + +``` +$ clever addon create keycloak myKeycloak +Add-on created successfully! +ID: addon_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +Real ID: keycloak_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +Name: mykeycloak + +Your Keycloak is starting: + - Access it: https://xxxxxxxxxxxxxxxxxxxx-keycloak.services.clever-cloud.com + - Manage it: https://console.clever-cloud.com/addon_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + +An initial account has been created, you'll be invited to change the password at first login: + - Admin user name: cc-account-admin + - Temporary password: xxxxxxxxxxxxxxxx + +/!\ The keycloak provider is in beta testing phase +``` + +Refer to the [Clever Tools documentation](https://github.com/CleverCloud/clever-tools/tree/master/docs) for more details on add-on creation. + +## Version management + +To change the version of a Keycloak add-on on Clever Cloud, you can use the `CC_KEYCLOAK_VERSION` environment variable of its Java Application and rebuild it. But there are various ways to do it simpler with [Clever Tools](/developers/doc/cli/): + +```bash +# Set a specific supported version at creation +clever addon create keycloak --addon-version myKeycloak + +# Enable Operators commands +clever features enable operators + +# Check the current version +clever keycloak version check keycloak_name_or_id +clever keycloak version check keycloak_name_or_id --format json + +# Update to a specific supported version +clever keycloak version update myKeycloak +clever keycloak version update myKeycloak +``` + +- Learn more about [Operators commands in Clever Tools](/developers/doc/cli/operators/) + +## Accessing the Keycloak interface + +Once you have created your add-on, go to the Console Keycloak Java runtime page and click "Open the application". You also can get the Keycloak add-on URL from the Clever Cloud console, in the information panel of your Keycloak add-on. + +The admin interface is accessible on the `/admin` endpoint. The default user and password are provided in the Java application by the environment variables `CC_KEYCLOAK_ADMIN` and `CC_KEYCLOAK_ADMIN_DEFAULT_PASSWORD`. + +A password change is requested at the first connection. + +### Bootstrap admin client + +You can set up a new client with the `admin` role for `master` realm during build time using `CC_KEYCLOAK_BOOTSTRAP_ADMIN_CLIENT_ID` and `CC_KEYCLOAK_BOOTSTRAP_ADMIN_CLIENT_SECRET` environment variables of the Java application. Once created, delete the environment variables from your application. + +Bootstrap client [should be temporary](https://www.keycloak.org/server/bootstrap-admin-recovery) and is mostly necessary for provisioning. + +## Realms management + +The number of realms significantly impacts the overall performances. **Use as few realms as possible.** + +**The recommended way** to create realms is by using the environment variables of the Java application of the Keycloak add-on. Thus, it comes with an optimized configuration such as brute-force detection and specific metrics: + +- In the Java application, go to the `Environment variables` panel and in the `CC_KEYCLOAK_REALMS` environment variable, declare as many realms as you need, separated by a `,`. For example `CC_KEYCLOAK_REALMS=realm_1,realm_2` declares `realm_1` and `realm_2`. +- Restart the application after the change. + +You can also create a realm from the Keycloak administrator console. On the dropdown menu from the top left corner, click `create realm`. + +> [!NOTE] +> Starting with `26.2` release, Keycloak add-ons on Clever Cloud come with `admin-cli` client disabled by default. If you need it for provisioning through a `direct access grant`, you must enable it first. + +### Exporting realms data + +You can create a partial export using the Keycloak console: + +- From the `Realm Settings` panel +- On the top right, click the dropdown`action` menu +- Select `partial Export` +- A cold export can be done at the build + +You can create a full export using the environment variables of the Keycloak Java application: + +- Go to the Keycloak Java application in the Clever Cloud Console +- In the Java application, create the `CC_KEYCLOAK_EXPORT_REALMS` environment variable +- Set the realms you want to export, separated by a `,` +- Rebuild the Java application from the Clever Cloud console + +It's a total export, including the client's secrets and hashed password. Exported realms are available in `realms/export` folder of the FS Bucket. + +### Importing realms data + +Uploading previously exported data in `realms/import` folder in the associated FS Bucket enables importing realms data. The import process starts after rebuilding the Java application. + +## Custom Themes and Plugins + +Keycloak uses an [FSBucket](/developers/doc/addons/fs-bucket) to install themes and plugins. To deploy a custom theme or custom plugin, simply download them into the respective `themes` or `providers` folder in your FSBucket. + +## Add IP filtering in Keycloak for admin console + +Two specific authentication flows with an IP addresses based filter are especially created and affected as default to clients `security-admin-console` and `admin-cli`. To use them (do not forget to make the same on each realm you want to protect): + +- Enable "PLEASE-OPEN.IT Authenticator IP Range" to "Required" +- Click on the crank to access parameters +- Set IPs with authorized access + +Those flows could be affected to your own clients if you need. + +## Grafana dashboard & Metrics + +Since version `25.06`, Keycloak add-on exposes [Prometheus](https://prometheus.io/) metrics on port `9000`. Use Clever Cloud's [Grafana integration](/developers/doc/metrics/#publish-your-own-metrics) to visualize them. + +You can also use a Grafana dashboard ready to import, available starting with Keycloak `26.2` release: +- Go to the `Metrics in Grafana` section of your organisation or personal space in [Console](https://console.clever-cloud.com/) +- Open Grafana, click on the `+` icon in the upper right corner and select `Import` dashboard +- Import this [JSON file](https://cc-keycloak.cellar-c2.services.clever-cloud.com/keycloak-grafana-dashboard.json) + +Then you'll have a `Keycloak dashboard` in your Grafana folders. Just select your Keycloak add-on in the `runtime section`, you'll automatically get instance information, metrics, cache and performance data, etc. + +## Hostnames + +By default, your Keycloak instance is exposed through a Clever Cloud domain, as mentioned in the `Service dependencies` tab of your add-on. + +### Custom hostname + +You can use your own domain. [Just set it](/developers/doc/administrate/domain-names) in the `Domains` section of the Java application of the Keycloak add-on. Then, edit the `CC_KEYCLOAK_HOSTNAME` environment variable, apply this change and restart the application. + +### Admin hostname + +By default, Keycloak expose administration console on the same hostname, but [you can use another one](https://www.keycloak.org/server/hostname#_exposing_the_administration_console_on_a_separate_hostname). Add its domain to the application and set it through the `CC_KEYCLOAK_HOSTNAME_ADMIN` environment variable. Then apply this change and restart the application. + +## Known issues + +### Java application deployment may fail + +> Sometimes, application dependencies such as PostgreSQL may take a longer time to start. Wait and relaunch the deployment to fix this issue + +- On the `Overview` tab from the Java application page +- Click `RE-BUILD AND RESTART` diff --git a/content/doc/addons/mailpace.md b/content/doc/addons/mailpace.md new file mode 100644 index 000000000..307238bd7 --- /dev/null +++ b/content/doc/addons/mailpace.md @@ -0,0 +1,58 @@ +--- +type: docs +title: MailPace +description: MailPace is a fast & reliable transactional email +tags: +- addons +keywords: +- mailpace +- mail +- email +- smtp +aliases: +- /doc/deploy/addon/mailpace +--- + +MailPace is a fast & reliable transactional email. + +## Overview + +[MailPace](https://mailpace.com/) is an SMTP provider which can be used on Clever Cloud to send emails. + +MailPace provides an HTTPS API, SMTP Server and several libraries for sending emails that completely removes the need for any email setup or active email management. Emails sent through the MailPace API can come from any address for any domain that you are able to verify ownership of through a simple DNS update. + +## Add-on configuration + +Create the add-on from Clever Cloud's Console. You need to verify you domain name by adding the provided DNS entry in your DNS provider's dashboard. Then, you will get an `API KEY` that you should add to your application (as environment variable with PHP, see section below). + +- Host : `smtp.mailpace.com` +- Port : `25`, `465`, `587`, `2525` +- User : `API KEY` +- Password : `API KEY` +- Encryption : usage of `TLS` or `STARTTLS` are highly recommended. + +## MailPace for Erlang, Go, Node.js, Rust and Ruby + +Check [MailPace documentation](https://docs.mailpace.com/) + +## MailPace for PHP + +### PHP `mail()` function usage + +**You have to turn TLS on with port 465** (environment variable `CC_MTA_SERVER_USE_TLS=true`) to make Mailpace working. Enable `STARTTLS` allows to use another port. + +These environment variables have to be set with the value of : + +- `CC_MTA_SERVER_HOST`: Host of MailPace's SMTP server is `smtp.mailpace.com`. +- `CC_MTA_SERVER_PORT`: Server port has to be set to `465`. Defaults to `465` whether TLS is enabled or not. +- `CC_MTA_AUTH_USER`: User to authenticate to MailPace's SMTP server has to be set with `MAILPACE_API_KEY`. +- `CC_MTA_AUTH_PASSWORD`: Password to authenticate to the SMTP server has to be set with `MAILPACE_API_KEY`. +- `CC_MTA_SERVER_USE_TLS`: Have to be enabled. Defaults to `true`. +- `CC_MTA_SERVER_STARTTLS`: Enable or disable STARTTLS. Defaults to `false`. +- `CC_MTA_SERVER_AUTH_METHOD`: Authentication has to be enabled. Defaults to `on`. + +Then, redeploy your application on Clever Cloud for the changes to take effect. A few minutes later, your application will be able to send mails with `mail()` function thanks to MailPace's SMTP server. + +### PHP frameworks + +To use frameworks such as Symfony, you can check [MailPace documentation](https://docs.mailpace.com/integrations/php/symfony). diff --git a/content/doc/addons/materia-kv.md b/content/doc/addons/materia-kv.md new file mode 100644 index 000000000..2aeddbe17 --- /dev/null +++ b/content/doc/addons/materia-kv.md @@ -0,0 +1,229 @@ +--- +type: docs +title: Materia KV +description: Materia KV is a serverless key-value database, with high availability and open compatibility +tags: +- addons +keywords: +- materia +- kv +- dynamodb +- graphql +- redis +draft: false +aliases: +- /doc/addons/materia-db-kv/ +- /doc/materia-kv +--- + +Materia is a new serverless databases offering by Clever Cloud. A whole range of services meeting the needs expressed by our customers in recent years, with an open and resilient approach. It includes deployment across multiple availability zones, compatibility with existing protocols, clients, and pay-as-you-go billing. It's built on the [FoundationDB](https://www.foundationdb.org/) open source transactional engine. A distributed and robust solution, notably thanks to its high simulation capacity. + +Materia KV is the first publicly available product of this family. It's a key-value database which comes with simplicity in mind. You have no instance size to choose, no storage capacity to worry about. We simply provide you with a host address, a port and a token: you’re ready to go! Once our servers send a reply message, your data is durable: it's synchronously replicated over 3 data centers in Paris. + +You don't have to configure leaders, followers: high availability is included, by design. + +{{< callout type="info" >}} + +**Materia KV is in Alpha testing phase:** your insights and suggestions are crucial in shaping the future of this platform. To share your feedback, please visit us at [our community page](https://github.com/CleverCloud/Community/discussions/categories/materia). Thank you for being a part of our journey towards innovation and improvement! +{{< /callout >}} + +## Compatibility layers + +We didn’t want this Materia KV to come at the cost of complex configuration, requiring the use of special clients and ORMs. That’s why we’ve developed its compatibility layers. To “talk” to it, you don’t need a special API or tools specific to Clever Cloud. You'll be able to use it with existing solutions for **DynamoDB, GraphQL or Redis**. The first available layer is compatible with Redis API (and its variants as Reddict or Valkey). + +Thus, you can use a Materia KV add-on with any compatible client within your applications, `redis-cli` or alternatives such as [iredis](https://github.com/laixintao/iredis). You can also use it with graphical interface (GUI). We tested many of them with success: + +- [Another Redis Desktop Client](https://goanother.com/) +- [PX3 Redis UI](https://github.com/patrikx3/redis-ui) +- [Qredis](https://github.com/tiagocoutinho/qredis) +- [Redis Commander](https://github.com/joeferner/redis-commander) +- [Redis Insight](https://redis.com/redis-enterprise/redis-insight/) + +## Create a Materia KV add-on + +You can create a Materia KV add-on as simply as any other Clever Cloud service in the Console, [following this link](https://console.clever-cloud.com/users/me/addons/new). Select the Alpha plan (free during testing phase), an application to link to (or none), give it a name, and you'll get access to its dashboard giving you connection details. Environment variables shared with a linked application are listed in the `Service dependencies` section. + +We included them with the `REDIS_` format. Thus, you can just try to replace a Redis instance by Materia KV. It's as simple as linking the new add-on, unlinking the old one and restarting your application! (Check commands you'll need first). + +You can also use clever tools to create a Materia KV add-on and set environment variables to test it with a `PING` command: + +```bash +clever addon create kv DATABASE_NAME +source <(clever addon env addon ADDON_ID -F shell) +redis-cli -h $KV_HOST -p $KV_PORT --tls PING +``` + +Here is an example of what you can expect: + +``` +$ clever addon create kv testKV + +Add-on created successfully! +ID: addon_4997cfe3-f104-4d05-9fe4-xxxxxxxxx +Real ID: kv_01HV6NCSRDxxxxxxxxxxxxxxxx +Name: testKV + +/!\ The Materia KV provider is in Alpha testing phase, don't store sensitive or production grade data +You can easily use Materia KV with 'redis-cli', with such commands: +source <(clever addon env addon_4997cfe3-f104-xxxx-xxxx-xxxxxxxxx -F shell) +redis-cli -h $KV_HOST -p $KV_PORT --tls +``` + +You can also deploy Materia KV add-ons with [Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/latest/docs/resources/materiadb_kv) (OpenTofu compatible). + +{{< callout type="info" >}} + +**Materia KV is in Alpha testing phase** Each add-on is limited to 128 MB of storage, requests sent to the server can't exceed 5 MB. As we fine-tune and enhance its capabilities, we advise against using the alpha release for production purposes. During alpha testing we can delete data or renew token, don't store sensitive or production grade data. + +{{< /callout >}} + +{{% content "kv-explorer" %}} + +## Using the Redis API compatible layer + +### Environment variables and CLI usage + +To connect to a Materia KV add-on, you need 3 parameters: the host, the port and a ([biscuit](https://biscuitsec.org) based) token. You can set these parameters as environment variables by doing `source <(clever addon env addon ADDON_ID -F shell)`. The variables set are: + +* `$KV_HOST` and its alias `$REDIS_HOST` +* `$KV_PORT` and its alias `$REDIS_PORT` +* `$KV_TOKEN` and its alias `$REDIS_PASSWORD` +* `$REDIS_CLI_URL` +* `$REDISCLI_AUTH` + +You can directly use these environment variables to connect to a Materia KV add-on using `redis-cli` if `REDISCLI_AUTH` is set: + +```bash +redis-cli -h $KV_HOST -p $KV_PORT --tls +``` + +Materia KV is also compatible with alternatives such as [iredis](https://github.com/laixintao/iredis). + + +### Fish shell users + +If you use the Fish shell, you can use the following command to set the environment variables: + +```fish +clever addon env ADDON_ID -F shell | source +``` + +{{< callout type="info" >}} +By default, Materia KV uses TLS on the 6379 port. You can use non-TLS connections on the 6378 port for testing purposes. +{{< /callout >}} + +### Clever KV + +We're exploring how [Clever Tools](https://github.com/CleverCloud/clever-tools/) can natively support Materia KV and helps you to manage such add-ons without any additional software or configuration. The `clever kv` command is available since [version 3.11](https://github.com/CleverCloud/clever-tools/releases/tag/3.11.0). + +* [Learn more about Clever KV](/developers/doc/cli/kv-stores/) + +### Demos and examples + +We've prepared a few examples to help you get started with Materia KV: + +* [Materia KV Go client](https://github.com/CleverCloud/mkv-go-cli) +* [Materia KV raw TCP V demo](https://github.com/CleverCloud/mkv-raw-tcp-v) +* [Materia KV raw TCP Ruby demo](https://github.com/CleverCloud/mkv-raw-tcp-ruby) +* [Materia KV PHP sessions with TTL demo](https://github.com/CleverCloud/php-sessions-kv-example) +* +### Supported types and commands + +During this alpha stage, we don't provide 100% compatibility with the Redis API. Currently supported value types are: + +- String + +Find below the list of currently supported commands: + +|
Commands
| Description | +| ------- | ----------- | +| `APPEND` | If `key` already exists and is a string, this command appends the value at the end of the string. If `key` doesn't exist it is created and set as an empty string, so `APPEND` will be similar to `SET` in this special case. | +| `AUTH` | Authenticate the current connection using the biscuit token as `password`. | +| `CLIENT ID` | Returns the `ID` of the current connection. A connection ID has is never repeated and is monotonically incremental. | +| `COMMAND` | Return an array with details about every supported command. | +| `COMMAND DOCS` | Return documentary information about commands. By default, the reply includes all the server's commands. You can use the optional command-name argument to specify the names of one or more commands. The reply includes a map for each returned command. | +| `COMMAND INFO` | Returns an array reply of details about multiple Materia KV commands. Same result format as `COMMAND` except you can specify which commands get returned. If you request details about non-existing commands, their return position will be `nil`. | +| `COMMAND LIST` | Return an array of the server's command names. | +| `DBSIZE` | Return the number of keys in the currently-selected database. | +| `DECR` | Decrements the number stored at `key` by one. If the `key` doesn't exist, it is set to `0` before performing the operation. An error is returned if `key` contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64-bit signed integers. | +| `DECRBY` | Decrements the number stored at `key` by the given `decrement`. If the `key` doesn't exist, it is set to `0` before performing the operation. An error is returned if `key` contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64-bit signed integers. | +| `DEL` | Removes the specified `key`. A key is ignored if it doesn't exist. | +| `EXISTS` | Returns if `key` exists. | +| `EXPIRE` | Set a `key` time to live in seconds. After the timeout has expired, the `key` will be automatically deleted. The time to live can be updated using the `EXPIRE` command or cleared using the `PERSIST` command. | +| `FLUSHALL` | Delete all the keys of all the existing databases, not just the currently selected one. This command never fails. | +| `FLUSHDB` | Delete all the keys of the currently selected DB. This command never fails. | +| `GET` | Get the value of `key`. If the `key` doesn't exist the special value nil is returned. An error is returned if the value stored at `key` is not a string, because `GET` only handles string values. | +| `GETBIT` | Returns the bit value at offset in the string value stored at `key`. | +| `GETRANGE` | Returns the substring of the string value stored at `key`, determined by the offsets start and end (both are inclusive). Negative offsets can be used in order to provide an offset starting from the end of the string. So `-1` means the last character, `-2` the penultimate and so forth. | +| `HELLO` | Switch to a different protocol, optionally authenticating and setting the connection's name, or provide a contextual client report. It always replies with a list of current server and connection properties. | +| `INCR` | Increments the number stored at `key` by one. If the `key` doesn't exist, it is set to `0` before performing the operation. An error is returned if `key` contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64-bit signed integers. | +| `INCRBY` | Increments the number stored at `key` by the given `increment`. If the `key` doesn't exist, it is set to `0` before performing the operation. An error is returned if `key` contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64-bit signed integers. | +| `INFO` | The `INFO` command returns information and statistics about the server in a format that is simple to parse by computers and easy to read by humans. | +| `JSON.DEL` | Deletes JSON value at path from key. Returns the number of paths deleted. Can delete array elements or object fields. | +| `JSON.GET` | Gets JSON value at path from key. Supports both single and multiple path queries with different path notations. | +| `JSON.SET` | Sets JSON value at root path (`$`) and updating existing paths in key. Creates new key if it doesn't exist. | +| `KEYS` | Returns all keys matching `pattern`, can be `*` | +| `LOLWUT` | Returns Materia KV's version and might be hiding an easter egg 👀 | +| `MGET` | Returns the values of all specified keys. For every key that doesn't hold a string value or doesn't exist, the special value `nil` is returned. Because of this, the operation never fails. | +| `MSET` | Sets the given keys to their respective values. `MSET` replaces existing values with new values, just as regular `SET`. `MSET` is atomic, so all given keys are set at once. It is not possible for clients to see that some keys were updated while others are unchanged. | +| `PERSIST` | Remove the existing time to live associated with the `key`. | +| `PEXPIRE` | Set a `key` time to live in milliseconds. After the timeout has expired, the `key` will be automatically deleted. The time to live can be updated using the `PEXPIRE` command or cleared using the `PERSIST` command. | +| `PING` | Returns `PONG` if no argument is provided, otherwise return a copy of the argument as a bulk. | +| `PTTL` | RReturns the remaining time to live of a `key`, in milliseconds. | +| `SCAN` | Incrementally iterate over a collection of elements. It is a cursor based iterator, this means that at every call of the command, the server returns an updated cursor that the user needs to use as the cursor argument in the next call. An iteration starts when the cursor is set to `0`, and terminates when the cursor returned by the server is `0`. | +| `SET` | Set `key` to hold the string `value`. If key already holds a value, it is overwritten, regardless of its type. | +| `SETBIT` | Sets or clears the bit at offset in the string value stored at `key`. | +| `STRLEN` | Returns the length of the string value stored at `key`. An error is returned when key holds a non-string value. | +| `TTL` | Returns the remaining time to live of a `key`, in seconds. | +| `TYPE` | Returns the string representation of the type of the value stored at `key`. Can be: `hash`, `list` or `string`. | + +### JSON commands + +Materia KV provides preliminary support for JSON data type operations, compatible with Redis API JSON commands and clients. Unlike Redis JSON which uses a dedicated data type, our implementation works directly with classic string data types while maintaining API compatibility. + +#### Path Syntax and Behavior +- `$`: Root element (required for setting values, optional for `GET`/`DEL`) +- `$.field`: Access field in object +- `$..field`: Recursively search for all matching fields +- `$.array[index]`: Access array element by index +- `.field`: Shorthand notation (without `$`) returns a direct value instead of an array wrapper + +#### Examples + +```bash +# Setting and getting JSON +> JSON.SET myJsonKey $ '{"a":"23"}' +OK +> JSON.GET myJsonKey +"{\"a\":\"23\"}" +> JSON.GET myJsonKey $ +"[{\"a\":\"23\"}]" +> JSON.GET myJsonKey $.a +"[\"23\"]" + +# Multiple paths with different notations +> JSON.SET myJsonKey $ '{"f1":{"k1":["foo",42],"k2":["bar",53]},"f2":{"k1":["Hello",61]}}' +OK +> JSON.GET myJsonKey $.f1 $.f2 +"{\"$.f1\":[{\"k1\":[\"foo\",42],\"k2\":[\"bar\",53]}],\"$.f2\":[{\"k1\":[\"Hello\",61]}]}" +> JSON.GET myJsonKey .f1 .f2 +"{\".f1\":{\"k1\":[\"foo\",42],\"k2\":[\"bar\",53]},\".f2\":{\"k1\":[\"Hello\",61]}}" + +# Recursive search +> JSON.GET myJsonKey $..k1 +"[[\"foo\",42],[\"Hello\",61]]" + +# Array manipulation +> JSON.SET myJsonKey $ '{"a":[1,2,3,4]}' +OK +> JSON.DEL myJsonKey $.a[1] +(integer) 1 +> JSON.GET myJsonKey +"{\"a\":[1,3,4]}" +``` + +#### Current Limitations +- `JSON.SET` can only create new documents at root path (`$`) +- `JSON.SET` can't create new fields in existing documents +- Nested path creation is not supported (e.g., `$.new.child.field`) +- Keys in your JSON must not contains characters like `..`, `*`, `[?(` diff --git a/content/doc/addons/matomo.md b/content/doc/addons/matomo.md new file mode 100644 index 000000000..c024125f4 --- /dev/null +++ b/content/doc/addons/matomo.md @@ -0,0 +1,127 @@ +--- +type: docs +title: Matomo +description: This add-on provides a Matomo analytics solution based on existing Clever Cloud services +tags: +- addons +keywords: +- matomo +- web analytics +- google analytics +- privacy +- gdpr +aliases: +- /addons/matomo +- /doc/deploy/addon/matomo +- /doc/matomo +--- + +Matomo is an open source web analytics solution which gives you full ownership of your data. It's a [GDPR compliant](https://matomo.org/gdpr-analytics) alternative to Google Analytics. You can learn more about Matomo on [their website](https://matomo.org). Matomo on Clever Cloud allows your marketing team to setup a tailored web analytics solution, that adapts to your needs and workloads. + +{{< callout type="info" >}} +**Matomo is in Beta testing phase:** your insights and suggestions are crucial in shaping the future of this platform. +To share your feedback, visit [our community forum](https://github.com/CleverCloud/Community/discussions/categories/matomo). +Thank you for being a part of our journey towards innovation and improvement! +{{< /callout >}} + +## How it works? + +When you subscribe the Matomo add-on, we automatically setup a PHP instance based on the latest Matomo release. It comes with the required MySQL database and an optional Redis cache. + +We have chosen to let you see and manage these companion add-ons in the Console so that you could adjust them to your needs. You can change their settings and use the Clever Cloud ability to migrate from an S flavored database or cache to an L or XL if required. You can also activate auto-scalability (horizontal and/or vertical scaling). + +By default, Matomo on Clever Cloud comes with small sized resources: + +- PHP Nano +- MySQL XXS BigStorage +- Redis S + +We've already integrated the Clever Cloud SSO, so you can login directly into your Matomo instance from the Console, start to integrate your website, create different users. + +## Create Matomo add-on + +### From the Console + +1. Create a new add-on by clicking on the **Create…** dropdown in the sidebar and then **an add-on**. +2. Select the Matomo add-on. +3. You can skip linking the add-on to an application, it won't be needed. +4. Enter the name of your Matomo add-on and select the zone where you wish to deploy it. +5. It's done! + +### Using the CLI + +Make sure you have `clever-tools` installed locally. Please refer to the [setup guide](/developers/doc/cli/install/) if needed. In your terminal, `clever addon create addon-matomo --region --org ` (`--org` and `--region` are optional). You'll get URLs to manage your Matomo instance: + +``` +$ clever addon create addon-matomo myMatomo +Add-on created successfully! +ID: addon_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + +Real ID: matomo_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +Name: myMatomo + +Your Matomo is starting: + - Access it: https://xxxxxxxxxxxxxxxxxxxx-matomo.services.clever-cloud.com + - Manage it: https://console.clever-cloud.com/addon_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + +/!\ The addon-matomo provider is in beta testing phase +``` + +Refer to the [Clever Tools documentation](/developers/doc/cli/addons/) for more details on add-on management. + +## Accessing the Matomo interface + +Once you created your add-on, open the management URL or use the `Access Matomo` link in the Matomo dashboard from the Console. To authenticate, you'll only need to use your Clever Cloud account. + +{{% content "single-sign-on" %}} + +## Configure your Matomo instance + +Once you accessed your Matomo interface, we can start configuring it. A custom Clever Cloud configuration is automatically installed on your instance during the provisioning. + +This configuration helps you to benefit from optimizations by using a Redis cache by default. + +### Using your Matomo + +If you're new with Matomo, you would probably want to read the Matomo's guides on [the official documentation](https://matomo.org/guides/). + +## Matomo plugins + +Your Matomo instance comes with a list of pre-installed plugins. As a managed instance, our Matomo add-on won't let you bypass the installation process. Installed plugins already allows a quite advanced use of Matomo, but if you wish to install a specific plugin that's not in your instance, feel free to contact our support team. + +### When activating a deactivated plugin + +Keep in mind that some plugins might consume more resources than you have by default on your PHP instance, since some PHP processes can take a long time, depending on what you are doing. + +If you activate a deactivated by default plugin (like [GoogleAnalyticsImporter](https://matomo.org/guide/installation-maintenance/import-google-analytics/)): + +- Scale your PHP app +- Disable auto-scalability for the PHP app +- Scale your Matomo MySQL add-on + +If you activate the plugin while enabling auto-scalability, your PHP instance will restart with default settings when scaling, therefore disabling the plugin and killing the process. + +Plugins can be browsed from [Matomo own plugin repository](https://plugins.matomo.org/). + +{{< callout type="warning" >}} +Plugin files are removed every time your instance reboots. **This means you have to reinstall them all again after every reboot.** This is temporary, and it is something we plan on improving as soon as we can. +{{< /callout >}} + +### QueudTracking + +By default, the `QueudTracking` plugin is enabled on Matomo instances, with a queue size of `25`. This means that the plugin stores 25 visits in a queue before they appear in Matomo. This helps to prevent the server from receiving too many request at once. You can change this setting by modifying the **Number of requests that are processed in one batch** parameter in **Administration->System->General settings**. + +## Delete old archive + +By default, Matomo isn't configured to delete the data that it receive. This can cause the databases to accumulate a lot of old data that may not be useful anymore and completely fill the databases. +To resolve this issue, you can setup and automatic deletion of old achives in Matomo settings. + +To do this, you must go to the **Anonymize data** menu in **Administration->Privacy->Anoymize data**. You have two option you can activate to delete old achives, `Regularly delete old raw data` and `Delete old aggregated report data`. When you activate one of those options, you can select how old the date needs to be for it to get deleted. When one of the two options is activated, you can schedule the frequency (every day, month, year) at which you wish to delete the data in **Schedule old data deletion**. + +## Security and updates + +The Matomo add-on is a fully managed application, you don't have to select a particular version. Clever Cloud updates it for both features and security, and manages it continuously to apply regular version upgrades. After being updated, you Matomo add-on could need to be restarted. + +## Plans + +Matomo on Clever Cloud is the easiest way to set it up, but you can go further and adjust the flavor of your instance, database or cache independently. We provide [different plans for PHP, MySQL and Redis](https://www.clever-cloud.com/pricing/). diff --git a/content/doc/addons/metabase.md b/content/doc/addons/metabase.md new file mode 100644 index 000000000..7b35c5487 --- /dev/null +++ b/content/doc/addons/metabase.md @@ -0,0 +1,237 @@ +--- +type: docs +title: Metabase +description: This add-on provides a one-click Metabase (Business Intelligence, Dashboards, and Data Visualization) instance hosted by Clever Cloud +tags: +- addons +keywords: +- metabase +- business intelligence +- BI +- dashboard +- data visualization +- dataviz +aliases: +- /doc/metabase +--- + +[Metabase](https://www.metabase.com/) is an open source Business Intelligence server that connects to MySQL, PostgreSQL, MongoDB, and more! Anyone can use it to build charts, dashboards, nightly emails or Slack reports. Thanks to this add-on, you can deploy Metabase in your organisation in just one click. It leverages all Clever Cloud features such as monitoring, scalability, high availability SLA, etc. + +{{< callout type="info" >}}Share your feedback on Metabase operator through [our community page](https://github.com/CleverCloud/Community/discussions/categories/metabase){{< /callout >}} + +## Key features + +Metabase on Clever Cloud is a preconfigured set of resources, benefiting from all features the platform provides such as monitoring, scalability, up-to date systems, blue/green deployments, etc. It's easy to manage and allows you to make better sense of the business metrics produced by your application. Once deployed, Metabase takes form of a web application in which you can: + +- Navigate and **explore data** in the connected databases +- Create **dashboards** that regroup multiple questions in a canva +- **Integrate** questions/dashboards in another application +- **Share** a questions/dashboard to anyone using an anonymous link +- **Periodically send** results of a question/dashboard by email/Slack +- Configure **data visualization** for questions results: table, line chart, pie chart, gauge, single number, etc. +- Connect **external databases**; it works with add-ons such as [MySQL](/developers/doc/addons/mysql/), [PostgreSQL](/developers/doc/addons/postgresql/), [MongoDB](/developers/doc/addons/mongodb/) and [many other data sources](https://www.metabase.com/data-sources/) +- Create _questions_ either by typing in `SELECT` SQL queries or by using Metabase’s UI to build such queries **without using SQL** + +You can also save questions and **organize** them in _collections_. When opening a saved question, fresh data is extracted from the source DB, so that questions always show fresh results. You get user management with **groups and permissions**: users can access to whole data sources so that they can explore and create questions, or they can have access only to collections containing already existing questions/dashboard. + +## Create a Metabase add-on + +### From the Console + +1. [Create a new add-on](https://console.clever-cloud.com/users/me/addons/new) by clicking the **Create…** dropdown in the sidebar and then **an add-on** +2. Select the Metabase add-on +3. You can skip linking the add-on to an application, it won't be needed (connecting data sources to Metabase is done via Metabase's UI) +4. Enter a name for your Metabase add-on and select the zone where you want it to be deployed + +### Using the CLI + +Make sure you have `clever-tools` installed locally. Please refer to the [setup guide](/developers/doc/cli/install/) if needed. In your terminal, run `clever addon create metabase --org ` (`--org` is optional). You'll get URLs to manage your Metabase instance and the temporary credentials: + +``` +$ clever addon create metabase myMetabase +Add-on created successfully! +ID: addon_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +Real ID: metabase_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +Name: myMetabase + +Your Metabase is starting: + - Access it: https://xxxxxxxxxxxxxxxxxxxx-metabase.services.clever-cloud.com + - Manage it: https://console.clever-cloud.com/addon_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + +/!\ The metabase provider is in beta testing phase +``` + +Refer to the [Clever Tools documentation](/developers/doc/cli/addons/) for more details on add-on management. + +## Accessing the Metabase interface + +Once you created your add-on, open the management URL or look for `MB_SITE_URL` value in the Metabase dashboard from the Console. The first time you connect, you will be taken to a wizard to create the first user, data sources, etc. Then you can configure and use it. + +* [Learn how to use Metabase](https://www.metabase.com/learn/metabase-basics/getting-started/find-data) + +## Password reset + +To be able to reset your password, you must have [set up an active SMTP server](#configuring-a-smtp-server) in the `e-mail` section of the administrator settings. You can also do it [using a Mailpace add-on](#using-a-mailpace-add-on). Once done, the forgot password procedure will ask you the user email address and send a reset link to it. + +If you don't have an active SMTP server configured, there is a manual procedure to get the reset link: + +{{% steps %}} + +### Identify the Java application of your Metabase add-on + +Its name is the same as the add-on name, followed by the add-on ID. + +### Go to its environment variables page and add the password reset command + +Add a `CC_PRE_RUN_HOOK` environment variable with this value (replace `email@example.com` with your own address): + +``` +MB_DB_CONNECTION_URI="$POSTGRESQL_ADDON_URI" java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar reset-password email@example.com +``` + +Press `Update changes` and restart the Java application. + +### Get the reset token + +In the applications logs, during the application start, you'll see a line like `OK [[[TOKEN]]]` + +### Reset the password + +Go to the Metabase instance URL followed by `/auth/reset_password/TOKEN` and reset the password + +### Clean up + +Remove the `CC_PRE_RUN_HOOK` environment variable from the Java application and restart it + +{{% /steps %}} + +## Underlying resources + +When you create the Metabase add-on, Clever Cloud automatically deploys: + +- A [Java](/developers/doc/applications/java/java-jar/) instance with Metabase pre-loaded +- A [PostgreSQL](/developers/doc/addons/postgresql/) database (for internal Metabase use) + +## Plan sizing + +By default, Metabase on Clever Cloud uses small-size resources, i.e: + +- XS Java +- XXS Small Space PostgreSQL + +They are dimensioned to suit a majority of needs. You can however manage and adjust them directly [in the Console](https://console.clever-cloud.com/). For example when you have multiple users loading large dashboards concurrently or if your instance experiences crashes due to Out of Memory (OOM) issues, you should use a larger flavor for the Java application or activate auto-scalability. The PostgreSQL database is not likely to be needed a larger plan, but should this happen you can migrate it using Clever Cloud's Console. + +## Version management, Security and Updates + +The Metabase add-on is a fully managed application, so you don't have to do anything to update it: by default **it is automatically updated** to match the latest Community Edition release. Your add-on will be automatically restarted when a new Metabase release is available, but thanks to Clever Cloud this will be done without downtime. All deployed versions are reviewed and tested before being released. + +Of course, you have full control other this. The Java application of your Metabase add-on contains a `CC_METABASE_VERSION` environment variable, but there are various ways to do it simpler with [Clever Tools](/developers/doc/cli/): + +```bash +# Set a specific supported version at creation +clever addon create metabase --addon-version myMetabase + +# Enable Operators commands +clever features enable operators + +# Check the current version +clever metabase version check metabase_name_or_id +clever metabase version check metabase_name_or_id --format json + +# Update to a specific supported version +clever metabase version update myMetabase +clever metabase version update myMetabase +``` + +- Learn more about [Operators commands in Clever Tools](/developers/doc/cli/operators/) + +If you use `CC_METABASE_VERSION` it can contain a value that is either a special keyword or a [SemVer](https://semver.org/) version requirement (the only difference with SemVer is that `x.y.z` is interpreted as `=x.y.z` instead of `^x.y.z`.): + +- `community-latest` (_default_): use the latest version of the Community Edition (_same as `0`, `0.*`, `^0` or empty_) +- `0.55.1`: use the `0.55.1` version (_same as `=0.55.1`_) +- `0.55`: use the latest available version starting with `0.55` (_same as `^0.55.0`, `~0.55.0`_) + +To update Metabase manually, you **should** restart the Java application without the build cache, using the `re-build and restart` button in the [Console](https://console.clever-cloud.com/) or the `clever restart --without-cache` command of [Clever Tools](/developers/doc/cli/applications/deployment-lifecycle/#restart). + +The Metabase JAR is stored in the build cache so that no time is wasted re-downloading it every time you restart the application (or it is restarting as part of a scaling event). This also makes the service more resilient: should the download be temporarily failing for any reason, this would not prevent restarting/scaling your add-on. + +{{< callout type="warning" >}} +**With great power comes great responsibility.** If you choose to fix your add-on to a specific version (for example, `0.55.3`) or a specific "branch" (for example, `0.55`), you must make sure that this version/branch does not become obsolete (new Metabase versions that patch critical security issues may be released but not used in your add-on because you specified otherwise). +{{< /callout >}} + +- [The Atom feed (XML) of latest versions and their changelog](https://cc-metabase.cellar-c2.services.clever-cloud.com/metabase_releases.xml) +- [The TOML list of all available versions and their changelog](https://cc-metabase.cellar-c2.services.clever-cloud.com/metabase_releases.toml) + +### Using Metabase Enterprise Edition + +Metabase provides an Enterprise Edition (EE) that offers [more features](https://www.metabase.com/docs/latest/paid-features/overview) but requires a license key that must be purchased through their website (see the [pricing page](https://www.metabase.com/pricing/)) EE versions are usually released at the same time as Community Edition (CE) versions, starting with a `1` instead of a `0`. + +If you wish to deploy an EE version on your Clever Cloud add-on, `CC_METABASE_VERSION` environment variable to either use a fixed version/branch that starts with `1` (for example: `CC_METABASE_VERSION=1.55`) or `CC_METABASE_VERSION=enterprise-latest`. + +You must then add your license key in Metabase's settings (see [documentation](https://www.metabase.com/docs/latest/paid-features/activating-the-enterprise-edition#how-to-activate-your-token-when-self-hosting)). + +### Version rollbacks + +There is nothing stopping you from rolling back your Metabase instance to an older version (using the `CC_METABASE_VERSION` environment variable), but **this may break things**. When starting, Metabase checks its attached internal PostgreSQL database and may apply database migrations to evolves its structure. But not all new versions of Metabase add new migrations (patch versions may not, thus this is not a contract). + +There are two cases: + +1. A version does not add migrations: rolling-back to the previous version can be done without complications +2. A version adds migrations: rolling-back may or may not work. An older Metabase software is not guaranteed to work with a new database structure, so this could break the whole instance, some features or cause data loss. + +{{< callout type="info" >}} +**Rollbacks are not officially supported.** +If you need to rollback to an older version (for example, because a new version introduced a blocking regression), it is your responsibility to check if this can be done safely. +{{< /callout >}} + +## Credentials at-rest encryption + +When you add a new data source to Metabase, its credentials are stored into Metabase internal database. Metabase offers an [optional feature](https://www.metabase.com/docs/latest/databases/encrypting-details-at-rest) that allows you to encrypt such credentials before storing them in the database. + +When you deploy a Metabase add-on, this **at-rest encryption is enabled by default**. +This is why the Java app of your add-on has a `MB_ENCRYPTION_SECRET_KEY` environment variable that contains a randomly generated value. + +## Configuring a SMTP server + +While this is not strictly required to successfully operate Metabase, it might be useful to configure a SMTP server. +There are two main usages: + +1. Sending user management/security emails (new user connections, account recoveries, invitations, …) +2. Sending questions/dashboards emails (when users created subscriptions to them) + +Clever Cloud does not provide a SMTP server for your Metabase add-on. +You can use a [MailPace](/developers/doc/addons/mailpace/) add-on or any other SMTP server. + +The SMTP server can be configured (and tested) in Metabase administration interface. +See [documentation](https://www.metabase.com/docs/latest/configuring-metabase/email) for more details. + +### Using a MailPace add-on + +If you have a [MailPace](/developers/doc/addons/mailpace/) add-on, you can link it to the Java application of your Metabase add-on using [Clever Cloud's console](https://console.clever-cloud.com/): + +- Go to the Java application of the Metabase add-on +- Open the "Service dependencies" page +- In the "Linked add-ons" section, select your MailPace add-on and click "Add" +- Restart the Java application of your Metabase add-on + +When a MailPace add-on is linked, Metabase will automatically get the SMTP server and credentials using (hidden) environment variables. In this case, SMTP settings will **not** be editable from Metabase interface; just unlink the MailPace add-on if you prefer to edit them manually. + +You still need to specify the email address which Metabase must use as sender (use Metabase administration interface or set the `MB_EMAIL_FROM_ADDRESS` environment variable). Make sure you MailPace account is able to send email from this address/domain. + +## Migrating from a self-hosted instance + +Even if you already have a self-hosted Metabase instance, you might want to migrate to the Metabase add-on in order to benefit from automatic upgrades. This is possible if your self-hosted instance uses PostgreSQL as its internal database. + +Here is how you can do it: + +1. Create an instance of the Metabase add-on in your Clever Cloud organisation +2. In the add-on Java application, set `CC_METABASE_VERSION` to the same version as your existing self-hosted instance +3. In the add-on Java application, set `MB_ENCRYPTION_SECRET_KEY` to the same value as it is in your existing self-hosted instance (or let it to its current random value if you did not enable credentials encryption in your existing self-hosted instance) +4. Stop the Java application of your Clever Cloud add-on +5. Stop your self-hosted instance (but let its database up!) +6. Use `pg_dump` to export the whole internal database of your self-hosted instance: `pg_dump -d postgresql://[your-self-hosted-instance-connection-URI] --format c --compress 7 --schema public --verbose > metabase.backup` +7. Use `pg_restore` to restore the dump to the PostgreSQL database of your Clever Cloud add-on: `pg_restore -d postgresql://[your-addon-database-connection-URI] --no-owner --clean --if-exists --schema public --verbose metabase.backup` +8. _(optional)_ Configure the Java application domain and update your DNS record accordingly; if you use a custom domain, you should also update the `MB_SITE_URL` environment variable (it defines the base URL used by links in Metabase emails, among other things) +9. Start the Java application of your Clever Cloud add-on (without build cache) + +If everything seems OK, set `CC_METABASE_VERSION` to the value you wish (for example, `community-latest`) in the Java application of your Clever Cloud add-on and restart it. [Contact the Clever Cloud support](https://console.clever-cloud.com/ticket-center-choice) if you need advice or help doing that. diff --git a/content/doc/addons/mongodb.md b/content/doc/addons/mongodb.md new file mode 100644 index 000000000..b4f3a5e74 --- /dev/null +++ b/content/doc/addons/mongodb.md @@ -0,0 +1,101 @@ +--- +type: docs +title: MongoDB +description: A noSQL and document-oriented database, operated by Clever Cloud +tags: +- addons +keywords: +- mongo +- mongodb +- document +- nosql +- database +aliases: +- /deploy/addon/mongodb/mongodb +- /doc/mongodb +- /doc/deploy/addon/mongodb +- /doc/deploy/addon/mongodb/mongodb +- /doc/deploy/addon/mongodb/managing-mongodb +- /doc/mongodb-hosting +--- +## Overview + +MongoDB is an open source NoSQL document-oriented database. We provide these databases with daily backups and monitoring for both shared and dedicated plans. + +## Supported Versions + +In order to comply with [MongoDB Server Side Public License](https://www.mongodb.com/licensing/server-side-public-license), the version currently installed by the add-on is: + +{{< software_versions_shared_dedicated mongo>}} + +### Higher Versions + +If you purchased a higher version from MongoDB and you want to deploy your database on Clever Cloud, [contact us](https://www.clever-cloud.com/contact/). + +{{< callout type="warning" >}} +DEV plan is no longer available for MongoDB. +{{< /callout >}} + +### Important note about fair use on DEV plans + +Heavy usage of DEV databases may impact the shared cluster they rely upon. It will degrade performance of the other databases. To that extent, DEV plan has a limit of **15 operations/second**. Going above the limit might disconnect your database. + +{{% content "db-backup" %}} + +## Database Migration Process + +The migration process is pretty much the same for each of these cases: + +- migrating from a Clever Cloud shared database to a dedicated one +- migrating from an external database to a Clever Cloud one +- migrating between Clever Cloud Databases + +The process consists in three steps: + +1. First, perform a backup and download it, either with the Clever Cloud add-on dashboard or the `mongodump` command from your workstation. +2. Install `mongorestore` (a tool packaged with [MongoDB](https://docs.mongodb.com/manual/administration/install-community/)) +3. On your workstation, use the taylor-made `mongorestore` command line located in your mongodb dashboard page (open the "Backup" panel and click on the "Restore" link to find the complete command line to perform the database import). If needed, change the `nsFrom` and `nsTo` flags, depending on what you actually want to do (importing this database in another, importing another to this one, …). + +## Encryption at rest + +Encryption at rest is available on MongoDB. You can have more information on the [dedicated page](/developers/doc/administrate/encryption-at-rest) + +{{% content "db-migration" %}} + +## Can I use Mongo Ops Manager on Clever Cloud? + +To be able to use [Mongo Ops Manager](https://www.mongodb.com/products/ops-manager), you'll need a valid MongoDB Enterprise Advanced subscription and to deploy a [Linux version of their manager solution](https://www.mongodb.com/try/download/ops-manager). If you haven't purchased any license from MongoDB and you are using the Community version, you might be looking for a similar service for your databases. + +### Does Clever Cloud provide a similar service? + +The features available with Mongo Ops Manager could be relevant if you managed your infrastructure and the maintenance of your MongoDB databases yourself. However, if you use Clever Cloud to access our Mongo add-ons, you are already opting for a managed service, and will therefore benefit from the following features similar to Mongo Ops Manager: + +- **A centralized interface** to access your database settings and perform operations on them. +- **A monitoring and alert system** that can be configured with Grafana. See ([this example with Slack alerts](https://www.clever-cloud.com/blog/features/2021/12/03/slack-alerts-for-grafana/)). +- **A backup and restore system** already configured for our add-ons (customizable upon request) with easy migration and one-click importation. +- The ability to **automate tasks** with our CLI. +- **Enhanced security** through our default access management on Clever Cloud (encryption at rest, default unauthorized super admin operations, etc.). + +Note that these features are available for all our databases add-ons, in addition to MongoDB. + +**The managed databases provide an advantage if you want to avoid the complexity of installing and deploying databases** and if you want simple-to-use management and monitoring tools. + +## 🔑 Rights and permissions + +Add-ons are managed services, meaning that users have **standard access** to the database (role **owner**). Some operations like databases and users creation, as well as some settings modifications aren't available by default. This ensures optimal performances and security for managed services as configured by Clever Cloud. + +Authorized actions: +- Manage collections (create, delete…). +- Manage indexes. +- Manage documents. + +If you think your system might require more advanced administrative access, [contact Clever Cloud support](https://console.clever-cloud.com/ticket-center-choice) to explain your use case, and we will work with you to find a solution. + +Here is the list of actions that you won't be able to perform: +- Database administration (for example you won't be able to create new databases). +- Users administration (you won't be able to create other users than the one handled with our control plane, ie the base owner and read-only users). +- Server configuration update. +- Cluster creation. +- Backup frequency or retention control. + +Ask Clever Cloud support if you want to perform one of these actions. diff --git a/content/doc/addons/mysql.md b/content/doc/addons/mysql.md new file mode 100644 index 000000000..6e696fee6 --- /dev/null +++ b/content/doc/addons/mysql.md @@ -0,0 +1,89 @@ +--- +type: docs +title: MySQL +description: MySQL is an open source relational database management system (RDBMS) +tags: +- addons +keywords: +- sql +- mysql +- mariadb +- RDBMS +aliases: +- /doc/mysql +- /doc/add-ons/mysql +- /doc/databases/mysql +- /doc/deploy/addon/mysql +- /doc/deploy/addon/mysql/mysql +- /doc/en/mysql-hosting +--- +## Overview +MySQL is an open source relational database management system (RDBMS). Clever Cloud's add-on uses the [Percona Server](https://www.percona.com/mysql/software/percona-server-for-mysql), a 100% compatible open source implementation, with performances improvements and more features. + +## Supported Versions + +MySQL is available in regular versions and `early` for 8.4. That means it's the first release (8.4.0) of this long term support (LTS) branch, so you should consider it mostly to make some tests and discover what's new. But we recommend waiting a bit before using a new branch in production. + +{{< software_versions_shared_dedicated mysql>}} + +{{% content "db-backup" %}} + +## Migrating from an old database + +Some applications require a populated database to run properly. +If you want to import your **SQL** dump, you can use several methods: + +1. [The WebGUI (PhpMyAdmin)](https://pma.services.clever-cloud.com/). +2. Command line tool for MySQL administration +3. Any MySQL client such as [MySQL Workbench](https://www.mysql.fr/products/workbench/) + +If you need to import a very large dump, contact [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice). + +{{% content "db-migration" %}} + +## Direct access + +{{< callout type="warning">}} +Using direct access is a trade-off: if you migrate your add-on, you will need to generate the hostname and port again, so your application will need to update that environment, while using a proxy does not change anything. +{{< /callout>}} + +All our dedicated MySQL databases are served via a proxy. To reduce the latency you can bypass this proxy by generating direct hostname and port for the add-on. You can do it by clicking the "Generate direct hostname and port" on the add-on dashboard. + +This action will add new environment variables to reach the add-on without any proxy. + +## Encryption at rest + +Encryption at rest is available on MySQL. You can have more information on the [dedicated page](/developers/doc/administrate/encryption-at-rest). + +## ProxySQL + +{{% content "proxysql" %}} + +You can learn more about ProxySQL on the [dedicated documentation page](/developers/guides/proxysql) + +## Plans + +{{< callout type="warning" >}} +As Shared databases (DEV) are shared between multiple applications and delays could appear in case of an high demand. If this delays create problems in your application or are problematic, we recommend you to use a dedicated database (XS plans and above). +{{< /callout >}} + +## 🔑 Rights and permissions + +Add-ons are managed services, meaning that users have **standard access** to the database (**ALL privileges**). Some operations like databases and users creation, as well as some settings modifications aren't available by default. This ensures optimal performances and security for managed services as configured by Clever Cloud. + +Authorized actions: +- Manage tables (create, delete…). +- Manage indexes. + +If you think your system might require more advanced administrative access, contact [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice) to explain your use case, and we will work with you to find a solution. + +Here is the list of actions that you won't be able to perform: +- Database administration (for example you won't be able to create new databases). +- Users administration (you won't be able to create other users than the one handled with our control plane, i.e. the base owner and read-only users). +- Server configuration update. +- Plugins installation. +- Replica creation. +- Backup frequency or retention control. +- Create Trigger or Function (Only on DEV plan) + +Ask Clever Cloud support if you want to perform one of these actions. diff --git a/content/doc/addons/otoroshi.md b/content/doc/addons/otoroshi.md new file mode 100644 index 000000000..b32584dfa --- /dev/null +++ b/content/doc/addons/otoroshi.md @@ -0,0 +1,143 @@ +--- +type: docs +title: Otoroshi with LLM +description: Otoroshi is a lightweight proxy that helps you to connect your services to your clients +tags: +- addons +keywords: +- otoroshi +- reverse +- proxy +- llm +- waf +aliases: +- /doc/clever-cloud-overview/clevergrid-machine-learning +- /doc/otoroshi +--- + +Otoroshi is a lightweight API management solution built on a modern HTTP reverse proxy. It serves as a flexible and powerful API gateway for your microservices architecture and operates as a technology-agnostic platform, embracing HTTP as its universal language and providing real-time configuration capabilities. The platform follows an API-first approach, ensuring all features are accessible programmatically. + +The solution excels at dynamic service management, offering essential API gateway functionalities including request routing, security enforcement, traffic management, and comprehensive monitoring. Its event-driven architecture and flexible deployment model make it particularly effective in cloud-native and PaaS environments. + +On Clever Cloud, it comes with pre-configured with features included such as [Coraza Web Appplication Firewall](#coraza-waf-web-application-firewall) or the [LLM extension](#llm-extension). + +{{< callout type="info" >}}Share your feedback on Otoroshi operator through [our community page](https://github.com/CleverCloud/Community/discussions/categories/otoroshi){{< /callout >}} + +## Create an Otoroshi with LLM add-on + +### From the Console + +1. [Create a new add-on](https://console.clever-cloud.com/users/me/addons/new) by clicking the **Create…** dropdown in the sidebar and then **an add-on** +2. Select the Otoroshi with LLM add-on +3. You can skip linking the add-on to an application, it won't be needed +4. Enter a name for your Otoroshi with LLM add-on and select the zone where you want it to be deployed + +### Using the CLI + +Make sure you have `clever-tools` installed locally. Please refer to the [setup guide](/developers/doc/cli/install/) if needed. In your terminal, run `clever addon create otoroshi --org ` (`--org` is optional). You'll get URLs to manage your Otoroshi with LLM instance and the temporary credentials: + +``` +$ clever addon create otoroshi myOtoroshi +Add-on created successfully! +ID: addon_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +Real ID: otoroshi_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx +Name: myOtoroshi + +Your Otoroshi with LLM is starting: + - Access it: https://xxxxxxxxxxxx-api-otoroshi.services.clever-cloud.com + - Manage it: https://console.clever-cloud.com/addon_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + +An initial account has been created, change the password at first login (Security -> Administrators -> Edit user): + - Admin user name: cc-account-admin + - Temporary password: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +Learn more about Otoroshi with LLM on Clever Cloud: https://www.clever.cloud/developers/doc/addons/otoroshi/ +``` + +Refer to the [Clever Tools documentation](/developers/doc/cli/addons/) for more details on add-on management. + +## Version management + +To change the version of an Otoroshi add-on on Clever Cloud, you can use the `CC_OTOROSHI_VERSION` environment variable of its Java Application and rebuild it. But there are various ways to do it simpler with [Clever Tools](/developers/doc/cli/): + +```bash +# Set a specific supported version at creation +clever addon create otoroshi --addon-version myOtoroshi + +# Enable Operators commands +clever features enable operators + +# Check the current version +clever otoroshi version check otoroshi_name_or_id +clever otoroshi version check otoroshi_name_or_id --format json + +# Update to a specific supported version +clever otoroshi version update myOtoroshi +clever otoroshi version update myOtoroshi +``` + +- Learn more about [Operators commands in Clever Tools](/developers/doc/cli/operators/) + +## Accessing the Otoroshi with LLM interface + +Once you created your add-on, open the management URL or look for `CC_OTOROSHI_URL` value in the Otoroshi with LLM dashboard from the Console. The first time you connect, change the initial password (Security -> Administrators -> Edit user). + +* [Learn how to use Otoroshi](https://maif.github.io/otoroshi/manual/how-to-s/index.html) + +## Underlying resources + +When you create the Otoroshi add-on, Clever Cloud automatically deploys: + +- A [Java](/developers/doc/applications/java/java-jar/) instance with Otoroshi with LLM pre-loaded +- A [Redis](/developers/doc/addons/postgresql/) database (for internal Otoroshi use) + +## Plan sizing + +By default, Otoroshi with LLM on Clever Cloud uses small-size resources, i.e: + +- S Java +- S Redis® + +They are dimensioned to suit a majority of needs. You can however manage and adjust them directly [in the Console](https://console.clever-cloud.com/). + +## LLM extension + +Otoroshi on Clever Cloud comes with LLM Extension. It provides a unified gateway for managing and interacting with Large Language Models through an OpenAI-compatible API interface, with [MCP support](https://www.clever-cloud.com/blog/company/2025/01/21/create-your-own-mcp-client-server-as-easy-as-1-2-3-with-otoroshi/). This extension streamlines the integration and management of multiple LLM providers including Ollama instances, OpenAI, Mistral, Anthropic, DeepSeek, Eleven Labs, Gemini, Groq, Hive, Hugging Face, Leonardo AI, Luma, OVH and Scaleway AI Endpoints. It supports audio, image, moderation and text generation models. + +### Smarter AI operations +The extension enhances your LLM operations with intelligent workload distribution and automatic failover mechanisms, ensuring consistent service availability. It implements sophisticated features such as semantic caching to optimize response times and reduce costs, while providing comprehensive quota management capabilities for effective resource allocation. + +{{< youtube id="M8sA9xuE3gs">}} + +### Security and Management +Security is paramount with built-in features for API key management through Otoroshi's secure vault system. The extension leverages Otoroshi's advanced authorization framework to implement fine-grained access controls based on user identity, API keys, consumer metadata, and request parameters. Additionally, prompt fencing technology helps prevent sensitive information leakage and ensures response quality. + +### Observability and Enhancement +Every LLM interaction is thoroughly audited, capturing detailed information about consumers, providers, and usage patterns. The extension also includes robust prompt engineering capabilities, allowing you to create and maintain a library of contextually enhanced prompts and templates for improved efficiency and consistency in LLM interactions. + +- [Otoroshi LLM extension documentation](https://cloud-apim.github.io/otoroshi-llm-extension/docs/overview) +- [Otoroshi LLM extension video tutorials](https://www.youtube.com/watch?v=M8PbydxPw4A&list=PLNHaf5rXAx3FWk7dn2fKGwQXxeLCPhZCh) + +## Coraza WAF (Web Application Firewall) + +Otoroshi on Clever Cloud integrates Coraza, a high-performance Web Application Firewall (WAF), through a WebAssembly-based plugin. This integration provides enterprise-grade security features to protect your applications using the OWASP Core Rule Set (CRS). + +### Security features +The Coraza WAF plugin enables robust security policy enforcement while maintaining high performance across deployments of any scale. It seamlessly integrates with Otoroshi's existing infrastructure to provide comprehensive protection against web application threats. + +The integration provides advanced security capabilities through OWASP CRS implementation, allowing you to create and enforce custom security policies. The system generates detailed audit logs for security monitoring and compliance purposes, with full integration into Otoroshi's existing logging and monitoring infrastructure. + +### Enterprise Capabilities +Designed for production environments, the Coraza WAF plugin offers flexible configuration options, supporting both detection and prevention modes. It enables customized rule sets per domain and provides detailed security event tracking through Otoroshi's event management system. The implementation is optimized for minimal performance impact while maintaining robust security controls. + +- [Otoroshi Coraza WAF documentation](https://maif.github.io/otoroshi/manual/how-to-s/instantiate-waf-coraza.html) + +## Manage Otoroshi from its API + +Otoroshi exposes a comprehensive REST API that enables programmatic control over all operations available through the Otoroshi dashboard. The dashboard itself operates as a client of this API. It gives you full control over your Otoroshi instances, enabling you to build custom integrations and extensions tailored to your infrastructure needs. [A Swagger UI detailing available endpoints is available](https://maif.github.io/otoroshi/swagger-ui/index.html). + +An OpenAPI descriptor is available from your instance: + +``` +https://xxxxxxxxxxxx-api-otoroshi.services/apis/openapi.json +``` diff --git a/content/doc/addons/postgresql.md b/content/doc/addons/postgresql.md new file mode 100644 index 000000000..9863f38a8 --- /dev/null +++ b/content/doc/addons/postgresql.md @@ -0,0 +1,185 @@ +--- +type: docs +title: PostgreSQL +description: PostgreSQL is an open source relational database management system (RDBMS) +tags: +- addons +keywords: +- sql +- postgresql +- pg +- pgsql +- mariadb +aliases: +- /addons/postgresql +- /deploy/addon/postgresql +- /doc/databases-and-services/postgresql +- /doc/deploy/addon/postgresql +- /doc/deploy/addon/postgresql/postgresql +- /doc/postgresql +- /doc/postgresql-hosting +- /postgresql-hosting +--- +## Overview + +PostgreSQL is an object-relational database management system (ORDBMS) with an emphasis on extensibility and on standards-compliance. + +## Supported Versions + +{{< software_versions_shared_dedicated pg>}} + +{{% content "db-backup" %}} + +## Migrating from an old database + +Some applications require a non-empty database to run properly. If you want to import your **SQL** dump, you can use several methods: +1. [WebGUI (Adminer)](https://dbms-adminer.clever-cloud.com/) +2. Command line tool for PostgreSQL administration like `psql` +3. Any PostgreSQL client such as [pgAdmin](https://www.pgadmin.org/) + +{{% content "db-migration" %}} + +## Replication + +You can add up to 2 replicas to an existing PostgreSQL (v12 or higher) database on Clever Cloud to enhance performance and reliability. They're set up as read-only [standby servers](https://www.postgresql.org/docs/current/runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-STANDBY) with full physical replication, in a different availability zone (AZ) or region if requested. + +You can see if a database is a [primary server](https://www.postgresql.org/docs/current/runtime-config-replication.html#RUNTIME-CONFIG-REPLICATION-PRIMARY) or a replica from PostgreSQL dashboard in [the Console](https://console.clever-cloud.com). If a primary server isn't available, you can promote a replica as a standalone server and link it to applications. This database will: +- Become a primary server (using `pg_ctl promote` command internally) with read/write capabilities +- Delete its replication link to the original primary server + +> [!Note] Replication setup isn't yet available from API or the Console +> To create and configure PostgreSQL replicas, contact your sales representative or [Clever Cloud support](https://console.clever-cloud.com/ticket-center-choice). + +## Direct access + +A proxy serves all dedicated PostgreSQL databases. In some cases, this can add some latency between applications and their database. If this is an issue, you can generate a direct hostname and port for the add-on to bypass the proxy, using the "Generate direct hostname and port" button in the add-on dashboard. + +Generating direct access adds new variables to the add-on's environment, allowing connections without going through the proxy. + +{{< callout type="info" >}} +Direct access doesn't persist after migrating a database. Manually re-generate direct host name and port after a migration to allow applications linked through direct access to connect to the database. + +Such a limitation doesn't exist when using proxy access. +{{< /callout >}} + +## Encryption at rest + +Encryption at rest is available on PostgreSQL. You can find more information on the [dedicated page](/developers/doc/administrate/encryption-at-rest) + +## Note on shared databases + +If you try to list the databases on the shared cluster, you will see the names of the databases of all other users of the cluster. This is normal behaviour. Rest assured, permissions are set properly, meaning no one but your user can read or write data to your database. + +This referencing does not exist for dedicated databases. + +## Pgpool-II + +{{% content "pgpool" %}} + +You can learn more about Pgpool-II on the [dedicated documentation page](/developers/guides/pgpool) + +## Default extensions + +PostgreSQL databases managed by Clever Cloud comes with these extensions: + +Extension              | Description +----------------------- | ----------- + adminpack              | Administrative functions for PostgreSQL (not supported on PostgreSQL 17+) + autoinc                | Functions for autoincrementing fields + btree_gin              | Support for indexing common datatypes in GIN + btree_gist             | Support for indexing common datatypes in GiST + citext                 | Data type for case-insensitive character strings + cube                   | Data type for multidimensional cubes + dblink                 | Connect to other PostgreSQL databases from within a database + dict_int               | Text search dictionary template for integers + dict_xsyn              | Text search dictionary template for extended synonym processing + earthdistance          | Calculate great-circle distances on the surface of the Earth + file_fdw               | Foreign-data wrapper for flat file access + fuzzystrmatch          | Determine similarities and distance between strings + hstore                 | Data type for storing sets of (key, value) pairs + hypopg                 | Hypothetical indexes for PostgreSQL + insert_username        | Functions for tracking who changed a table + intagg                 | Integer aggregator and enumerator (obsolete) + intarray               | Functions, operators, and index support for 1-D arrays of integers + isn                    | Data types for international product numbering standards + lo                     | Large Object maintenance + ltree                  | Data type for hierarchical tree-like structures + moddatetime            | Functions for tracking last modification time + pageinspect            | Inspect the contents of database pages at a low level + pg_buffercache         | Examine the shared buffer cache + pg_freespacemap        | Examine the free space map (FSM) + pg_stat_statements     | Track planning and execution statistics of all SQL statements executed + pg_trgm                | Text similarity measurement and index searching based on trigrams + pgcrypto               | Cryptographic functions + pgrowlocks             | Show row-level locking information + pgstattuple            | Show tuple-level statistics + pgvector | Vector data type and ivfflat and hnsw access methods + plcoffee               | PL/CoffeeScript (v8) trusted procedural language (not supported on PostgreSQL 16+) + plls                   | PL/LiveScript (v8) trusted procedural language (not supported on PostgreSQL 16+) + plpgsql                | PL/pgSQL procedural language + plv8                   | PL/JavaScript (v8) trusted procedural language (not supported on PostgreSQL 16+) + postgis                | PostGIS geometry and geography spatial types and functions + postgis_raster         | PostGIS raster types and functions + postgis_tiger_geocoder | PostGIS tiger geocoder and reverse geocoder + postgis_topology       | PostGIS topology spatial types and functions + postgres_fdw           | Foreign-data wrapper for remote PostgreSQL servers + refint                 | Functions for implementing referential integrity (obsolete) + seg                    | Data type for representing line segments or floating-point intervals + sslinfo                | Information about SSL certificates + tablefunc              | Functions that manipulate whole tables, including crosstab + tcn                    | Triggered change notifications + unaccent               | Text search dictionary that removes accents + uuid-ossp              | Generate universally unique identifiers (UUIDs) + xml2                   | XPath querying and XSLT + +## On-demand extensions + +In the [Console's Ticket Center](https://console.clever-cloud.com/ticket-center-choice), you can ask our support team to add any of these extensions for you: + +Extension | Description +----------- | ----------- +pg_cron | Job scheduler for PostgreSQL +pg_ivm | Incremental view maintenance for PostgreSQL +pg_net | Enables asynchronous (non-blocking) HTTP/HTTPS requests with SQL +pgaudit | Provides detailed session and/or object audit logging via the standard PostgreSQL logging facility +pgsql-http | HTTP client for PostgreSQL +pgtap | Unit testing for PostgreSQL +rum | Provides an access method to work with a RUM index +timescaledb | Enables scalable inserts and complex queries for time-series data (Apache 2 Edition) + +{{< callout type="warning" >}} +On-demand extensions aren't available for DEV plans. +{{< /callout >}} + +## Automatic vacuuming + +[Autovacuum](https://www.postgresql.org/docs/current/routine-vacuuming.html) is automatically enabled on PostgreSQL add-ons. +The autovacuum will proceed when a given percentage of rows of a table will be updated/inserted/deleted. +Usually this threshold is set to 20%. + +## `pg_activity` + +If you want to use [pg_activity](https://github.com/dalibo/pg_activity) on a PostgreSQL add-on, but you encounter the following error `Exception: Must be run with database superuser privileges.`, you need to add the `--rds` flag when you start it. + +## 🔑 Rights and permissions + +Add-ons are managed services, meaning that users have **standard access** to the database (role **owner**). Some operations like databases and users creation, as well as some settings modifications aren't available by default. This ensures optimal performances and security for managed services as configured by Clever Cloud. + +Authorized actions: +- Manage tables (create, delete…). +- Manage schemas. +- Manage indexes. +- Access information from **pg_catalog** (except **pg_database** on DEV plan). +- Access to basic maintenance operations such as *VACUUM* and *ANALYZE*. + +If you think your system might require more advanced administrative access, [contact Clever Cloud support](https://console.clever-cloud.com/ticket-center-choice) to explain your use case, and we will work with you to find a solution. + +Here is the list of actions that you won't be able to perform: +- Database administration (for example you won't be able to create new databases). +- Users administration (you won't be able to create other users than the one handled with our control plane, i.e. the base owner and read-only users). +- Server configuration update. +- Extensions installation. +- Replica creation. +- Back-up frequency or retention control. + +Ask Clever Cloud support if you want to perform one of these actions. diff --git a/content/doc/addons/pulsar.md b/content/doc/addons/pulsar.md new file mode 100644 index 000000000..559f39a43 --- /dev/null +++ b/content/doc/addons/pulsar.md @@ -0,0 +1,476 @@ +--- +type: docs +title: Pulsar +description: A distributed messaging and streaming platform on the publish/subscribe model +tags: +- addons +keywords: +- pulsar +- messaging +- cold storage +- queue +- hot storage +- biscuit +- rabbitmq +- kafka +aliases: +- /deploy/addon/pulsar +- /doc/deploy/addon/pulsar +--- + +{{< callout type="warning" >}} Pulsar is still in beta. {{< /callout >}} + +## Overview + +[Pulsar](https://pulsar.apache.org/) works on a publisher/subscriber model. It allows services to communicate asynchronously, with latencies ranging around 100 milliseconds. It is used for streaming analytics and data integration pipelines to ingest and distribute data. It's equally effective as messaging-oriented middleware for service integration or as a queue to parallelize tasks. It also enables you to create systems of event producers and consumers. Publishers communicate with subscribers asynchronously by broadcasting events. + +```mermaid +%%{ + init: { + 'theme': 'base', + 'themeVariables': { + 'fontFamily':'Arial', + 'primaryColor': '#FFFFFF', + 'primaryTextColor': '#6b7280', + 'primaryBorderColor': '#e5e7eb', + 'lineColor': '#545191', + 'secondaryColor': '#FFFFFFCC', + 'tertiaryColor': '#e5e7eb' + } + } +}%% + +flowchart RL + B("Pulsar Topic"):::pulsar + direction LR + C[Client producer] -- publishes to --> B + direction RL + D["Client consumer"]-- subscribes to --> B + + classDef pulsar stroke:#188FFF +``` + +There are several modes of subscription. A consumer may subscribe exclusively, or share the subscription with other consumers. Here are the four subscription types: + +- Exclusive (only one consumer for the subscription) +- Failover (if a consumer fails, another one receives the message) +- Shared (messages are distributed to several consumers) +- Key_Shared (messages come with keys and go to consumers with the corresponding key) + +More on this in the [official documentation](https://pulsar.apache.org/docs/en/concepts-messaging/#subscriptions). + +A topic is defined this way: + +`{persistent|non-persistent}://tenant/namespace/topic` + +Tenants and namespaces allow for grouping and sub-grouping of topics. + +A Clever Cloud Pulsar add-on is basically an immutable `tenant/namespace` where the tenant is your organisation ID, and the namespace is the add-on ID. +It allows you to create and use topics following this pattern: + +`{persistent|non-persistent}:////` + +## Version + +We maintain up-to-date Pulsar clusters based on the official Apache Pulsar release process. Your Pulsar add-on version is available in your add-on dashboard. Updates will be notified using Clever Cloud weekly updates on the [blog](https://www.clever-cloud.com/blog/). + +## Common use cases + +- **Replicating data among databases** using [Pulsar IO](https://pulsar.apache.org/docs/en/io-overview/) is commonly used to distribute change events from databases. +- **Parallel processing and workflows**. You can efficiently distribute a large number of tasks among multiple workers (compressing text files, sending email notifications). +- **Data streaming from IoT devices**. For example, a residential sensor can stream data to backend servers. +- **Refreshing distributed caches**. For example, an application can publish invalidation events to update the IDs of objects that have changed. +- **Real-time event distribution**. Events, raw or processed, may be made available to multiple applications across your team and organisation for real time processing. + +## Create a Pulsar add-on + +It is as simple and straightforward as creating any other add-on. In your personal space, click on *Create* > *an add-on* > *Pulsar*. Choose your plan, link an app to it (or not), give it a name and a zone, and it's done. + +## Authorization + +Pulsar add-on uses [Biscuit for Pulsar](https://github.com/CleverCloud/biscuit-pulsar) implementation which is directly pluggable to the Pulsar authentication and authorization system. Each add-on exposes its own Biscuit token. + +As Biscuit is a token, you can use `AuthenticationToken($ADDON_PULSAR_TOKEN)` provided by [clients libraries](https://pulsar.apache.org/docs/en/client-libraries/) to authenticate to our clusters without any tweak. + +### Attenuation + +The Pulsar add-on given Biscuit token can be attenuated, here is an attenuation example using [biscuit-cli](https://github.com/biscuit-auth/biscuit-cli) from the given Biscuit token to produce/consume topics starting with a custom topic prefix called `"my-own-prefix"`. + +Put your Biscuit token in a file: + +```bash +echo $ADDON_PULSAR_TOKEN > addon.biscuit +``` + +Inspect your Biscuit token: + +```bash +biscuit inspect addon.biscuit +Authority block: +== Datalog == +right("admin"); + +== Revocation id == +0392cdc4dbda294fd254269ad0ce5d1ad2e9c6301b189945074dd051890e495dd16bf5390f84e8499a2045bde85795636f2e156309f9b425270979957e50280a + +========== + +Block n°1: +== Datalog == +check if namespace("user_1235678-f54e-4e09-848c-1953af6e3e89", "pulsar_1235678-6b36-4af2-be1f-d97862c0c41c") or topic("user_1235678-f54e-4e09-848c-1953af6e3e89", "pulsar_1235678-6b36-4af2-be1f-d97862c0c41c", $topic); + +== Revocation id == +4a72ca17001b173853f5cd6cce7b46ba4113b1d6e934a3e13e717f91e276c3230861ee49c843c4aafd7d11b14903a7ff32f9e2b35bd6f84794ba3dc6e3c0450c + +========== +``` + +- The authority block is the cluster authentication block (the cluster admin Biscuit token). +- The block n°1 is an attenuation of the authority block to only authorize operations on `tenant = "user_1235678-f54e-4e09-848c-1953af6e3e89"` and `namespace = "pulsar_1235678-6b36-4af2-be1f-d97862c0c41c"`. + +Attenuate it: + +```bash +biscuit attenuate addon.biscuit +``` + +This will open your `$EDITOR` to type the attenuation. + +Put + +```bash +check if topic_operation($operation), $topic.starts_with("my-own-prefix") +``` + +Then it outputs the attenuated token. Inspect it to ensure your attenuation: + +```bash +Authority block: +== Datalog == +right("admin"); + +== Revocation id == +0392cdc4dbda294fd254269ad0ce5d1ad2e9c6301b189945074dd051890e495dd16bf5390f84e8499a2045bde85795636f2e156309f9b425270979957e50280a + +========== + +Block n°1: +== Datalog == +check if namespace("user_1235678-f54e-4e09-848c-1953af6e3e89", "pulsar_1235678-6b36-4af2-be1f-d97862c0c41c") or topic("user_1235678-f54e-4e09-848c-1953af6e3e89", "pulsar_1235678-6b36-4af2-be1f-d97862c0c41c", $topic); + +== Revocation id == +4a72ca17001b173853f5cd6cce7b46ba4113b1d6e934a3e13e717f91e276c3230861ee49c843c4aafd7d11b14903a7ff32f9e2b35bd6f84794ba3dc6e3c0450c + +========== + +Block n°2: +== Datalog == +check if topic_operation($operation), $topic.starts_with("my-own-prefix"); + +== Revocation ids == +3b71ba17001b173853f5cd6cce7b46ba4113b1d6e934a3e13e717f91e276c3230861ee49c843c4aafd7d11b14903a7ff32f9e2b35bd6f84794ba3dc6e3c0450d + +========== +``` + +Now the block n°2 ensures that topics must start with `"my-own-prefix"`. + +You can find more examples on the [biscuit-pulsar authorization java tests](https://github.com/CleverCloud/biscuit-pulsar/blob/master/src/test/java/com/clevercloud/biscuitpulsar/AuthorizationProviderBiscuitTest.java). + +## Usage + +We advise you to use [`pulsarctl`](https://github.com/streamnative/pulsarctl) provided by StreamNative. Here is an example to list topics in your add-on (in your namespace): + +```bash +pulsarctl --admin-service-url $ADDON_PULSAR_HTTP_URL \ + --auth-params $ADDON_PULSAR_TOKEN \ + --auth-plugin org.apache.pulsar.client.impl.auth.AuthenticationToken \ + namespaces topics $ADDON_PULSAR_TENANT/$ADDON_PULSAR_NAMESPACE +``` + +### Rust example + +Clever Cloud maintains pulsar's [asynchronous Rust client](https://github.com/wyyerd/pulsar-rs), which support biscuits. +Here is a minimal example that produces (publishes) a *"Hello, World!"* on the topic `my-own-topic`: + +```toml +# Cargo.toml +[dependencies] +tokio = {version = "1.9.0", features = ["full"] } +pulsar = "4.0.0" +serde_json = "1.0.66" +serde = { version = "1.0.127", features = ["derive"] } +``` + +```rust +use pulsar::{ + message::proto, producer, Error as PulsarError, Pulsar, SerializeMessage, TokioExecutor, +}; +use serde::{Deserialize, Serialize}; + +#[derive(Serialize, Deserialize)] +struct TestData { + data: String, +} + +impl SerializeMessage for TestData { + fn serialize_message(input: Self) -> Result { + let payload = serde_json::to_vec(&input).map_err(|e| PulsarError::Custom(e.to_string()))?; + Ok(producer::Message { + payload, + ..Default::default() + }) + } +} + +#[tokio::main] +async fn main() -> Result<(), pulsar::Error> { + let pulsar_addon_url = std::env::var("ADDON_PULSAR_BINARY_URL").unwrap(); + let biscuit = std::env::var("ADDON_PULSAR_TOKEN").unwrap(); + let tenant = std::env::var("ADDON_PULSAR_TENANT").unwrap(); + let namespace = std::env::var("ADDON_PULSAR_NAMESPACE").unwrap(); + + let topic = format!("non-persistent://{}/{}/my-own-topic", tenant, namespace); + + let auth = pulsar::Authentication { + name: "token".to_string(), + data: biscuit.clone().into_bytes(), + }; + + let pulsar: Pulsar<_> = Pulsar::builder(pulsar_addon_url, TokioExecutor) + .with_auth(auth) + .build() + .await?; + + let mut producer = pulsar + .producer() + .with_topic(topic) + .with_name("my-producer") + .with_options(producer::ProducerOptions { + schema: Some(proto::Schema { + r#type: proto::schema::Type::String as i32, + ..Default::default() + }), + ..Default::default() + }) + .build() + .await?; + + producer + .send(TestData { + data: "Hello world!".to_string(), + }) + .await?; + + Ok(()) +} +``` + +### Java example + +There is an official [Java Pulsar Client](https://pulsar.apache.org/docs/en/client-libraries-java/), import it in your `pom.xml`: + +```xml + + org.apache.pulsar + pulsar-client + 2.8.0 + +``` + +```java +PulsarClient client = PulsarClient.builder() + .authentication(new AuthenticationToken("ADDON_PULSAR_TOKEN")) + .serviceUrl("ADDON_PULSAR_BINARY_URL") + .build(); + +String TOPIC = "non-persistent://{}/{}/my-own-topic" + +Producer producer = client.newProducer(Schema.STRING) + .topic(TOPIC) + .create(); + + producer.send("Hello world!"); + +Consumer consumer = client.newConsumer() + .topics(Arrays.asList(TOPIC)) + .consumerName("my-consumer-name") + .subscriptionName("my-subscription-name") + .subscriptionInitialPosition(SubscriptionInitialPosition.Earliest) + .subscribe(); + +while (!consumer.hasReachedEndOfTopic()) { + Message msg = consumer.receive(); + // Got the message! +} +``` + +### Python example + +There is an official [Python Pulsar Client](https://pulsar.apache.org/docs/en/client-libraries-python/), import it in your `requirements.txt`: + +```text +pulsar-client==2.10.2 +``` + +```python +import pulsar +import os +import json +from pulsar import AuthenticationToken +from transfer import transfer + +client = pulsar.Client( + os.getenv("ADDON_PULSAR_BINARY_URL"), + authentication=AuthenticationToken(os.getenv("ADDON_PULSAR_TOKEN")), +) + +tenant = os.getenv("ADDON_PULSAR_TENANT") +namespace = os.getenv("ADDON_PULSAR_NAMESPACE") +topic = "persistent://{}/{}/TOPIC_NAME".format(tenant, namespace) + +producer = client.create_producer(topic) +for i in range(10): + producer.send(('Hello-%d' % i).encode('utf-8')) + +while True: + msg = consumer.receive() + print("Received message id='{}' with data\n{}\n".format(msg.message_id(), msg.data())) + # Acknowledge successful processing of the message + consumer.acknowledge(msg) + # Message failed to be processed +client.close() +``` + +### Operations + +The Biscuit token provided by the Pulsar add-on allows you to run several operations on the add-on's namespace, its policies and the related topics. + +These operations might change in the future. Don't hesitate to write to our support to ask for new operations! + +#### Namespace + +Authorized namespace operations: + +```text +CREATE_TOPIC +GET_TOPIC +GET_TOPICS +DELETE_TOPIC +GET_BUNDLE +CLEAR_BACKLOG +UNSUBSCRIBE +``` + +#### Topics + +Authorized topics operations: + +```text +LOOKUP +PRODUCE +CONSUME +COMPACT +EXPIRE_MESSAGES +OFFLOAD +PEEK_MESSAGES +RESET_CURSOR +SKIP +TERMINATE +GET_BUNDLE_RANGE +SUBSCRIBE +GET_SUBSCRIPTIONS +UNSUBSCRIBE +GET_STATS +GET_METADATA +GET_BACKLOG_SIZE +SET_REPLICATED_SUBSCRIPTION_STATUS +``` + +### Namespace and topic policies + +Authorized namespace/topic policies operations: + +```text +ALL_READ +ANTI_AFFINITY_READ +AUTO_SUBSCRIPTION_CREATION_READ +AUTO_SUBSCRIPTION_CREATION_WRITE +AUTO_TOPIC_CREATION_READ +AUTO_TOPIC_CREATION_WRITE +BACKLOG_READ +BACKLOG_WRITE +COMPACTION_READ +COMPACTION_WRITE +DEDUPLICATION_READ +DEDUPLICATION_SNAPSHOT_READ +DEDUPLICATION_SNAPSHOT_WRITE +DEDUPLICATION_WRITE +DELAYED_DELIVERY_READ +DELAYED_DELIVERY_WRITE +ENCRYPTION_READ +ENCRYPTION_WRITE +INACTIVE_TOPIC_READ +INACTIVE_TOPIC_WRITE +MAX_CONSUMERS_READ +MAX_CONSUMERS_WRITE +MAX_PRODUCERS_READ +MAX_PRODUCERS_WRITE +MAX_SUBSCRIPTIONS_READ +MAX_SUBSCRIPTIONS_WRITE +MAX_TOPICS_READ +MAX_TOPICS_WRITE +MAX_UNACKED_READ +MAX_UNACKED_WRITE +OFFLOAD_READ +PARTITION_READ +PARTITION_WRITE +PERSISTENCE_READ +PERSISTENCE_WRITE +RATE_READ +RATE_WRITE +REPLICATION_RATE_READ +REPLICATION_READ +RESOURCEGROUP_READ +RESOURCEGROUP_WRITE +RETENTION_READ +RETENTION_WRITE +SCHEMA_COMPATIBILITY_STRATEGY_READ +SCHEMA_COMPATIBILITY_STRATEGY_WRITE +SUBSCRIPTION_AUTH_MODE_READ +SUBSCRIPTION_AUTH_MODE_WRITE +SUBSCRIPTION_EXPIRATION_TIME_READ +SUBSCRIPTION_EXPIRATION_TIME_WRITE +TTL_READ +TTL_WRITE +``` + +## Storage + +### Retention + +A Pulsar add-on is provided with infinite retention policies, which can be changed using: + +```bash +# Example to set retention of namespace to 2 weeks and/or 100 GB +pulsarctl --admin-service-url $ADDON_PULSAR_HTTP_URL \ + --auth-params $ADDON_PULSAR_TOKEN \ + --auth-plugin org.apache.pulsar.client.impl.auth.AuthenticationToken \ + namespaces set-retention $ADDON_PULSAR_TENANT/$ADDON_PULSAR_NAMESPACE --time 2w --size 100G +``` + +### Offload storage to Cellar (S3) + +Pulsar has a [tiered storage feature](https://pulsar.apache.org/docs/en/tiered-storage-overview/) allowing to offload heavy data to cold storage once a threshold is reached. + +For each Pulsar add-on we provide, we also provide a hidden [Cellar add-on](/developers/doc/addons/cellar), our object storage add-on. This Cellar add-on is bound to the Pulsar namespace offload policies and will store your offloaded data. + +The offload threshold of the namespace is deactivated by default, you can activate it with: + +```bash +# Example to set offload to run when hot storage is > 10G and put data to Cellar Addon +pulsarctl --admin-service-url $ADDON_PULSAR_HTTP_URL \ + --auth-params $ADDON_PULSAR_TOKEN \ + --auth-plugin org.apache.pulsar.client.impl.auth.AuthenticationToken \ + namespaces set-offload-treshold $ADDON_PULSAR_TENANT/$ADDON_PULSAR_NAMESPACE 10G +``` diff --git a/content/doc/addons/redis.md b/content/doc/addons/redis.md new file mode 100644 index 000000000..aed2a47c9 --- /dev/null +++ b/content/doc/addons/redis.md @@ -0,0 +1,71 @@ +--- +type: docs +title: Redis +description: Redis is an open source, in-memory data structure store, used as database, cache and message broker +tags: +- addons +keywords: +- key +- value +- key-value +- in-memory +aliases: +- /addons/redis +- /doc/addons/redsmin +- /doc/deploy/addon/redis +- /doc/en/redis-hosting +- /doc/redis +- /doc/redis-hosting +--- + +Redis is an open source, in-memory data structure store, used as database, cache and message broker. + +## Version + +The version currently installed by the add-on are the following : + +{{< software_versions_shared_dedicated redis>}} + +{{% content "db-backup" %}} + +A backup is a `tar.gz` archive containing both the `.rdb` and `.aof` files. You can extract this archive and run `redis-server` in the extracted folder to access data. + +{{% content "db-migration" %}} + +## Leader / follower topology + +By default, all redis add-ons are configured as leaders. You can set up a redis add-on as a follower from the add-on panel (in the "Add-on information" tab). You need to set the leader +information (host, port, password) to start the replication. The add-on panel will display the sync process status so that you know when the synchronisation is done. + +While a redis database is configured as a follower, it's read-only. + +## Redis-cli usage + +You can use Redis URI to connect to your databases with -u option. However, the generated URI in the information tab (`REDIS_URL`) of you add-on is not a legal syntax to use `redis-cli`. + +This is the correct syntax for `redis-cli` URI : *redis ://password@host:port[/database]* + +{{% content "kv-explorer" %}} + +## Default retention policy + +By default, the eviction policy is `noeviction`. If you plan to use Redis as a LRU cache, +please contact the support to change its policy. + +## 🔑 Rights and permissions + +Add-ons are managed services, meaning that users have **controlled access** to the server. They are granted access to all proposed operations except changing the server configuration. Based on the plan, they are granted access to a fix amount of databases. This ensures optimal performances and security for managed services as configured by Clever Cloud. + +Authorized actions: +- Access to one or more databases depending on your plan. +- Access to all Redis operations except *CONFIG* and *CLUSTER*. +- Set up replica via clever cloud console. + +If you think your system might require more advanced administrative access, [contact Clever Cloud support](https://console.clever-cloud.com/ticket-center-choice) to explain your use case, and we will work with you to find a solution. + +Here is the list of actions that you won't be able to perform: +- Server configuration update. +- Modules installation. +- Backup frequency or retention control. + +Ask Clever Cloud support if you want to perform one of these actions. diff --git a/content/doc/administrate/_index.md b/content/doc/administrate/_index.md new file mode 100644 index 000000000..fb7a495f3 --- /dev/null +++ b/content/doc/administrate/_index.md @@ -0,0 +1,29 @@ +--- +weight: 5 +type: docs +title: "Administrate" +description: Manage your applications, add-ons, and more on Clever Cloud +comments: false +aliases: +- /doc/admin +--- + +{{< cards >}} + {{< card link="/developers/doc/administrate/apps-management" title="Application management" icon="cursor-arrow-ripple" >}} + {{< card link="/developers/doc/administrate/activity" title="Activity" icon="clock" >}} + {{< card link="/developers/doc/administrate/scalability" title="Application scaling" icon="arrow-trending-up" >}} + {{< card link="/developers/doc/administrate/clamav" title="CLAMAV" icon="clamav" >}} + {{< card link="/developers/doc/administrate/cron" title="CRON" icon="code-bracket" >}} + {{< card link="/developers/doc/administrate/database-migration" title="Database migration and security update" icon="circle-stack" >}} + {{< card link="/developers/doc/administrate/domain-names" title="Domain names" icon="at-symbol" >}} + {{< card link="/developers/doc/administrate/encryption-at-rest" title="Encryption at rest" icon="lock-closed" >}} + {{< card link="/developers/doc/administrate/ssl" title="Installing TLS certificate" icon="document-check" >}} + {{< card link="/developers/doc/administrate/log-management" title="Log management" icon="document-text" >}} + {{< card link="/developers/doc/administrate/network" title="Network and IP adresses ranges" icon="globe-alt" >}} + {{< card link="/developers/doc/administrate/service-dependencies" title="Service dependencies" icon="plug" >}} + {{< card link="/developers/doc/administrate/ssh-clever-tools" title="SSH access to running instances" icon="command-line" >}} + {{< card link="/developers/doc/administrate/tcp-redirections" title="TCP redirections with Clever Tools" icon="tcp-ip-service" >}} + {{< card link="/developers/doc/administrate/cache" title="Varnish as HTTP cache" icon="bubbles" >}} + {{< card link="/developers/doc/administrate/zone-migration" title="Zone migration" icon="map-pin" >}} + +{{< /cards >}} diff --git a/content/doc/administrate/activity.md b/content/doc/administrate/activity.md new file mode 100644 index 000000000..f9b82802a --- /dev/null +++ b/content/doc/administrate/activity.md @@ -0,0 +1,49 @@ +--- +type: docs +title: Activity +description: Applications activity lifecycle explained +tags: +- lifecycle +keywords: +- activity +- unreachable +- timeout +- diskfull +- scaling +- maintenance +--- + +Follow your application activities and lifecycle from the **Activity** option in the application menu. Every time your application redeploys, a new block appears on the timeline. Re-deployment triggers can be either: + + - An action performed by you or by a member of your organisation + - An action performed by Clever Cloud + + ## Re-deployment triggered by you + +This happens when you or a member of your organisation performs an action on the application, like: + +- [Restart or rebuild](/developers/doc/administrate/apps-management/#start-restart-and-stop) from the Console or [the CLI](/developers/doc/cli/) +- Push a new commit from Git or GitHub + + Here's what you might see on the timeline: + +![Activity timeline](/images/activity.png) + +Each block indicates if the deployment was successful or unsuccessful, along with the following information: + +- **Date**: when the activity happened and from where (`Console`, `Git`, `Github` or `Monitoring`) +- **Author**: which member of your organisation triggered the activity +- **Commit ID**: on which commit the activity happened +- **Redeploy this commit**: the option to redeploy a previous commit (useful to quickly roll-back if needed) + +## Re-deployments triggered by Clever Cloud + +Clever Cloud might also trigger re-deployments, either when you're being assisted by the Support, or automatically by the monitoring system. If the monitoring triggers a re-deployment, you'll see no author and the message explaining the reason, like `Monitoring/Unreachable`. The messages you might get are the following: + +![Re-deployment triggered by the monitoring](/images/monitoring.png) + +- `Unreachable`: The monitoring servers couldn't open a TCP connection with at least one monitoring agent hosted on instances of the application. +- `Timeout`: The monitoring servers has succeed to open TCP connections on all monitoring agents hosted on instances of the application, but at least one did not send its probes in time. +- `Scaling`: Clever Cloud triggers a new deployment with more instances (virtual machines) or more resources of the application as the platform detects that the consumption is greater that the determined threshold on memory or CPU usage. For further details, see [Scalability](/developers/doc/administrate/scalability) +- `Maintenance`: Clever Cloud performed a maintenance deployment of the application to integrate new configurations, security patches, operating system updates, runtime updates and so on… +- `DiskFull`: Rarely appears, but you could see this message if you haven't enabled the auto-scalability, after the app crashed and the monitoring restarted it. diff --git a/content/doc/administrate/apps-management.md b/content/doc/administrate/apps-management.md new file mode 100644 index 000000000..f6396da7b --- /dev/null +++ b/content/doc/administrate/apps-management.md @@ -0,0 +1,60 @@ +--- +type: docs +title: Application Management +description: Starting, restarting, stopping your applications +tags: +- dashboard-setup +keywords: +- stop +- deploy +- restart +- logs +aliases: +- /administrate/apps-management +- /doc/admin-console/apps-management +--- + +## Start, restart and stop + +You can start, restart, and stop your application in the **Overview** menu of your application in the Clever Cloud console. + +- **Start**: will restart a stopped application. This will not trigger a rebuild phase as it will use the build cache. +- **Re-build and restart**: Same as start but with a build phase and without using using the build cache. +- **Restart last pushed commit**: will start last commit on the tree even if you reverted deployments to a previous commit. +- **Stop**: will stop currently running instances of your application. + +Stop functionality is useful during the development of the application to limit its credit consumption. + +![Manage your application from the Console](/images/app-management.png) + +{{< callout type="info" >}} + If you set [`CC_DISABLE_BUILD_CACHE_UPLOAD`](/developers/doc/develop/env-variables/#settings-you-can-define-using-environment-variables) environment variable to `true`, the cache archive won't be created nor uploaded. +{{< /callout >}} + +## Deploy an old commit + +If you want to revert to a previous version of your code, you can go to the **Activity** menu of your application in the Clever Cloud console. You will find here all your previous commits. Just select **redeploy this commit** on the desired one. This will trigger a redeploy of your application at this version. + +## Edit application configuration + +You can edit your application in the **Information** menu of your application in the Clever Cloud console. You can rename it, change description and deployment zone. +You can also enable/disable: + +- **Zero downtime deployment**: During a deployment, old scalers are kept up until the new instances work. Updates are thus transparent to the user. Your application has to work correctly with several scalers in parallel (e.g. for connections to databases). *`pico` and `nano` scalers are using this feature by default.* +- **Sticky sessions**: When horizontal scalability is enabled, a user is always served by the same scaler. Some frameworks or technologies require this option. +- **Dedicated build instance**: Your application will build on a dedicated machine allowing you to use a small scaler to run your application. But, using this option will make your deployment slower (by ~10 seconds) +- **Cancel ongoing deployment on new push**: A "git push" will cancel any ongoing deployment and start a new one with the last available commit. +- **Force HTTPS**: Any non secured HTTP request to this application will be redirected to HTTPS with a 301 Moved Permanently status code. + +Do not forget to save after editing your configuration. + +![Edit your application](/images/application-edit.png) + +## Archiving/Unarchiving your application + +You can perform this operation in the **Overview** menu of your application in the Clever Cloud console. You will find an **archive** button. This will remove it from your application's list, but you will stil be able to access your application and push to its git remote. +If you want to unarchieve your application simply click the **un-archive** button where the **archive** button was. + +## Deleting your application + +You can perform this operation in the **Information** menu of your application in the Clever Cloud console. You will find a red **remove this application** button at the bottom. This will open a modal where you should type the name of your application. Click **remove** to finish the process. Your application will be deleted and no longer accessible. diff --git a/content/doc/administrate/cache.md b/content/doc/administrate/cache.md new file mode 100644 index 000000000..24e678993 --- /dev/null +++ b/content/doc/administrate/cache.md @@ -0,0 +1,68 @@ +--- +type: docs +title: Varnish as HTTP Cache +description: Configuring Varnish on Clever Cloud +tags: +- administrate +keywords: +- varnish +- varnish-modules +- caching +- cache +aliases: +- /administrate/cache +- /doc/tools/varnish +--- + +## Overview + +[Varnish](https://www.varnish-cache.org/) is a HTTP proxy-cache, which works as a reverse proxy between your application +and the client. Following rules defined by the user, Varnish will cache the data of an application to reduce the load on its server. We use **Varnish 7.7.1 and varnish-modules 0.26.0**. + + +> [!NOTE] Supported runtimes +> Varnish is available on **FrankenPHP**, **Go**, **Linux**, **Node.js**, **PHP with Apache**, **Static**, and **V (Vlang)** applications + +## Enable Varnish for your application + +To enable it, create a `varnish.vcl` file in the `/clevercloud` folder. You can also define `CC_VARNISH_FILE=/path/to/varnish.vcl` environment variable relative to your application root. This file describes how Varnish caches your applications and how it decides to return a cached resource or not. To know how to write your `varnish.vcl` file, have a look at the [Varnish 6 book](https://info.varnish-software.com/resources/varnish-6-by-example-book). + +The `vcl 4.1;` and backend section of the `varnish.vcl` configuration file are not necessary as they are already handled by Clever Cloud. +If you have a PHP FTP application or if your `varnish.vcl` file is on an FS Bucket, make sure you redeploy the application for the changes to take effect. + +## Listen on the right port + +Once varnish is enabled, your application should no longer listen on port **8080**, but on port **8081**. Because it's Varnish that will listen on port **8080**, and it will have in its configuration your application as backend. + +## Configure the cache size + +Change the storage size specified in the varnish.params file with the `CC_VARNISH_STORAGE_SIZE` environment variable (the default value is `1G`). + +```bash +CC_VARNISH_STORAGE_SIZE=2G +``` + +## Varnish 7 migration + +If you have a configuration for an older version of varnish, read [Upgrading to Varnish 7.0](https://varnish-cache.org/docs/7.0/whats-new/upgrading-7.0.html) guide. + +## Example files + +We provide some [examples of Varnish configuration files](https://github.com/CleverCloud/varnish-examples) that you can +use for your application. Create a `/clevercloud` folder at the root of your application if it does not exist, +rename the file to `varnish.vcl` and move it in the `/clevercloud` folder. + +## Varnish with a monorepo + +If you use a monorepo, you may want to use Varnish for only some of its applications. Use a dedicated `CC_VARNISH_FILE` for that. + +If you have a `/clevercloud/varnish.vcl` file at the root of your monorepo, all of your applications automatically start using it with Varnish. To resolve this create a symlink during the deployments: + +1. Put your `varnish.vcl` file anywhere but at the root of your monorepo. +2. Create a symlink inside a `CC_PRE_BUILD_HOOK` to the app that needs to use Varnish, such as: + +```bash +CC_PRE_BUILD_HOOK="mkdir $APP_HOME/clevercloud; ln -s $APP_HOME/path/to/your/file/varnish.vcl $APP_HOME/clevercloud/varnish.vcl" +``` + +If you don't add this variable, the application won't use Varnish. diff --git a/content/doc/administrate/clamav.md b/content/doc/administrate/clamav.md new file mode 100644 index 000000000..c602a473f --- /dev/null +++ b/content/doc/administrate/clamav.md @@ -0,0 +1,61 @@ +--- +type: docs +title: Clamav +description: Configuring Clamav on Clever Cloud +tags: +- administrate +keywords: +- apps +- antivirus +- clamav +--- + +[Clam AntiVirus](https://www.clamav.net/) is an open source (GPLv2) anti-virus toolkit, designed especially for e-mail scanning on mail gateways. It provides a number of utilities including a flexible and scalable multi-threaded daemon, a command line scanner and advanced tool for automatic database updates. The core of the package is an anti-virus engine available in a form of shared library. + +## ClamAV for all applications + +ClamAV is not enabled by default but it's available for all Clever Cloud applications. + +## Activate ClamAV + +You can set the **CC_CLAMAV** environment variable to enable ClamAV for your application: + +```bash +CC_CLAMAV=true +``` + +This variable is used to start these two services: + +* **clamav-daemon.service** (multi-threaded daemon that uses libclamav to scan files for viruses). +* **clamav-freshclam.service** (used to update signature database sets to the latest version). + +The signature database is updated every 2 hours. + +## Memory consumption + +ClamAV can consume a lot of resources, make sure you have a scaler with enough memory (at least 1GB available) to avoid a complete shutdown / crash of your application (OOM). + +## Unix and/or TCP sockets connections + +The ClamAV daemon on Clever Cloud instances listens for incoming connections on the following sockets: + +Unix socket: + +```bash +/run/clamav/clamd.ctl +``` + +TCP socket: + +```bash +localhost:3310 +``` + +Be sure to use these settings when configuring your ClamAV client. + +## Additional configurations + +`CC_CLAMAV_MAXTHREADS`: Maximum number of threads running at the same time. +`CC_CLAMAV_MAXQUEUE`: Maximum number of queued items. + +If you have special needs, you can make a request on [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice). diff --git a/content/doc/administrate/cron.md b/content/doc/administrate/cron.md new file mode 100644 index 000000000..f53aa5ab7 --- /dev/null +++ b/content/doc/administrate/cron.md @@ -0,0 +1,155 @@ +--- +type: docs +title: CRON +description: All you need to know about running crons on Clever Cloud +keywords: +- apps +- cron +- cronjob +- schedule +tags: +- administrate +aliases: +- /doc/tools/crons +--- + +The configuration file used for crontab is `/clevercloud/cron.json`. + +{{< callout type="warning" >}} + Crons are not available in the Docker environment as it would require to set them up inside the Docker container. +{{< /callout >}} + +## Syntax + +Here is the general syntax: + +```json +[ + "", + "" +] +``` + +The string `` must use the cron format: + +```javascript +M H d m Y command +``` + +- M: Minute [0,59] +- H: Hour [0,23] +- d: Day of the month [1,31] +- m: Month of the year [1,12] +- Y: Day of the week [0,6] (0 is Sunday) + +{{< callout type="warning" >}} + All the servers are configured to use Coordinated Universal Time (UTC), please keep it in mind when configuring cron tasks to run at a specific hour. +{{< /callout >}} + +For more information about the syntax, you can check [the Wikipedia page of cron](https://en.wikipedia.org/wiki/Cron). + +## Restrictions + +There are two restrictions about the usage of crontab on our platform: + +- The special date `@reboot` is not available since the crontab is added after the startup of the instance +- You must use the absolute path of commands + +{{< callout type="warning" >}} + We do not currently support the clustering of cron tasks, you must manage it yourself if your application requires more than one instance. +{{< /callout >}} + +## $ROOT + +You can use the special token `$ROOT` to refer to the root folder of your application. + +Example of `clevercloud/cron.json` which executes the file `cron.php` every 5 minutes: + +```json +[ + "*/5 * * * * /usr/bin/php $ROOT/cron.php" +] +``` + +Note: `$ROOT` is only a token (not an actual variable) which is replaced when setting up the crons by the equivalent of the `APP_HOME` variable (`/home/bas/`). Do not write `${ROOT}`, only `$ROOT` will work. + +## Access environment variables + +To have access to environment variable, you must wrap your commands in a bash script. Let's say +your command is `bundle exec rake myapp:dosomething`. + +You need to put it in a bash script, starting with `#!/bin/bash -l`. The *`-l`* is very +important: + +```bash +#! /bin/bash -l + +cd ${APP_HOME} # Which has been loaded by the env. +bundle exec rake myapp:dosomething +``` + +Then you need to commit an executable file: + +```bash +chmod +x crons/mycron.sh +git add crons/mycron.sh + +git diff --cached +$ diff --git a/crons/mycron.sh b/crons/mycron.sh +$ old mode 100644 +$ new mode 100755 + +git commit -m "Make cron file executable" +``` + +Then, in `clevercloud/cron.json`: + +```json +[ + "*/5 * * * * $ROOT/crons/mycron.sh" +] +``` + +### Avoiding double bash + +You might be tempted to put the following in your cron.json file: + +```json +[ + "*/5 * * * * /bin/bash $ROOT/crons/mycron.sh" +] +``` + +Do *NOT* do this. Invoking bash here will supersede the shebang and cancel the `bash -l` that +loads the env. So just put the path to your *executable* `mycron.sh`. + +You can refer to [this list](/developers/doc/develop/env-variables#special-environment-variables) to see which variables are available. + +## Deduplicating crons + +Crons are installed and executed on every scaler of an application. This means the same cron may be executed more than once. + +You can use your own techniques to avoid that, like a shared task queue or some other locking system. + +If you do want to stay stateless and simple, just your bash wrapper script by: + +```bash +#! /bin/bash -l + +if [[ "$INSTANCE_NUMBER" != "0" ]]; then + echo "Instance number is ${INSTANCE_NUMBER}. Stop here." + exit 0 +fi + +cd ${APP_HOME} # Which has been loaded by the env. +# Your part here +``` + +{{< callout type="warning" >}} + If [Zero downtime deployment](/developers/doc/administrate/apps-management#edit-application-configuration) is activated, Crons might overlap for a couple of minutes until the old instance are deleted as two instances would have the same instance number + You can prevent this by deactivating it. +{{< /callout >}} + +## Logs collection + +Everything coming from stdout & stderr is forwarded to our logs collection system and is available in the web console / CLI logs. diff --git a/content/doc/administrate/database-migration.md b/content/doc/administrate/database-migration.md new file mode 100644 index 000000000..11e2b9f13 --- /dev/null +++ b/content/doc/administrate/database-migration.md @@ -0,0 +1,61 @@ +--- +type: docs +title: Database migration +description: How to migrate your database to improve performance or security +keywords: +- database +- dbaas +- migration +tags: +- administrate +--- + +{{< hextra/hero-subtitle style="margin:.3rem 0 2rem 0">}} + Clever Cloud features a simple, elegant way of migrating your databases to change the size of the instance, or improving its security by updating the middleware on it. +{{< /hextra/hero-subtitle >}} + +## Migrating any database and updating its security + +Our databases add-ons are deployed on immutable Virtual Machines. No updates are made on those VMs. +To improve security, you need to perform a "migration", which will boot a new VM with up-to-date system and database. +Unless you want to upgrade your database to a new major version or to give it more resources, you just have to perform a migration on the same zone, same plan and same major version. + +These updates are not related to your add-on (PostgreSQL, MySQL…) major version. Only patches or minor versions of the add-on software along with system upgrades (security patches and new kernel features) are performed. For example, you can keep *PostgreSQL 11* if you want to. + +{{< callout type="warning" >}} +We **do not** support the migration of read only users except for PostgreSQL add-ons. If you have any, you will have to create new ones at the end of the migration. +{{< /callout >}} + +## Migration (updating) step-by-step + +{{% steps %}} + +### Go to your database menu + +### Go to the *Migrate/Upgrade* section + +You will see the disclaimer of the database migration assistant. It informs you that *your databse will be read-only during the migration process* and that the *hostname and database name will be automatically changed*. + +Regarding this, we strongly recommend that you make sure every linked application uses the database add-on environment variables so those values will be automatically updated in your application. + +### Click on *Migration Settings* + +A menu will open, where you will see your current database informations. + +Under you will see that you can select your new batabse size and pricing plan. Billing section in Summary will be edited accordingly. + +Under **Targeted version** you can choose the desired database version. + +Downgrading database is currently not supported, you can however ask [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice). + +### Select *Migrate the Database* + +You will be prompted to confirm the migration. + +As soon as you do so, the database will be set in read-only mode and the migration process will start. + +{{% /steps %}} + +If the process succeeds, you will get a success screen. Every linked applications will automatically restart to use the new configuration. Please make sure to update configuration that do not use environment variable if you have some. + +In case the database migration fails, you will be informed at which point it did and a button to contact our support team will appear. Reach out to [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice) with you add-on ID (available in the **Addon Dashboard** section) and they will help you finish the process. diff --git a/content/doc/administrate/domain-names.md b/content/doc/administrate/domain-names.md new file mode 100644 index 000000000..46424d71c --- /dev/null +++ b/content/doc/administrate/domain-names.md @@ -0,0 +1,217 @@ +--- +type: docs +title: Domain names +description: How to setup and configure domains names for your apps +tags: +- dashboard-setup +- apps +keywords: +- DNS +- domain +- URL +--- + +When creating an application, you have two (non-exclusive) choices for domain names: + +* Using a personal domain name +* Using a `cleverapps.io` free domain for development and testing purposes, with built-in SSL + +Add it in the application configuration: in the console, click **application name** in the first panel, then choose **domain names**. You'll have to choose to add a custom domain name or use a subdomain under `*.cleverapps.io`. + +{{< callout type="info" >}} + You can link one or more domain names to the same application. On the other hand, you can add `mydomain.com/app1` and `mydomain.com/app2` to different Clever Cloud applications at the same time through [path routing](#path-routing). +{{< /callout >}} + +## Primary (favourite) domain name + +You can set multiple custom or `cleverapps.io` domain names to an application, but only set one of them as the **primary (favourite)**. This is the one that will be used by default when you access your application with the `clever open` command of Clever Tools or through the link in the upper right corner of the Console: + +![Primary domain link](/images/primary-domain-link.webp) + +To select the primary domain name: +- Click the star icon next to the domain name in the **Domain names** section of your application in the Console +- Use the `clever domain favourite set example.com` command in [Clever Tools](/developers/doc/cli/applications/configuration/#domain) +- Use the dedicated `/vhosts/favourite` endpoint [in the API](/developers/api/v2/#put-/organisations/-id-/applications/-appId-/vhosts/favourite) + +## Testing with `cleverapps.io` Domain + +{{< callout type="warning" >}} + Clever Cloud provides `*.cleverapps.io` domains for development and testing purposes. They point to specific reverse proxies and have the following drawbacks: the `.io` TLD isn't made for production, and since we offer the domain, the likelihood of people abusing it can be very high. **It's therefore not possible to guarantee a high level of quality on cleverapps domains**. +{{< /callout >}} + +In the console, in the domain name sub menu of your application, there is a default entry configured by default for every new app: `yourAppID.cleverapps.io`, which can be removed. + +In your application's domain section, just enter `example.cleverapps.io`. You have to choose a unique one. Trusted SSL is available on every subdomain. + +{{< callout emoji="🌐" >}} +`*.cleverapps.io` certificate is only valid for the first subdomain level, it won't work with a domain like `blog.mycompany.cleverapps.io`. +{{< /callout >}} + +## Configuring Domain Names by Region + +It's possible to point your personalized domain name to Clever Cloud with either a type `A` or `CNAME` record through your registrar. + +{{< callout type="warning" >}} + The use of a CNAME record is **highly** recommended. +{{< /callout >}} + +With a `CNAME` record, your DNS configuration is always up-to-date. +Using `A` records requires you to keep the DNS configuration up-to-date manually. + +We also support wildcard personal domain names, to do so use the standard pattern to describe it: `*.example.com` + +### Europe/Paris (PAR) + +Provide the following to your registrar: + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.par.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 91.208.207.214`
`@ 10800 IN A 91.208.207.215`
`@ 10800 IN A 91.208.207.216`
`@ 10800 IN A 91.208.207.217`
`@ 10800 IN A 91.208.207.218`
`@ 10800 IN A 91.208.207.220`
`@ 10800 IN A 91.208.207.221`
`@ 10800 IN A 91.208.207.222`
`@ 10800 IN A 91.208.207.223` | + +### Europe/Paris HDS (PARHDS) + +Provide the following to your registrar: + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.parhds.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 91.208.207.214`
`@ 10800 IN A 91.208.207.215`
`@ 10800 IN A 91.208.207.220`
`@ 10800 IN A 91.208.207.221`
`@ 10800 IN A 91.208.207.222`
`@ 10800 IN A 91.208.207.223` | + +To benefit from certified hosting for health data, you need to deploy in an HDS zone and to sign up to a specific contract. This begins with [an initial discussion with our team](https://www.clever-cloud.com/fr/hebergement-donnees-de-sante/contact-hds/). + +### Europe/Paris onto Scaleway (SCW) + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.scw.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 212.129.27.239`
`@ 10800 IN A 212.83.186.147`
`@ 10800 IN A 212.83.186.216`
`@ 10800 IN A 212.129.27.183` | + +### Europe/Gravelines HDS (GRAHDS) + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.grahds.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 188.165.58.196`
`@ 10800 IN A 188.165.58.200` | + +To benefit from certified hosting for health data, you need to deploy in an HDS zone and to sign up to a specific contract. This begins with [an initial discussion with our team](https://www.clever-cloud.com/fr/hebergement-donnees-de-sante/contact-hds/). + +### Europe/London (LDN) + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.ldn.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 77.68.78.36`
`@ 10800 IN A 77.68.94.247` | + +### Europe/Roubaix (RBX) + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.rbx.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 87.98.177.176`
`@ 10800 IN A 87.98.177.181`
`@ 10800 IN A 87.98.180.173`
`@ 10800 IN A 87.98.182.136` | + +### Europe/Roubaix HDS (RBXHDS) + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.rbxhds.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 135.125.16.47`
`@ 10800 IN A 135.125.16.49` | + +To benefit from certified hosting for health data, you need to deploy in an HDS zone and to sign up to a specific contract. This begins with [an initial discussion with our team](https://www.clever-cloud.com/fr/hebergement-donnees-de-sante/contact-hds/). + +### Europe/Warsaw (WSW) + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.wsw.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 145.239.17.127`
`@ 10800 IN A 145.239.17.192` | + +### North-America/Montreal (MTL) + +Provide the following to your registrar: + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.mtl.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 158.69.109.229`
`@ 10800 IN A 149.56.117.183` | + +### Asia/Singapore (SGP) + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.sgp.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 51.79.197.159`
`@ 10800 IN A 51.79.197.160` | + +### Oceania/Sydney (SYD) + +| Record Type | Value | +| ----------- | ----- | +| CNAME
Recommended | `{yoursubdomain} 10800 IN CNAME domain.syd.clever-cloud.com.` | +| A
Only if CNAME is not available | `@ 10800 IN A 139.99.253.215`
`@ 10800 IN A 139.99.253.237` | + +{{< callout type="warning" >}} +You cannot use a CNAME on a top-level domain, or on a subdomain which already has DNS records. +{{< /callout >}} + +If you want to make your application available from a domain name which doesn't support CNAME records (eg `example.com` in addition to `www.example.com`), check if your registrar provides a web redirection service. This way, you only have to make `www.example.com` point to Clever Cloud. Please note that web redirection provided by registrars only work over HTTP. + +Remember that DNS changes may take time to propagate (usually a few hours, sometimes up to a day or more). It depends on the TTL setting of your DNS configuration. For faster changes, you can lower the TTL value in advance, and rise it again afterwards. + +{{< callout type="info" >}} +`*.example.com` match for instance `blog.example.com` or `www.example.com`. But for the raw domain `example.com`, you have to add both `*.example.com` and `example.com` to your application. +{{< /callout >}} + +### Contextual Example + +| Domain Name Use Case | CNAME config | Record A config | Web redirections | +|-----------------------------|-------------------------------------------------|-----------------------------------------------------------------|--------------------------------------------| +| `www.example.com`
`example.com` | Point `www.example.com` to `domain.par/mtl.clever-cloud.com.` | No A record needed | Redirect `example.com` to `www.example.com` | +| `www.example.com` | Point `www.example.com` to `domain.par/mtl.clever-cloud.com.` | No A record needed | No redirect needed | +| `example.com` | No CNAME record needed | Point `example.com` to the two IP addresses of the selected region | No redirect needed | + +## Path routing + +Requests are routed to applications based on the domain name, but you can also route depending on its path. + +For instance, you can bind `example.com` to an app, and `example.com/api` to another one. +All the HTTP requests on `example.com` where the path starts with `/api` are routed to +the second app. The other requests are routed to the first app. +You can add a path after every domain name you bind in the console (or with [clever tools](/developers/doc/cli "Clever Tools")). + +Note that your path-routed application **needs** to have a `/whatever` route. + +This will work: + +```text +example.com -> myfirtapp-main-route + +example.com/api -> mysecond-app-main-route/api +``` + +This will NOT work: + +```text +example.com -> myfirtapp-main-route (works) + +example.com/api -> mysecondapp-main-route (404 response from mysecondapp) +``` + +### Path routing for static sites + +In the case of static files, you usually understand routes as paths in a file tree. + +This will work: + +```text +example.com/api -> my-static-site/api/index.php +``` + +This will NOT work: + +```text +example.com/api -> my-static-site/index.php +``` + +## Gandi CNAME configuration + +Here is [an article that demonstrates a simple setup for Gandi CNAMEs](https://www.clever-cloud.com/blog/features/2019/03/05/gandi-domain-on-clever-cloud/). diff --git a/content/doc/administrate/encryption-at-rest.md b/content/doc/administrate/encryption-at-rest.md new file mode 100644 index 000000000..fcaf4db12 --- /dev/null +++ b/content/doc/administrate/encryption-at-rest.md @@ -0,0 +1,69 @@ +--- +type: docs +title: Encryption at rest +description: Learn how to enable encryption at rest for your add-ons on Clever Cloud, enhancing data security by encrypting data stored on disk +tags: +- encryption +- rest +- security +aliases: +- /administrate/encryption-at-rest +--- + +## Introduction + +Encrypting your data at rest provides another security layer to protect your data from various security threats. By default and unless you implemented it in your code, the data stored on disk is not encrypted. Enabling encryption at rest allows you to make sure your data can't be read by anyone having a physical access to the hard drive. + +Encryption at rest only protects the data "at rest", meaning that if your data is sent over an unencrypted channel on the network, it could be read on the fly. The scenario encryption at rest covers are mostly hard drives stealing or unauthorized access once the hard drive got removed. + +Here at Clever Cloud, before removing a hard drive, either because it is faulty or not used anymore, we first [shred](https://linux.die.net/man/1/shred) the hard drive with multiple passes. Then it is physically damaged by the data center operators before being thrown away. If one of those steps are missing or fail for some reason, your data could still be read if you didn't use encryption at rest. If you did, no one will be able to access it. + +## Technical details + +Encryption at rest works by decrypting the encrypted data disk and exposing it to the system in an unencrypted volume. Each time you read data on this unencrypted volume, the system will fetch the data on the encrypted disk and decrypt it. If you write data, the opposite happens: the data to be written is encrypted and then its encrypted content is written to the encrypted disk. + +Each add-on has a randomly generated encryption key used to encrypt the data disk. The key will stay the same during the add-on life but can be changed if needed. In that case, a migration will use the new passphrase. + +We use the [cryptsetup tool](https://gitlab.com/cryptsetup/cryptsetup) to operate encrypted disks. Cryptsetup's current default is [LUKS2](https://gitlab.com/cryptsetup/LUKS2-docs) with `aes-xts` as the encryption algorithm. This may be subject to change as cryptsetup and the security algorithms evolve. + +The encryption key is only stored encrypted on our systems and is not stored on your add-on. When your add-on boots, the key is downloaded over HTTPS from our systems and the disk is then mounted. + +We also have a small swap partition on add-ons to allow more available RAM for background services. This swap file is also encrypted to avoid any encrypted data leak. + +### Performances + +Performances may be a bit degraded with encryption enabled but in most of the cases under regular load, it is usually insignificant and an acceptable tradeoff. + +Also, depending on whether you are using a single vCPU add-on or a multiple vCPU one, numbers can greatly vary. Single vCPU instances will switch between decrypting/encrypting the data and reading/writing it to the disk while multiple vCPU instances will be able to parallelize those operations, leading to better performance. + +Note that most of the databases either have an in-memory cache or use the system's file cache so if the same data is often read, it may be available in the cache and no decryption occur leading to fast reads. + +Those tests were made using a 4 vCPU instance with 4 GiB of RAM. +Before each test, the system's cache was dropped to avoid having reads that are faster than they should be: `sync; echo 1 > /proc/sys/vm/drop_caches`. + +Note: The `dd` tool wasn't used for this benchmark as it does not represent a valid workload, leading to results that can greatly vary depending on disk performance. + +#### Using pgbench for PostgreSQL + +Using `pgbench` with 20 jobs and 20 clients, we see a difference between 3% and 5% less transactions per second on the encrypted disk and no real CPU difference. + +With encrypted disk, the number of transactions per second was 315. On the unencrypted one, it was 330 per second. + +#### Using sysbench for MySQL + +Using `sysbench` with 6 threads, the difference is between 5% and 10% less transactions per second. The CPU usage is also between 5% and 10% higher depending on the work load (reads or writes). + +With encrypted disk, the number of transactions per second was 635. On the unencrypted one, it was 703 per second. + +## Availability + +Encryption at rest is currently available for the following add-ons: + +- PostgreSQL +- MySQL +- MongoDB +- Redis +- Elastic Stack +- Jenkins + +Only dedicated add-ons have the option. If your add-on is not encrypted, you can ask our support team to configure it. A migration will then be needed to encrypt your disk. diff --git a/content/doc/administrate/log-management.md b/content/doc/administrate/log-management.md new file mode 100644 index 000000000..611c1379c --- /dev/null +++ b/content/doc/administrate/log-management.md @@ -0,0 +1,287 @@ +--- +type: docs +title: Logs management +description: How to manage add-ons and applications logs and drains +tags: + - administrate +keywords: +- logs +- log +- logging +- log drains +- drain +- drains +- datadog +- newrelic +aliases: +- /clever-cloud-apis/add-ons-log-collector +- /doc/administrate/log-management/#get-continuous-logs-from-your-application +- /doc/clever-cloud-apis/add-ons-log-collector +--- + +Clever Cloud new logs stack is based on Vector and Apache Pulsar. This Web Component allow you to check for live or past logs. You can target a specific time window, select logs lines and copy them in clipboard through keyboard and/or mouse. It's not available for add-ons yet. + +There are two text filter modes: exact match (case-sensitive) and regular expression. Settings panel offers lots of parameters such as dark/light themes, line wrapping, ANSI codes escaping, etc. You can also choose the date/time format, UTC or local, to show the instances name or not. + +![New logs interface](/images/new-logs.webp) + +This interface is constantly improving, send us your feedback through our GitHub Community: + +* [Give your feedback about new Logs interface](https://github.com/CleverCloud/Community/discussions/categories/new-logs-interface) + +{{< callout type="info">}} +Logs are retained for 7 days, sometimes more for specific customers/needs. +{{< /callout >}} + +## Get continuous logs from your application + +Log management is also available through [Clever Tools](https://github.com/CleverCloud/clever-tools) and our [APIv4](/developers/api/v4/#logs). They're collected and sent through the Vector service enabled in every application deployed on Clever Cloud. To disable it, set the `CC_PREVENT_LOGSCOLLECTION` environment variable to `true`. You can see logs with the command down below. + +```bash +clever logs +``` + +You can add `--since`, followed by a duration or a date (ISO8601 format). The `--until` flag should be followed by a date (ISO8601 format). + +```bash +clever logs --since 2h +clever logs --until 2024-04-15T13:37:42Z +``` + +You can also get your add-on's logs by using `--addon` flag, the value must be the add-on ID starting by `addon_`. + +```bash +clever logs --addon +``` + +{{< callout type="warning" >}} + With add-ons, only the last 1000 lines of logs are got by `clever logs`. +{{< /callout >}} + +### Access logs + +It contains all incoming requests to your application. Here is an example: + +```txt +255.255.255.255 - - [06/Feb/2020:07:59:22 +0100] "GET /aget/to/your/beautiful/website -" 200 1453 +``` + +They are available in different formats, the most common is CLF which stands for Common Log Format. + +You can see access logs with the following command: + +```bash +clever accesslogs +``` + +As with the `logs` command, you can specify `--before` and `--after` flags. +If you don't specify any options, the logs display continuously. + +To change the output, specify the `--format` flag with one of these values: + +- simple: `2021-06-25T10:11:35.358Z 255.255.255.255 GET /` +- extended: `2021-06-25T10:11:35.358Z [ 255.255.255.255 - Nantes, FR ] GET www.clever-cloud.com / 200` +- clf: `255.255.255.255 - - [25/Jun/2021:12:11:35 +0200] "GET / -" 200 562` +- json: + + ```json + { + "t":"2021-06-25T10:11:35.358209Z", + "a":"app_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "adc":"clevercloud-adc-nX", + "o":"orga_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "i":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "ipS":"255.255.255.255", + "pS":58477, + "s":{ + "lt":50.624, + "lg":3.0511, + "ct":"Nantes", + "co":"FR" + }, + "ipD":"46.252.181.17", + "pD":14001, + "d":{ + "lt":45.7059, + "lg":4.7444, + "ct":"Chaponost", + "co":"FR" + }, + "vb":"GET", + "path":"/", + "bIn":658,"bOut":562, + "h":"www.clever-cloud.com", + "rTime":"31ms", + "sTime":"75μs", + "scheme":"HTTPS", + "sC":200,"sT":"OK", + "w":"WRK-01", + "r":"01F91AEG8Z9RJKYB7JY7H56FNB", + "tlsV":"TLS1.3" + } + ``` + +## Exporting logs to an external tool + +You can use the logs drains to send your application's logs to an external server with the following command. + +```bash +clever drain create [--alias ] [--username ] [--password ] +``` + +Where `DRAIN-TYPE` is one of: + +- `TCPSyslog`: for TCP syslog endpoint; +- `UDPSyslog`: for UDP syslog endpoint; +- `HTTP`: for TCP syslog endpoint (note that this endpoint has optional username/password parameters as HTTP Basic Authentication); +- `ElasticSearch`: for Elasticsearch endpoint (note that this endpoint requires username/password parameters as HTTP Basic Authentication); +- `DatadogHTTP`: for Datadog endpoint (note that this endpoint needs your Datadog API Key). + +You can list the currently activated drains with this command. + +```bash +clever drain [--alias ] +``` + +And remove them if needed + +```bash +clever drain remove [--alias ] +``` + +If the status of your drain appears as `DISABLED` without you disabling it, it may be because it haven't been able to send your application logs to your drain endpoint or because the requests timed out after **25 seconds**. + +Use the logs drain to send your add-on's logs by using `--addon` flag, the value must be the add-on ID starting by `addon_`. + +### Elasticsearch + +ElasticSearch drains use the Elastic bulk API. To match this endpoint, specify `/_bulk` at the end of your Elasticsearch endpoint. + +```bash +clever drain create ElasticSearch https://xxx-elasticsearch.services.clever-cloud.com/_bulk --username USERNAME --password PASSWORD +``` + +Each day, we will create an index `logstash-` and push logs to it. + +#### Index Lifecycle Management + +Depending on the amount of logs generated by your application, you might want to manage the lifecycle of your log indexes to prevent your Elasticsearch instance from running out of storage space. + +To do so, Elasticsearch provides a feature called [Index Lifecycle management](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-management.html) that allows you to create a policy to delete indexes based on their creation date. + +With our Elasticsearch add-on, you can choose to create a Kibana application in which you can create the policy and apply it to your indexes with an index template, but you can create them manually through API requests. + +Here is an example that will create a policy to delete indexes older than 30 days: + +```bash +curl -X PUT "https://username:password@xxx-elasticsearch.services.clever-cloud.com/_ilm/policy/logs_drain?pretty" -H 'Content-Type: application/json' -d' +{ + "policy": { + "phases": { + "delete": { + "min_age": "30d", + "actions": { + "delete": {} + } + } + } + } +} +' +``` + +An index template example to apply the policy based on an index pattern: + +```bash +curl -X PUT "https://username:password@xxx-elasticsearch.services.clever-cloud.com/_index_template/logs_drain?pretty" -H 'Content-Type: application/json' -d' +{ + "index_patterns": ["logstash-*"], + "template": { + "settings": { + "index.lifecycle.name": "logs_drain" + } + } +} +' +``` + +For more information, please refer to the [official documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/set-up-lifecycle-policy.html). + +### Datadog + +To create a [Datadog](https://docs.datadoghq.com/fr/api/latest/logs/#send-logs) drain, you just need to use: + +```bash +clever drain create DatadogHTTP "https://http-intake.logs.datadoghq.com/v1/input/?ddsource=clevercloud&service=&hostname=" +``` + +{{< callout type="warning" >}} +Datadog has two zones, **EU** and **COM**. An account on one zone is not available on the other, make sure to target the right intake endpoint (`datadoghq.eu` or `datadoghq.com`). +{{< /callout >}} + +### NewRelic + +To create a [NewRelic](https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/) drain, use: + +```bash +clever drain create NewRelicHTTP "https://log-api.eu.newrelic.com/log/v1" --api-key "" +``` + +{{< callout type="warning" >}} +NewRelic has two zones, **EU** and **US**. An account on one zone is not available on the other, make sure to target the right intake endpoint (`log-api.eu.newrelic.com` or `log-api.newrelic.com`). +{{< /callout >}} + +### OVHcloud Logs Data Platform + +To export logs from an application or an add-on to [OVHcloud Logs Data Platform](https://help.ovhcloud.com/csm/en-ie-logs-data-platform-quick-start?id=kb_article_view&sysparm_article=KB0055819), use the following setup: + +- A **TCP** drain log with `clever drain create TCPSyslog` +- Your Logs Data Platform **host** with **port** `514` (SSL ports aren't supported for TCP drains) +- The **write token** for your stream (provided on your Logs Data Platform console) + +On your terminal, use the following command: + +{{< tabs items="Application,Add-on" >}} + + {{< tab >}}**Exporting logs from an application**: + + ```shell + clever drain create TCPSyslog tcp://:514 -app --sd-params="X-OVH-TOKEN=\"\"" + ``` + + Replace the following values: + + - `` + - `` + - `` + + {{< /tab >}} + + {{< tab >}}**Exporting logs from an add-on**: + + ```shell + clever drain create TCPSyslog tcp://:514 -addon --sd-params="X-OVH-TOKEN=\"\"" + ``` + + Replace the following values: + + - `` + - `` + - `` + + {{< /tab >}} + +{{< /tabs >}} + +### Community software + +{{< callout type="info">}} +Community software isn't directly supported by Clever Cloud. It's developed by our community. We don't guarantee their maintenance or correct functioning. +You are better off opening issues on their GitHub repositories than contacting Clever Cloud support. +{{< /callout >}} + +#### HTTPS-based solution + +Some tools available on GitHub enable to create a drain to collect logs through an HTTPS endpoint. [This project](https://github.com/sebartyr/http-logs-drain), for example, is fully compatible with Clever Cloud. + +You could host it as an app and an add-on on Clever Cloud. A complete README explains all the features. diff --git a/content/doc/administrate/network.md b/content/doc/administrate/network.md new file mode 100644 index 000000000..c6432bb28 --- /dev/null +++ b/content/doc/administrate/network.md @@ -0,0 +1,73 @@ +--- +type: docs +linkTitle: Networking and IP +title: Networking and IP addresses ranges +description: What are my application's outgoing IP? +keywords: +- network +- ip +- range +- outgoing +- security +tags: +- administrate +--- + +Some services external to Clever Cloud require filtering their clients' source IPs. They +may call it "whitelist" or "allowlist". Since your applications may be deployed +"somewhere" inside your chosen zones, you cannot predict the IP they are going to +come from. + +Here's a bit more insight on the subject: + +## Custom network services + +### Unique IP service + +For each region, we provide a unique IP service. +This service allows your queries to some external services to come from a fixed and unique IP. + +This service does not appear in the Console at the moment. +The best is to ask the support team that will set it up for you and provide you with the needed information. +At the time of writing this doc, this service was billed 30€/month. +The price does not change with the number of applications that will use it. + +The IP depends on the zone, so ask the support about it. + +### VPN service + +Some external services, customers or providers may propose/require a encrypted Virtual Private Network between Clever +Cloud's regions and their datacenter to secure the traffic. + +We provide three kinds of VPN technologies: + +- [Wireguard](https://www.wireguard.com/): our favorite VPN technology. Has been adopted + by most major "off-the-shelf" VPNs (like the ones that sponsor Youtubers 😉). +- [IPSec](https://www.wikiwand.com/fr/IPsec): used by a lot of companies. It might be + their only available VPN technology. +- [OpenVPN](https://openvpn.net/): less used by companies, but still quite common. + +If you are interested, please ask the support / your sales contact for a quote. + +## The "Paris" region + +The Paris region is owned and handled by Clever Cloud. We own or entrust the associated AS's and +IP addresses ranges. + +Here are the current two addresses ranges your application may have an outgoing IP in: + +- 91.208.207.0/24 +- 185.133.116.0/22 + +Clever Cloud may change these ranges at any moment while we expand our infrastructure. If +filtering source IPs is important to you, please check this page, or opt into our Unique +IP service or a VPN Service. + +Please note that allowing all ranges means you "allow" **all Clever Cloud +applications** running in the Paris region to access that service. +This means you should not base all that service security solely on filtering source IPs! + +## The other regions + +The other regions we provide are hosted by other providers (OVHCloud, Scaleway, Oracle Cloud). +In this case, we use the IPs they provide to us and have no control over the ranges. diff --git a/content/doc/administrate/scalability.md b/content/doc/administrate/scalability.md new file mode 100644 index 000000000..d64aac2a9 --- /dev/null +++ b/content/doc/administrate/scalability.md @@ -0,0 +1,96 @@ +--- +type: docs +title: Application scaling +description: How does Clever Cloud give your application the resources it needs? +tags: +- administrate +keywords: +- scale +- scalability +- autoscale +aliases: +- /administrate/scalability +- /doc/clever-cloud-overview/scaling +- /doc/deploy/application/scalability +- /doc/scaling-tips +--- + +When your application is running, you don't have the same number of users all the time. During an event for example, +the number of users can increase, as will the load on the server. If too many requests are done on your +server at the same time, the response time will increase and could slow down your website. + +To avoid this problem and keep a fast website, the main solution is to deploy more **Scalers** for your application to +support the load. That's what scaling is: adapting automatically the number of **Scalers** and their size to fit the +load of your application, without any action from you. + +Clever Cloud gives you the ability to fine tune your application's scaling by managing both horizontal and vertical +scaling. These two parameters can be combined to adapt to your needs. + +## What is a Scaler? + +A **Scaler** is a Clever Cloud "instance". It is an individual and independent virtual machine hosting your application. A Scaler is defined by two factors: RAM and CPU. + +With the Scalers, Clever Cloud gives you the ability to scale your application **up and down** with **two non +exclusive methods**: horizontal and vertical scaling. + +{{< callout type="warning" >}} + Nano and pico instances operate with **reduced CPU priority** on the host system. As a result, during periods of high load on the hypervisor, these instances may experience performance degradation (since they yield processing power to higher-priority workloads). +{{< /callout >}} + +### Enable auto-scalability + +To enable the scalability of your application, open the [console](https://console.clever-cloud.com/) and go in the +"scalability" section of your application. Then, enable the auto-scalability. + +## Horizontal scaling + +You can enable it by defining how many maximum instances you need under the "Horizontal scaling" section of the "Scaling" menu. + +In case of large traffic, we detect a high load on your application and spawn **another instance in parallel**. +This will automatically set up another identical application with same size. Both will run in parallel with load +balancing. If the traffic grows even more, we will repeat the process until the maximum instances count you defined. + +{{< callout type="info" >}} +The maximum number of Scalers you can set for an application is 40. +{{< /callout >}} + +This process is exactly the opposite when the **load decreases**. A Scaler is removed and so on till a **minimum +reasonable level** is reached. + +The following scheme depicts a Scaler replication in case of a load increase: + +![Horizontal scaling: numbers of scalers](/images/scaling_horizontal_scheme.jpg "Horizontal scaling: you can define the min and max numbers of Scalers you need.") + +![Numbers of scalers between 1 and 15](/images/select-scalab-horizontal.png "Horizontal scaling: the amount of Scalers will evolve between 1 and 15.") + +## Vertical scaling + +In case of large traffic, we detect a high load on your application and set up **a new larger Scaler**. + +{{< callout type="info" >}} +The maximum Scaler size is 3XL: 16 vCPUs and 32 GiB of memory. +{{< /callout >}} + +In case of low traffic, we detect a low load and set up **a new smaller Scaler**. + +You give more power to your application by setting up a larger instance that will replace the previous one. The more the +load, the larger the instance. + +The following scheme depicts a larger Scaler replacement in case of a load increase: + +![Vertical scaling](/images/scaling_vertical_scheme.jpg "Vertical scaling") + +You can choose the size of Scalers you want by defining a maximum instance size manually: + +![Scaler size from S to XL](/images/select-scalab.png "Vertical scaling: the Scaler size will go from S to XL.") + +## Combination of both scalings + +When both scalings are set up, **vertical scaling** is privileged over **horizontal scaling**. In the case you set the +vertical scaling from S to L, and the horizontal scaling from 2 Scalers to 4 Scalers, Clever Cloud will firstly increase +the size of the 2 Scalers already launched. + +If the 2 initials Scalers are at their maximum size, Clever Cloud will launch new Scalers with the maximum Scalers size. +This is how it'll be done: + +2-S => 2-M => 2-L => 3-L => 4-L. diff --git a/content/doc/administrate/service-dependencies.md b/content/doc/administrate/service-dependencies.md new file mode 100644 index 000000000..424cca80a --- /dev/null +++ b/content/doc/administrate/service-dependencies.md @@ -0,0 +1,51 @@ +--- +type: docs +title: Service Dependencies +description: Materialize the logical dependencies between your applications with service dependencies +tags: +- administrate +keywords: +- application +- dependencies +- services +- configuration +aliases: +- /doc/admin-console/service-dependencies +- /doc/databases-and-services/add-service +- /doc/services-dependencies +--- + +On Clever Cloud, each application depends on one or more backing add-ons. Each +add-on exposes configuration, which allows the user to choose which add-on link +to an application. + +In a micro services architecture, backing services can be add-ons or other +applications. Clever Cloud allows you to declare the dependencies between +applications in the same way you can declare a dependency from an application +to an add-on. + +Clever Cloud allows to declare the topology of your micro services graph by +letting you link applications in the same way you can link add-ons. + +![Service dependencies](/images/service-dependencies-example.png "Service dependencies") + +To link an application to another, go to the "Service Dependencies" tab and +add the applications you depend on. + +## Exposed configuration + +Each application can expose configuration to be used by other applications. +For instance an API can expose its URL and credentials to access it. The +exposed configuration will be injected in the dependent applications' +environment. + +{{< callout type="warning" >}} +The configuration exposed by an application is available in the environment variables of the **dependent** applications, but not in the environment of the application itself. +{{< /callout >}} + +### Redeploy on configuration update + +When an application updates its exposed configuration, all applications +depending on it are automatically redeployed. + +![Automatic redeployment](/images/service-dependencies-config-update.png "Automatic redeployment") diff --git a/content/doc/administrate/ssh-clever-tools.md b/content/doc/administrate/ssh-clever-tools.md new file mode 100644 index 000000000..cce85d642 --- /dev/null +++ b/content/doc/administrate/ssh-clever-tools.md @@ -0,0 +1,134 @@ +--- +type: docs +linkTitle: SSH access +title: SSH access to running instances +description: How to SSH access running instances on Clever Cloud +tags: +- administrate +keywords: +- ssh +- cli +- clever-tools +- putty +aliases: +- /doc/admin-console/ssh-keys +- /doc/doc/admin-console/ssh-keys +- /doc/reference/clever-tools/ssh-access +- /doc/tutorials/ssh_keys +--- + +## Overview + +Clever Cloud allows you to connect to running instances via SSH. + +While direct SSH access to instances is not recommended in an [immutable infrastructure](https://boxfuse.com/blog/no-ssh.html) setup, it can be useful for debugging purposes. + +## Purpose + +Clever Cloud instances are to be seen as _read-only_ resources. Any change made on an instance **will not be persisted**. You can use SSH access for quick tests, but if you want to persist changes, you need to commit them in your repository. Changes made on instances are not kept across deployments. + +{{< callout type="warning">}} +For security reasons, you can't connect on the instance that hosts your Docker application. Instead, if `bash` is installed in your Docker application, you will be able to connect directly inside your container. Contact the support if you need help to debug your Docker applications. +{{< /callout >}} + +## Requirements + +You need to have at least one of the following installed locally: + +* the [Clever Tools CLI](/developers/doc/cli/) +* an SSH client (e.g [putty](https://putty.org/) for windows users) + +### Make sure you have a properly configured SSH key + +To use SSH access, you need to have a SSH key properly configured in your Clever Cloud account. Please refer to [the SSH keys section of the documentation](/developers/doc/account/ssh-keys-management) to know how to set up your SSH keys. + +## Using Clever Tools CLI + +In order to access the machine via SSH using the Clever Tools CLI +you need to have an application running on Clever Cloud and have linked it with your local repository using the Clever Tools CLI with `clever link --org ` + +### Accessing your machine + +You can access running instances of a linked application with `$ clever ssh` in the linked application's repository locally. + +```shell +clever ssh +> Opening an ssh shell +> bas@67fbf787-3518-47bb-abd9-2c2575844edd ~ $ +``` + +If multiple instances are running, you will be asked which one to use: + +```shell +clever ssh +> 1) Sleepy Ponita - Instance 0 - UP (11281f38-31ff-43a7-8595-a2d82630c32b) +> 2) Tense Caterpie - Instance 1 - UP (b10d19d9-5238-408b-b038-3e32c7a301c2) +> Your choice: 1 +> Opening an ssh shell +> bas@11281f38-31ff-43a7-8595-a2d82630c32b ~ $ + +You are now connected to the machine. +``` + +### Note for Windows users + +`$ clever ssh` command will fail on PowerShell or cmd.exe if there is no `ssh.exe` in your path. The most straightforward solution is to start `$ clever ssh` from `git-bash` but you can also add `ssh.exe` in your path.. + +## Using an SSH client + +You can connect using only your ssh client: + +```shell +ssh -t ssh@sshgateway-clevercloud-customers.services.clever-cloud.com +```` + +You can omit the application ID. In that case, you will be prompted to choose an organisation and an application. + +You can validate connection to remote server with this fingerprint : + +```shell +ED25519 key fingerprint is SHA256:lys1oC3plDGyAsWD7Yd5fJVKQUV/Pbn/M5KI5GyAj5s. +RSA key fingerprint is SHA256:0odQb8NQPKYNCme2Nf3Xrz3Bc9kmrDK6eSJGIzj9aEA. +``` + +{{< callout type="warning" >}} +The `-t` flag is mandatory for the ssh connection to work properly. If your terminal hangs and you see `pseudo-terminal will not be allocated because stdin is not a terminal`, it's likely you've forgotten the `-t` flag. +{{< /callout >}} + +## Access your application's folder + +No matter which way you've decided to use to SSH to the machine, your application's folder is located at: `/home/bas/`. + +## Show your application's logs + +If you want to show your application's logs while you debug: + +```shell +journalctl -efa -u bas-deploy.service +``` + +You can also use `journalctl` [with other options](https://www.commandlinux.com/man-page/man1/journalctl.1.html) if you need to. + +## Troubleshooting + +A commonly encountered issue when using `clever ssh` is: +``` +Error: Failed to choose instance: 'Error while running choice script: Error: This application has no instances you can ssh to' +``` + +First, make sure your application is running, otherwise there is no instance to connect to. + +If your application is up, this means you aren't allowed to access the organisation or application. This might be due to permission issue. +If you're supposed to have access to the application, this is likely due to a key management issue. To fix it: +* make sure you've added your public key on your Clever Cloud profile. You can refer to our documentation to [add your SSH key on Clever Cloud](/developers/doc/account/ssh-keys-management#add-a-public-ssh-key-on-clever-cloud) +* make sure your SSH agent is using the proper private key + +A useful command for debugging is: +``` +ssh -t ssh@sshgateway-clevercloud-customers.services.clever-cloud.com -v +``` + +This command shows information about your SSH connection attempt, such as the key, and the organisation your key is linked to. + +If you don't see your SSH key listed, you must [add it to your SSH agent](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent). +If your key is present but not resolved as the first one in the list, you can [force the use of a specific key](/developers/doc/account/ssh-keys-management/#configure-your-ssh-agent) diff --git a/content/doc/administrate/ssl.md b/content/doc/administrate/ssl.md new file mode 100644 index 000000000..4c81d0677 --- /dev/null +++ b/content/doc/administrate/ssl.md @@ -0,0 +1,220 @@ +--- +type: docs +title: Installing TLS Certificates +description: How to get HTTPS on Clever Cloud +keywords: +- ssl +- tls +- certificate +- https +- encrypt +- cloudflare +- rsa +- ECDSA +tags: +- administrate +aliases: +- /doc/tools/ssl-certificates +--- + +[TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) certificates (updated, more secure, version of SSL) are necessary to enable secure HTTPS connections between a browser and your application. These certificates can be bought online, or generated by Clever Cloud. In that case, we manage the whole process for you. + +There is two ways to get HTTPS for your apps: + +- **Let's Encrypt**: Provided by default by Clever Cloud. Free. Nothing to configure. +- **Your own certificates**: If you already have a certificate, you can upload it securely. + +## Getting Certificates with *Let's Encrypt* + +Clever Cloud automatically generates and renews TLS certificates for your domains. To enable this: + +1. Add your domain to the application: + - Use the Console or + - Use clever-tools +2. [Configure your DNS records](/developers/doc/administrate/domain-names) to point to Clever Cloud's load balancers + +{{< callout type="info" >}} + Note: Certificate generation attempts occur **only during the first 3 days** after adding a domain. To restart this window, remove and re-add the domain to your application. +{{< /callout >}} + +### Alternative Options + +#### Immediate Certificate Coverage +To avoid any period without certificate coverage (e.g., during migration from another provider): +1. [Upload your existing certificate](#uploading-my-own-certificates) first +2. Let Clever Cloud generate a new certificate automatically when your uploaded one expires + +#### Wildcard Certificates +Clever Cloud's automatic certificate generation doesn't support wildcard certificates. For wildcard certificates, you can: +- Generate your own Let's Encrypt certificate +- Purchase a commercial certificate +- [Contact support](https://console.clever-cloud.com/ticket-center-choice) for a quote on managed certificate services + +Need immediate certificate generation? [Contact the support team](https://console.clever-cloud.com/ticket-center-choice) for manual activation. + +### Cloudflare configuration + +If you use Cloudflare to manage your domain, the certificate generation could fail depending on your **SSL/TLS** settings, you will encounter 502 HTTP errors if Cloudflare expects **SSL/TLS** strict mode and automatically redirects to HTTPS. + +To prevent this from happening you can create a page rule to bypass this policy as Let's Encrypt needs to access the route `/.well-known/acme-challenge*` via HTTP to generate the certificate: + +{{% steps %}} + +#### Define a page rule + +![Bypass page rule on Cloudflare](/images/cloudflare-page-rule-ssl.png "Create a bypass page rule") + + We also recommend to disable the cache level. + +#### Turn off HTTP to HTTPS redirection on Cloudflare + +![HTTPS set up on Cloudflare](/images/cloudflare-https-setting.png "Turn off automatic HTTPS redirection") + + You can enable [Force HTTPS](/developers/doc/administrate/apps-management#edit-application-configuration) in the information tab of your Clever Cloud application instead. + +{{< callout emoji="💡" >}} +**If Let’s Encrypt fails to generate the certificate**, you can test that the acme-challenge url works by running the command below: +{{< /callout >}} + +```Bash +$ curl http:///.well-known/acme-challenge/test +test +``` + +It should return a HTTP 200 OK with the string "test" as the body. If it does not, check your Cloudflare configuration. + +{{% /steps %}} + +## Uploading my own certificates + +You can upload certificates yourself: [https://api.clever-cloud.com/v2/certificates/new ↗](https://api.clever-cloud.com/v2/certificates/new) + +### Prerequisites + +You need to paste a PEM bundle containing (in this order): + +- the private key +- the certificate itself +- intermediate certificates (optional) + +{{< callout type="warning" >}} + Only certificates with RSA 2048 and RSA 4096 keys are supported. + **ECDSA certificates are not currently handled**. +{{< /callout >}} + +You should create a `file.pem` containing: + +```text {filename="file.pem"} +-----BEGIN PRIVATE KEY----- + +-----END PRIVATE KEY----- +-----BEGIN CERTIFICATE----- + +-----END CERTIFICATE----- +``` + +You may need to mention the algorithm in the footer and header. +For instance, if the previous format doesn't work, try to use +`-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----` + +You can add optionnal intermediate certificates by appending them to the file as + +```text +-----BEGIN CERTIFICATE----- + +-----END CERTIFICATE----- +``` + +You should note that `.pem`` files use the unix way of terminating lines with a single line feed character. Make sure your text editor does the same. + +### Certificate Submission Checklist + +You `.pem` file must be correctly formatted to successfully upload your certificate. This checklist might help you troubleshoot uncesuccessful certificate submission. + +| Certificate Specifications | +|------------------------| +| ✅   The private key is included | +| ✅   Keys lenght are RSA and either 2048 or 4096 | +| ✅   ECDSA is not used to create your certificate | +| ✅   The line feed (LF) characters at the end | +| ✅   The certificate chain include your certificate together with all the intermediary CA certificates that signed it, in that order | + +## Sending Certificates Manually + +{{< callout emoji="👎" >}} +You should be aware that sending certificates manually is **NOT RECOMMENDED**. +Prefer another method, such as the certificate generation integrated into *Let's Encrypt*, or using our certificate [upload tool ↗](https://api.clever-cloud.com/v2/certificates/new). +If you have no other choice, then do not send these files by a means that is not secure. The integrity of your certificate will no longer be guaranteed. +{{< /callout >}} + +In the event that you request the installation of a certificate by the support team, this operation will be charged on a one-off basis for each request. Please contact us for installation rates. + +### Sharing Certificates via Keybase + +Another way to transmit your certificates is Keybase. +Keybase is an encrypted social networking service providing a key directory that maps social media identities to encryption keys (including, but not limited to PGP keys) in a publicly auditable manner. Additionally it offers an end-to-end encrypted chat, you can use to share sensitive informations, such as SSL/TLS certificates. + +If your are a Keybase.io user, you can find us at [keybase.io/clevercloud](https://keybase.io/clevercloud). + +### Sharing Certificates via GPG + +Email can be a secure way to transfer your certificates **when using a signed and encrypted email with GPG**. +Our dedicated email for receiving certificates is [ssl@clever-cloud.com](mailto:ssl@clever-cloud.com). + +- fingerprint: `03943517934C1FA5ED4E2F61218B86BD5278470F` +- 64-bit: `218B86BD5278470F` + +```bash +-----BEGIN PGP PUBLIC KEY BLOCK----- +Comment: GPGTools - https://gpgtools.org + +mQINBFa4bJMBEAC21vsfJ1ay5iVUcKsP8X8GziZu8daV5G4Lqpns54zN/GB05f9+ +3jV1RYRMweq7RC6XU/GDZo20ksvDw0N963/WCswCt0MyzM1O105tZ/ZbYyVV/w5w +763DXCUPdBhzcA7o31A7JgPimiceP/BcyA8CniLSD4nfzD0CiM74kdG5/vx2Ve9T +vkJ0wX5qWFvEivBPf/+jUfmdwtx5RLjH783xRuh0wWcz9ey/hsuLxJmdDuIlUccu +yH0itAMiLmI0yGscTVQ6pmLmEY1GZY3GSrTZbDOrKbJLxPjtRAtW8JvE1UD9AOqs +yvJ+QYp+6viEkQg0Fq2agCkpWTEy/6INGvjwexHkq9zUBe/Dm0awcqg46GSY8cwA +gqaaV32hPwv4fYMsz8fH50DDIAmKjJspWTeehnaXUSmr9lHpYH/l1mHPOtCvBL2e +m52YAKF5bCQEwn1p/UsysxtTaOrLO3ZoRTpM9lAeR3SfM768lnLzpI2AcpyJ95jg +btibuy59WvCQMdbA6UneaWxaOhSAtAB3OzHauXhQzru1BXfy5VOva5YHgH+4xS9n +7aqMxG0uB9X7wcPPV9FHFv+6QnKZ1fHLf6zN0tUjoXTIS6egbJqtYcTbDE8nRgoU +rwEadolEVSNnTEX3cfdueUHslMZwF+U30RG2bHSJTmUTOnVT6g1zk2hxwwARAQAB +tD5DbGV2ZXIgQ2xvdWQgKENsZXZlciBDbG91ZCdzIFNTTCBlbWFpbCkgPHNzbEBj +bGV2ZXItY2xvdWQuY29tPokCPQQTAQoAJwUCVrhskwIbAwUJB4YfgAULCQgHAwUV +CgkICwUWAgMBAAIeAQIXgAAKCRAhi4a9UnhGDwbQD/49Ol6HlYivxbxHi+uZdI2V +RoRLQlbTjrpIWc3ENJSjo19w7ntirsTkAmwh80Uvf72dLTPT3/dAa7qDiLHbaEPq +1Qr9XWgvb1rs/iXaJyEG/bhPEYoB/cvV+C921vArx6R8ZaUV0GZnZraOQgXCXq/y +a7QdM+wnh2abRwEOUFqVc2q2/N/1SjCKx9cCk2v4s3/chC/EZfUw3AoDQSwRkKYk +JD8r5r7TP7m048KreIKL5YNh9M6ybfsXPAtVRT3qIXFFDhrTcTvRokf50EFDwGVC +7miSaDDBLzQOJaaAD4j7I+QsiiKJSE41bymPcNNtZ/StILVTtmUSWSZAYC5Ke/PI +78o/0Hp3vT2WUw3w4iAHhbDhaPk+swC1rzTvPUXNb0ELVZb23ouPGqn0gMFcv0I5 +ojQ+hH/J5kQ2VvRUc7aCzA6Cqqavn9FljlwbI/Vro562GTkHQnmvKAnTYLomhFyL +TLrCs8vnLIVBJiSO4v/di6GhderDGjeeEgKXN+BuxU+V1u4kTp9uRjlNtEHoGPo7 +n38nChtFmRkfCp8eBXKDTZllxHUoiBSbEpY64zr3D3X9KTRBbS+JJXFpTcHJXeC2 +Ifc+5rOeJFjjmQ7iui0u0wwGaXY5WaQYd7zQ2rQz8pDaINsOAMTdaRJ5rPFBmAAn +KX7GBYRhPwWB0sjSHhRttLkCDQRWuGyTARAAp2fLCM77rmEREyt4Rn2Psd+RU6Ad +4k5Zlug6JE0BC9H340RKo3ViXV258Yqg2ra8rr9anJ4qX+T5ZsgVQ6daRstE7l9N +d62w+86ZcI+av3ncAKAihZsuZeZiI4NldCFoaJUu2Ixt/Bk4ppY+Uo0MkdL3Rq/6 +pEt4WGjOm+KMY38mSYGgzkdyOrncZ8+XY8UFvza/MAu4ukuduh+uozXRvCiaeiEx +4OhPR4TksZ6RrP++f/ZywTf19Qn3/7ickW4TU7F/khGMg+xtTkgFA+pdes2JrfgF +G7zvLIsQqfB7rNTNPHaQhazdQDWX9ylzg+Az/uoF3nMcEgLdawm2X70cyzo0ogt1 +F1f+juMvJJ+W7ao7Dfve0qoSQtEOmmR8sc4vVBzdPAFCOh8QYqm1z4JGbDcmWfG4 +ypGbBXBiGLyeJRm3o4iRBkAl7jkSNJeDnO4ajrTmZYSpO/NecbWAiybIxpoqQ3Yy +36XyTJJp6sie/6BWEF+tJUC4w4jQiuGeE+As9VwkGnsH0+m9gOwiO/TUocrxOHal +W2GB6s9V2zBqMFHEwKZgGZXLMG7IbiHS72QnrynwZpkAW328SUb/DgkI5DbbeVDG +tFNHBDiqxFgREv7c8DpnnJK7WX59HAZlXDcz1jfc6oKCFILDB0ujfuceRMGCxZ7m +Slkp3cHibEvsW18AEQEAAYkCJQQYAQoADwUCVrhskwIbDAUJB4YfgAAKCRAhi4a9 +UnhGD1zuD/99suvRucY3IJXHFCsV4wHIVgerU86sx3w0Nu5p18feqEf6K9tODZ32 +NcFKaWKVZ7tK1G0fzOnoLiT/Pzhu2pjq+cFN9t1CQy5U2cyFRRbrkd64LsIU6Nln +BVLNTje+akWnF3ezOSYvU02LElt4HQgTE1fMh7lolNcDrsg3hAd7vWJsr5r9MNtL +hxKrRjT1P+5op+lomSHeeWMnj2DxnwyA4es7fRfHcqC6fCW39Plhl6uCGaKNaR4n +wr4ht/n06QsBcGyIJrrkTrRGiHx9z9McNdI3hGZijBFYtPGfSsDFtipf8sOXIok3 +rQ3NGoRYb9siJKupaMNXhhr8awXX36DlWIoS6m0pnlD9F3ZC+iWMQMpAFTg/8+ZU +IfFBXZpXGw8WLiLNiBWcxVrgPDNm0IJFoOd52fyFRyDGukhJFUJXWyQK2bKvOZdk +jUWMNJ2sQTFMlIAnhgeWnalMU4GOgSumxGozZ7fYGQJdPdclIrMSJFdHghsaX5PM +lxA/k5PoRGfhx2p+REbdgvD3oN11Kep2Y6/PEC9n0wPU9VHk+R8Ab9jLekQjcfLB +bvoe/dzJcoT/thvBKpxgRCoEFI0ozYUnU9L288hPg3ctLR6k8e7ALMbPk13BFbJa +S1G9NpEsu94rDq7yehVOpGv0bCav2xtDIAgQW+ZRpRoipu5KSsUAzg== +=DNbu +-----END PGP PUBLIC KEY BLOCK----- +``` diff --git a/content/doc/administrate/tcp-redirections.md b/content/doc/administrate/tcp-redirections.md new file mode 100644 index 000000000..e5e9b0ab2 --- /dev/null +++ b/content/doc/administrate/tcp-redirections.md @@ -0,0 +1,107 @@ +--- +type: docs +title: TCP redirections +description: TCP redirections to port 4040 of your instance +tags: +- administrate +keywords: +- tcp +- cli-setup +- redirection +--- +{{< callout type="warning" >}} +TCP redirections are currently available free of charge as long as the feature is in BETA stage. +Once the feature leaves the BETA stage, it won't be free anymore. +{{< /callout >}} + +## What is a TCP redirection? + +Every application hosted Clever Cloud must listen on port 8080 and answer to HTTP traffic. +This is useful for both routing requests and monitoring purposes. + +However, some applications might additionally require binary protocol, with raw TCP interactions. +In that case, you can use a TCP redirection to route TCP traffic, through Clever Cloud reverse proxies, to your application. + +Every application can be configured to receive TCP traffic on the port 4040. +Clever Cloud then assigns a specific port to your application to expose it to TCP traffic. This port is chosen at random above 5000. + +Use this specific port to send and receive TCP traffic. + +{{< callout type="warning" >}} +The application must still be listening to the 8080 port, regardless of TCP configuration. +{{< /callout >}} + +## What is a namespace? + +Clever cloud manages a fleet of reverse proxies that fulfill different purposes, depending on their type and region. +A namespace is a group of reverse proxies. You may encounter: + +- `default`: the stable public group of your region +- `cleverapps`: the group behind all the `cleverapps.io` domains +- dedicated name: if you are a premium customer with dedicated reverse proxies + +Use `default` or dedicated namespace for applications with a custom domain name. +Use `cleverapps` for applications under the `cleverapps.io` domain. +If your application has both a custom domain name and a `cleverapps.io` one, you may activate TCP redirections on both of them. +Note that this generates two different ports, one for each domain. +You should use one or the other depending on the domain name you use in your request. + +To list the possible redirections available to your application, you can use the following: + +```bash +clever tcp-redirs list-namespaces +``` + +## Creating a new TCP redirection + +### With the console + +From your console, select your application. In the secondary menu, go to **TCP redirections**. +From there, you can create a TCP redirection for a specific namespace (see [namespaces doc](#what-is-a-namespace?)) + +The creation is instantaneous. Find the TCP redirection port on this page. + +![Redirection console](/images/TCP_redirection_console.png) + +### With the Clever CLI + +You can use the following command to create a TCP redirection from the CLI: + +```bash +clever tcp-redirs add --namespace default +``` + +Depending on your situation, you should replace `default` with the appropriate namespace. + +The port assigned to your application displays right after the TCP redirection creation. +You can then contact your application over TCP using `tcp://your-domain-name:the-port/`. + +## Managing redirections + +### Listing active redirections + +To visualize your application's redirections: + +- from your console, an active redirection has a green tick next to it +- from the Clever CLI, you can use: + +```bash +clever tcp-redirs +``` + +### Deleting redirections + +To delete a redirection on an application: + +- from your console, use the `delete` button next to the redirection +- from the Clever CLI, use: + +```bash +clever tcp-redirs remove (port) --namespace (namespace) +``` + +Example: if your redirection is on port **5500** and the **default** namespace, the command would be + +```bash +clever tcp-redirs remove 5500 --namespace default +``` \ No newline at end of file diff --git a/content/doc/administrate/zone-migration.md b/content/doc/administrate/zone-migration.md new file mode 100644 index 000000000..b2a67213a --- /dev/null +++ b/content/doc/administrate/zone-migration.md @@ -0,0 +1,119 @@ +--- +type: docs +title: Zone Migration +description: Migrate your applications and add-ons from one zone to another +tags: +- migration +- zone +- application +- addon +--- + +In this document, we will see how you can migrate your Clever Cloud services from one zone to another zone, for example from Paris to Montreal. +For most of the services, you will be able to migrate them as-is. For others, you will need to create them and do a manual migration. +Keep in mind that our support team remains available, should you have any questions regarding zone migration. + +## Application migration + +Most of the applications will migrate without issues. If one of your applications matches any criteria is in the list below, you will need extra steps +described in the following sub-sections. + +- Any application that uses a FSBucket add-on +- PHP applications + +In this case, please read the prerequisites below first and then follow the right sub-section. + +### Prerequisites + +Besides redeploying your application in your target zone, you have to keep a few things in mind: + +- Increased latency might be observed during DNS propagation (more below) +- You will need to update your DNS settings, so make sure you have access to your DNS registrar + +One of the first things you can do is to lower your DNS records TTL (time to live). In order to speed up the DNS propagation during the update of your domains DNS records. + +On your registrar's interface, find your application's domain. Usually, the DNS record will be `domain.tld IN CNAME domain..clever-cloud.com` with a certain TTL. +Edit that TTL to 60 seconds instead of the existing value, and wait for this change to propagate (wait as much time as the old TTL value). This change will allow a faster DNS propagation when +you have to update the `CNAME` record value to `domain..clever-cloud.com`, lowering the amount of time your users will experience an increased latency. + +{{< callout type="info" >}} +After the migration, you can set back your old TTL value. +{{< /callout >}} + +#### Increased latency + +Once your application has been redeployed to your target zone, your application's domain will still have its DNS pointing to the old zone. As a consequence, the +latency may increase for your users. For example, if you are migrating from Paris (PAR) to Montreal (MTL), your visitors will connect to our Paris infrastructure, which will +then redirect the traffic to our Montreal infrastructure, leading requests to take more time. + +You might also experience an increased latency between your application and other services (like a PostgreSQL add-on for example). If your application has switched to the Montreal zone +and your PostgreSQL add-on is still in Paris, your application will need extra time to query the database. + +#### DNS updates + +Once your application has been migrated to your target zone, you will find in the `Domain names` section the new `A` and `CNAME` DNS records to use for your application's domains. +If you were using `A` records, update the records (there might be more or fewer of them than what you had previously, this is normal). If you used a `CNAME` record, simply change the value. + +Once done, it will take as much time to propagate as the TTL defined for that record. If you followed the prerequisites above, it should take a few minutes tops. + +### Migration + +If your application doesn't match any criteria of the list in the `Application migration` section, then you can go to the `Information` pane of your application. Under the `Zone` label, chose your target zone. +Once selected, you can save your changes using the `Save` button at the bottom of the page. + +After saving, you can now redeploy your application in the `Overview`, it will redeploy on the new zone. + +### Applications using an FSBucket + +FSBuckets can only be mounted by applications on the same zone. This means that you cannot use an FSBucket add-on hosted in Paris, if your application is in Montreal. + +To migrate FSBuckets, see the [section below](#fsbucket). + +### PHP Applications + +Because of technical reasons, a PHP application can not be migrated to another zone. In this case, you will have to re-create the application. +When domains are switched from the old application to the new one, a small downtime may occur. 404 or 503 errors might happen for a few seconds. + +First, create a new PHP application on your target zone. +Then, you can easily copy / paste the environment variable from the old application to the new one using the `Expert mode` of our environment variables interface. +Don't forget to link all services that were linked to your old application. Linking multiple times the same service to different application doesn't cause any issue. +Make sure the Scalability section of your application is the same as the old one, as well as the various options you can find in the `Information pane` (HTTPS redirection, build cache, …). + +Once everything is setup again, we can push the code. If you are using Git, you can find the new Git URL in the `Information` panel. +If you are using FTP, please read the [FSBucket migration section](#fsbucket). + +Your new application should now be deployed. You can update the domain names: for each domain of your old application, delete it and add it to the new application. + +You can use the CLI to do it and minimize the downtime: + +```shell +clever -a domain rm ; clever -a domain add +``` + +You can now update your DNS as described in the [DNS updates](#dns-updates) section. + +## Add-on migration + +Add-ons can be migrated from one zone to another. For some of them, our support team can help you do it. + +### PostgreSQL, MySQL, MongoDB, Redis + +You can migrate these add-ons using the [Migration Tool](/developers/doc/administrate/database-migration). + +Once your migration is over, the services connecting to the add-on might be impacted by an increased latency due to DNS updates. The domain of your add-on will have its DNS records +changed but it will take up to 1 hour for them to propagate. This means that during that time, your services might still connect to the old zone, which will then redirect to the target zone +where your database has been migrated. + +### Jenkins, Elasticsearch, Cellar, Pulsar + +These add-ons can not be automatically migrated across zones. Please reach out to our support team so we can assist you further for this migration. + +### FSBucket + +FSBuckets can not be migrated across zones either. You will have to create a new FSBucket in the target zone and transfer its content from the old to the new one. + +To do so, you can use the [LFTP](https://lftp.yar.ru/) or [Rclone](https://rclone.org/) tools. Or you can ask our support team and we will be able to do it for you. + +{{< callout type="warning" >}} +In case of a FSBucket add-on (and not a PHP+FTP add-on), remember to link it to your application once it has been migrated to the new zone. +{{< /callout >}} diff --git a/content/doc/applications/_index.md b/content/doc/applications/_index.md new file mode 100644 index 000000000..8ff59ea35 --- /dev/null +++ b/content/doc/applications/_index.md @@ -0,0 +1,75 @@ +--- +weight: 2 +type: "docs" +title: Applications +description: Deploy an application on Clever Cloud +tags: +- applications +keywords: +- deploy + +aliases: +- /applications +- /doc/apps +- /doc/deploy +- /doc/deploy/application +- /doc/deploy/application/ruby/by-framework +- /doc/getting-started/by-language +- /doc/java/select-java-version +comments: false +--- + +## Choose your Stack + +Find here specific instructions related to your application's language. + +{{< cards >}} + {{< card link="/developers/doc/applications/dotnet" title=".Net" icon="dotnet" >}} + {{< card link="/developers/doc/applications/docker" title="Docker" icon="docker" >}} + {{< card link="/developers/doc/applications/elixir" title="Elixir" icon="elixir" >}} + {{< card link="/developers/doc/applications/frankenphp" title="Franken PHP" icon="frankenphp" >}} + {{< card link="/developers/doc/applications/golang" title="Go" icon="go" >}} + {{< card link="/developers/doc/applications/haskell" title="Haskell" icon="haskell">}} + {{< card link="/developers/doc/applications/java" title="Java (Gradle, Jar, Maven, War/Ear)" icon="java" >}} + {{< card link="/developers/doc/applications/linux" title="Linux" icon="linux" >}} + {{< card link="/developers/doc/applications/meteor" title="Meteor.js" icon="meteor" >}} + {{< card link="/developers/doc/applications/nodejs" title="Node.js & Bun" icon="node" >}} + {{< card link="/developers/doc/applications/php" title="PHP with Apache" icon="php" >}} + {{< card link="/developers/doc/applications/python" title="Python with uv support" icon="python" >}} + {{< card link="/developers/doc/applications/ruby" title="Ruby" icon="ruby" >}} + {{< card link="/developers/doc/applications/rust" title="Rust" icon="rust" >}} + {{< card link="/developers/doc/applications/scala" title="Scala" icon="scala" >}} + {{< card link="/developers/doc/applications/static" title="Static" icon="static" >}} + {{< card link="/developers/doc/applications/static-apache" title="Static with Apache" icon="feather" >}} + {{< card link="/developers/doc/applications/v" title="V (Vlang)" icon="v" >}} +{{< /cards >}} + +## How To Deploy X if It Isn't Natively Supported + +If your favorite runtime is not available, you can deploy it on Clever Cloud by Dockerizing it and make it run in a Docker instance. +You will probably find a basic Docker file for your technology on the Docker hub. + +Refer to the [Docker](docker) section of this documentation to know how to deploy your Dockerized application. + +If you are out of options, contact our support team and we'll come up with a solution with you. + +## Environment Variables + +You can control deployments and set your application configuration with environment variables: +{{< cards >}} + {{< card link="/developers/doc/reference/reference-environment-variables/#set-by-the-deployment-process" title="Common to all applications" subtitle="Set by the deployment process." icon="server-stack" >}} + {{< card link="/developers/doc/reference/reference-environment-variables/#variables-you-can-define" title="Define" subtitle="Variables you can define." icon="pencil-square" >}} + {{< card link="/developers/doc/reference/reference-environment-variables/#control-build-and-dependencies-cache" title="Cache" subtitle="Control the build and deployment cache." icon="arrow-up-on-square-stack" >}} + {{< card link="/developers/doc/reference/reference-environment-variables/#control-the-deployments-behavior" title="Run" subtitle="Control the deployment behavior." icon="play-circle" >}} + {{< card link="/developers/doc/reference/reference-environment-variables/#deployment-hooks" title="Hooks" subtitle="Define commands to run between various steps of the deployment." icon="eye-dropper" >}} + {{< card link="/developers/doc/reference/reference-environment-variables" title="How to" subtitle="How to to configure your application with environment variables." icon="book-open" >}} +{{< /cards >}} + +### Common to All Applications + +- Applications on Clever Cloud listen on **port 8080**. Be sure you application is able to listen on port 8080 before deploying. +- Deployments on Clever Cloud are immutable: if your app restarts, last pushed commit will be deployed with your current environment variables. + +{{< callout type="info" >}} + Learn more about [immutablity and application management](/developers/doc/administrate/apps-management). +{{< /callout >}} diff --git a/content/doc/applications/docker.md b/content/doc/applications/docker.md new file mode 100644 index 000000000..4a684788c --- /dev/null +++ b/content/doc/applications/docker.md @@ -0,0 +1,148 @@ +--- +type: docs +title: Docker +description: Docker is an easy, lightweight virtualized environment for portable applications +keywords: +- docker +tags: +- deploy +aliases: +- /applications/docker +- /developers/doc/applications/docker +- /doc/deploy/application/docker +- /doc/deploy/application/docker/docker +- /doc/docker +- /doc/docker/docker +- /doc/getting-started/by-language/docker +- /doc/partials/language-specific-deploy/docker +- /docker +- /docker-hosting +--- +{{< hextra/hero-subtitle style="margin:.3rem 0 2rem 0">}} + Clever Cloud offers support for Docker containers. These are deployed inside virtual machines to guarantee a secure level of isolation. +{{< /hextra/hero-subtitle >}} + +## Overview + +Docker containers can encapsulate any payload, and will run consistently on and between virtually any server. The same container that a developer builds and tests on a laptop will run at scale, in production, on VMs, bare-metal servers, public instances, or combinations of the above. + +Clever Cloud allows you to deploy any application running inside a Docker container. This page will explain how to set up your application to run it on our service. + +{{< callout type="info" >}} + Clever Cloud supports many languages, but some users have specific application needs. With Docker, they can create custom stacks without relying on Clever Cloud's specific support. +{{< /callout >}} + +{{< callout type="warning" >}} +[FS Buckets](/developers/doc/best-practices/cloud-storage/#what-is-fs-bucket) access, Dockerfile validation, and Docker Compose functionalities are not supported. +{{< /callout >}} + +### How it works + +When you create a Docker application on Clever Cloud, the deployment process involves the following steps: + +1. **Install/Login:** + - The system checks for a Dockerfile and an entrypoint. + - It logs into the docker registry that you configured in the Dockerfile, if any, to find the necessary image (**note:** the name of the Docker registry may vary depending on the provider. It's called "container registry" in GitHub, for instance) +2. **Build:** + - The application pulls the specified image and execute commands you specified in Dockerfile. + - **Note:** This step focuses on executing commands in your Dockerfile and doesn't require build instructions if you are using a pre-compiled image. +3. **Run:** + - The application starts in a Docker container and exposes the service on port 8080 by default. + - If you need to expose your application on a different port, you can specify this using the environment variable `CC_DOCKER_EXPOSED_HTTP_PORT`. + + {{% content "set-env-vars" %}} + +## Configure your Docker application + +### Mandatory configuration + +Be sure that you: + +* push on the **master branch**. +* have and commit a file named **Dockerfile** or use the **CC_DOCKERFILE** [environment variable](/developers/doc/reference/reference-environment-variables#docker) if your Dockerfile has a different name, [Here is what it will look like](https://docs.docker.com/develop/develop-images/dockerfile_best-practices "Dockerfile"). +* run the application with `CMD` or `ENTRYPOINT` in your Dockerfile. +* listen on HTTP **port 8080** by default (you can set your own port using `CC_DOCKER_EXPOSED_HTTP_PORT=` environment variable). + +### Dockerfile contents + +You can virtually put everything you want in your Dockerfile. The only mandatory (for us) instruction to put in it is: + +```bash +CMD +``` + +**command to run**: this is the command that starts your application. Your application **must** listen on port 8080. It can be easier for you to put a script in your docker image and call it with the CMD instruction. + +### Docker Buildx + +We still use `docker build` command for legacy reasons, but you can use `docker buildx` instead, setting `CC_DOCKER_BUILDX` to `true`. + +### Memory usage during building + +If the building step of your app crashes because it uses more memory that it's available, you'll have to split the building and running steps and enable [Dedicated build instance](/developers/doc/administrate/apps-management#edit-application-configuration) + +```bash +# The base image +FROM outlinewiki/outline:version-0.44.0 + +# Run the memory intensive build on an instance with 4 GB of memory (M) +RUN yarn install && yarn build + +# Start the app on a smaller instance (nano) +CMD yarn start +``` + +### Login to registry + +As Docker Hub limits the number of image pulls and actions without authentication, use you own account to get higher limits. You can also use a private registry where you store your images. This feature launch `docker login` command before the build phase. + +* `CC_DOCKER_LOGIN_USERNAME`: the username to use to login +* `CC_DOCKER_LOGIN_PASSWORD`: the password of your username +* `CC_DOCKER_LOGIN_SERVER` (optional): the server of your private registry, default is Docker Hub + +### TCP support + +Clever Cloud enables you to use TCP over Docker applications using the environment variable `CC_DOCKER_EXPOSED_TCP_PORT=`. + +* [Learn more about TCP redirections](/developers/doc/administrate/tcp-redirections) + +### Docker socket access + +Some containers require access to the docker socket, to spawn sibling containers for instance. + +{{< callout type="warning" >}} +Giving access to the docker socket breaks all isolation provided by docker. **DO NOT** give socket access to untrusted code. +{{< /callout >}} + +You can make the docker socket available from inside the container by adding the `CC_MOUNT_DOCKER_SOCKET=true` environment variable. In that case, docker is started in the namespaced mode, and in bridge network mode. + +### Enable IPv6 networking + +You can activate the support of IPv6 with a IPv6 subnet in the docker daemon by adding the `CC_DOCKER_FIXED-CIDR-V6=` environment variable. + +### Build-time variables + +You can use the [ARG](https://docs.docker.com/engine/reference/builder/#arg) instruction to define build-time environment variables. + +Every environment variable defined for your application will be passed as a build environment variable using the `--build-arg=` parameter during the `docker build` phase. + +### Sample dockerized applications + +We provide a few examples of dockerized applications on Clever Cloud. + +* [Elixir App](https://github.com/CleverCloud/demo-docker-elixir/blob/master/Dockerfile) +* [Seaside / Smalltalk App](https://github.com/CleverCloud/demo-seaside) +* [Rust App](https://github.com/CleverCloud/demo-rust) + +You might need to use the `CC_DOCKERFILE = ` variable. + + +{{% content "env-injection" %}} + +{{% content "deploy-git" %}} + +{{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} \ No newline at end of file diff --git a/content/doc/applications/dotnet.md b/content/doc/applications/dotnet.md new file mode 100644 index 000000000..88616f320 --- /dev/null +++ b/content/doc/applications/dotnet.md @@ -0,0 +1,161 @@ +--- +type: docs +title: .NET +description: .NET. Free, Cross-platform, Open source. A developer platform for building all your apps +tags: +- deploy +keywords: +- .NET +- csproj +- fsproj +- vbproj +aliases: +- /applications/dotnet +- /deploy/application/dotnet/dotnet +- /doc/deploy/application/dotnet +- /doc/deploy/application/dotnet/dotnet +- /doc/develop/env-variables/doc/applications/dotnet +- /doc/partials/language-specific-deploy/dotnet +- /dotnet +--- + +## Overview + +Clever Cloud allows you to deploy .NET web applications. This page explains you how to set up your application to run it with the .NET runtime. + +You don't need to change a lot in your application, the *requirements* section explains how to configure your apps with some mandatory files to add, and properties to setup. + +{{< callout type="warning">}} + If you encounter an issue, please contact the support. +{{< /callout >}} + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +## Configure your Dotnet application + +### .NET version + +The versions used on Clever Cloud are the following: + +{{< runtimes_versions dotnet >}} + +You can change the default version by setting the `CC_DOTNET_VERSION` environment variable to `6.0`. Clever Cloud doesn't support non-LTS and older versions. + +### Requirements + +Be sure that: + +* You have pushed in **master** branch. +* You listen on port **8080**, by default each .NET application is created with the `ASPNETCORE_URLS="http://0.0.0.0:8080"` environment variable. +* You have committed the different files of your project and the corresponding project file (`.csproj`, `.fsproj` or `.vbproj`). + +Take an example with the [cc-dotnet-demo](https://github.com/CleverCloud/cc-dotnet-demo). + +If needed, you could add the `APP_FOLDER=` environment variable to define the application folder inside the Git repository (where `.*proj` is stored). + +During deployment, the runtime automatically detects the `cc-dotnet-demo.csproj` file and the target framework `net8.0`. Then, it publishes the .NET project: + +```bash +dotnet publish --framework net8.0 --configuration Release +``` + +No additional configuration is required (unless multiple project files or target frameworks are present, see the documentation below). + +### Multiple project files in the repository + +If multiple project files are present in your repository, you can specify the file to use (without the .*proj extension) with the `CC_DOTNET_PROJ` environment variable. + +```bash +CC_DOTNET_PROJ=cc-dotnet-demo +``` + +### Multiple binary targets + +If your project file defines multiple targets, like : + +```xml{linenos=table} + + + + net6.0;net8.0 + + … +``` + +You must specify the one you want to run, with the `CC_DOTNET_TFM` environment variable. + +If `CC_DOTNET_TFM` is specified, then the executable produced by this target is used to start the application. + +```bash +CC_DOTNET_TFM=net6.0 +``` + +### Dependencies + +Make sure to list all your dependencies in your project file. For example: + +```xml{linenos=table} + … + + + + + + +``` + +Compiled dependencies are cached by default to speed up deployments. You can turn off dependencies caching completely by removing the `CC_CACHE_DEPENDENCIES` environment variable. + +If you want to rebuild your application from scratch, you can select "rebuild and restart" from the console or launch `clever restart --without-cache` from [CLI](https://github.com/CleverCloud/clever-tools) + +### Configure profile + +The default profile is `Release` but you can use the `CC_DOTNET_PROFILE` environment variable to change this configuration. + +```bash +CC_DOTNET_PROFILE=Debug +``` + +### Custom run command + +If you need to run a custom command (or just pass options to the program), you can specify it through the `CC_RUN_COMMAND` environment variable. + +For instance, you can have `CC_RUN_COMMAND=./bin/Release/net6.0/exherbo-x64/myapp `. + +### Private dependencies + +Clever Cloud supports private dependency management with NuGet package manager. + +Add the configuration file `nuget.config` : + +```xml + + + + + + + + + + + + + +``` + +Set environment variables in the console according to your own information : `PACKAGE_REGISTRY_URI`, `PACKAGE_REGISTRY_USERNAME` and `PACKAGE_REGISTRY_PASSWORD` + +{{% content "env-injection" %}} + +To access environment variables from your code, you can use `System.Environment.GetEnvironmentVariable("MY_VARIABLE")"`. + +{{% content "deploy-git" %}} + +{{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/elixir.md b/content/doc/applications/elixir.md new file mode 100644 index 000000000..503c30ea9 --- /dev/null +++ b/content/doc/applications/elixir.md @@ -0,0 +1,76 @@ +--- +type: docs +title: Elixir +description: Elixir is a functional, concurrent, general-purpose programming language that runs on the Erlang virtual machine… +tags: +- deploy +keywords: +- elixir +- phoenix +- erlang +aliases: +- /applications/elixir +- /doc/deploy/application/elixir +- /doc/deploy/application/elixir/elixir +- /doc/elixir +- /doc/getting-started/by-language/elixir/ +- /doc/partials/language-specific-deploy/elixir +- /elixir +--- + +## Overview + +Clever Cloud supports Elixir based applications. + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +## Configure your Elixir application + +### Mandatory configuration + +Get your Elixir version in your console with `$ elixir -v` and set the environment variable `CC_ELIXIR_VERSION` to its value. Available versions as of today are the following: + +{{< runtimes_versions elixir >}} + +#### Compatibility between Elixir and Erlang/OTP + +- Each version of Elixir uses the most recent compatible version of Erlang, based on the compatibility table provided in the [official Elixir documentation](https://hexdocs.pm/elixir/compatibility-and-deprecations.html#between-elixir-and-erlang-otp). + +#### If you deploy a Phoenix application + +- Edit the file `config/prod.secret.exs` to replace `System.get_env("DATABASE_URL")` with `System.get_env("POSTGRESQL_ADDON_URI")`. +- Generate a secret token with `$ mix phx.gen.secret`. +- set environment variable **SECRET_KEY_BASE** to the value obtained with `$ mix phx.gen.secret` previously +- set environment variable **CC_PHOENIX_RUN_ECTO_MIGRATE** to `true` if you need to trigger the command `$ mix ecto.migrate` + +## Build, deployment phases and custom configuration + +Once you push your code to Clever Cloud, the following commands are run: + +```bash +mix deps.get +mix deps.compile +npm install +``` + +These commands will compile your dependencies at the root of your project folder. +If you want to use another folder for `npm install`, specify it via the environment variable **CC_PHOENIX_ASSETS_DIR**. +To change the folder for the entire build / run process, you should use **APP_FOLDER** environment variable. + +Then `mix compile` is run. If you want to override this behavior, you can set the environment variable **CC_MIX_BUILD_GOAL** to the value you desire. + +At this point, there is the command `npm run deploy`. + +Then `mix phx.digest` is run. You can override this one with the variable **CC_PHOENIX_DIGEST_GOAL**. + +Finally, `mix phx.server` is invoked, and as always, you can override this behavior, either with **CC_RUN_COMMAND** where you have to specify the full command, or **CC_PHOENIX_SERVER_GOAL** where it will be a mix task by default. + +Note: If you need to specify the timezone of your application, you can do it with the variable **TZ** set to the usual timezone format, for instance `Europe/Paris`. + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} diff --git a/content/doc/applications/frankenphp.md b/content/doc/applications/frankenphp.md new file mode 100644 index 000000000..dc112a83f --- /dev/null +++ b/content/doc/applications/frankenphp.md @@ -0,0 +1,99 @@ +--- +type: docs +linkTitle: FrankenPHP +title: FrankenPHP application runtime +description: Deploy your applications with FrankenPHP, the modern PHP server based on Caddy, written in Go +type: docs +--- + +## Overview + +[FrankenPHP](https://frankenphp.dev) is a fast and modern server for PHP developed by [Kevin Dunglas](https://github.com/dunglas) built on top of the [Caddy web server](https://caddyserver.com/docs/). It's a seamless drop-in replacement for PHP-FPM or Apache with `mod_php`, designed to enhance your PHP applications with advanced capabilities. + +It comes with many extensions and features such as early hints (HTTP 103), real-time capabilities with its built-in Mercure hub. FrankenPHP can also make your Laravel and Symfony projects faster than ever through their official integrations with the [worker mode](#worker-mode). Deploying PHP applications with FrankenPHP on Clever Cloud is straightforward and requires no complex configuration, nor Docker container. + +> [!NOTE] FrankenPHP is a new runtime +> Help us to improve it by reporting any issue or suggestion on the [Clever Cloud Community](https://github.com/CleverCloud/Community/discussions/categories/frankenphp) + +## Create your FrankenPHP application + +To create a new FrankenPHP application, use the [Clever Cloud Console](https://console.clever-cloud.com) or [Clever Tools](https://github.com/CleverCloud/clever-tools): + +```bash +clever create --type frankenphp +``` +* [Learn more about Clever Tools](/developers/doc/cli/) +* [Learn more about Clever Cloud application deployment](/developers/doc/quickstart/#create-an-application-step-by-step) + +> [!NOTE] FrankenPHP applications can't be deployed on a pico instance, XS is the default instance type + +## Configure your FrankenPHP application + +### Mandatory needs + +FrankenPHP runtime only requires a working web application, with an `index.php` or `index.html` file. If you need to serve files from a specific directory, set the `CC_WEBROOT` environment variable, relative to the root of your project (default: `/`). + +* [Learn more about environment variables on Clever Cloud](/developers/doc/reference/reference-environment-variables/) + +### FrankenPHP version and tools + +FrankenPHP currently deployed version on Clever Cloud is `1.8.0` based on PHP `8.4.10` and Caddy server `2.10.0`. Virtual machine image includes multiple tools from the PHP ecosystem such as Composer or Symfony CLI. + +- [FrankenPHP PHP info](https://frankenphpinfo.cleverapps.io/) + +### Composer native support + +If a `composer.json` file is detected at the root of your project, it will be used to install dependencies during building phase with `--no-interaction --no-progress --no-scripts --no-dev` flags. To use your own, set the `CC_PHP_COMPOSER_FLAGS`environment variable. + +To install development dependencies, set the `CC_PHP_DEV_DEPENDENCIES` environment variable to `install`. + +> [!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. + +## Custom PHP configuration + +To load your own PHP configuration directives, put a `php.ini` file at the root of your project. FrankenPHP will automatically use it. + +## FrankenPHP and Materia KV + +Materia KV is Clever Cloud's distributed serverless key-value store based on FoundationDB, compatible with existing ecosystems such as Redis®, with TTL for sessions support and JSON commands. + +To manage Materia KV data with FrankenPHP, use the included `redis` extension in your PHP code and configure it with your add-on URL, port and token as password. For now, you need to use the `tcp` mode and `6378` port. + +- [Learn more about Materia KV](/developers/doc/addons/materia-kv) +- [Materia KV and FrankenPHP demo](https://github.com/CleverCloud/frankenphp-kv-json-example) + +### Worker mode + +With FrankenPHP worker mode, a script of your project is kept in memory to handle incoming requests in a few milliseconds. Define the path to this script, relative to the root of your project, with the `CC_FRANKENPHP_WORKER` environment variable (e.g. `/worker/script.php`). It's supported by design by Laravel Octane and Symfony Runtime projects. + +* [Learn more about FrankenPHP worker mode](https://frankenphp.dev/docs/worker/#standalone-binary) +* [Learn more about Laravel Octane](https://laravel.com/docs/master/octane#frankenphp) +* [Learn more about Symfony Runtime](https://symfony.com/doc/current/components/runtime.html) + +## Configurable port + +By default, FrankenPHP listens on port `8080`. If you want to change it, set the `CC_FRANKENPHP_PORT` environment variable to your desired port. This is useful if you want to run a service in front of FrankenPHP, such as [Redirection.io](/developers/doc/reference/reference-environment-variables/#use-redirectionio-as-a-proxy) for example. + +## Custom FrankenPHP run command + +Use your own command to run your FrankenPHP application to define flags such as `--debug`, `--mercure` or `--no-compress`. To do so, set the `CC_RUN_COMMAND` environment variable, starting with `frankenphp php-server --listen 0.0.0.0:8080`. + +You can also use this to load [a custom Caddyfile](https://frankenphp.dev/docs/config/#caddyfile-config), starting `CC_RUN_COMMAND` with `frankenphp run --config /path/to/Caddyfile`. + +## Use FrankenPHP to execute PHP scripts as Clever Tasks + +FrankenPHP can be used to execute PHP scripts. On Clever Cloud, to run such workloads as Clever Tasks, configure an application as Tasks from the `Information` panel in [the Console](https://console.clever-cloud.com) or with [Clever Tools](/developers/doc/cli/applications/#tasks): + +```bash +clever create --type frankenphp --task "frankenphp php-cli path/to/task.php" +clever deploy # or clever restart if there is no code change +``` + +- [Learn more about Clever Tasks](/developers/doc/develop/tasks/) + +## Included extensions + +FrankenPHP on Clever Cloud comes with a set included PHP extensions: `amqp`,`apcu`,`ast`,`bcmath`,`brotli`,`bz2`,`calendar`,`ctype`,`curl`,`dba`,`dom`,`exif`,`fileinfo`,`filter`,`ftp`,`gd`,`gmp`,`gettext`,`iconv`,`igbinary`,`imagick`,`intl`,`ldap`,`lz4`,`mbregex`,`mbstring`,`mysqli`,`mysqlnd`,`opcache`,`openssl`,`parallel`,`pcntl`,`pdo`,`pdo_mysql`,`pdo_pgsql`,`pdo_sqlite`,`pgsql`,`phar`,`posix`,`protobuf`,`readline`,`redis`,`session`,`shmop`,`simplexml`,`soap`,`sockets`,`sodium`,`sqlite3`,`ssh2`,`sysvmsg`,`sysvsem`,`sysvshm`,`tidy`,`tokenizer`,`xlswriter`,`xml`,`xmlreader`,`xmlwriter`,`xz`,`zip`,`zlib`,`yaml`,`zstd` + +{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/golang.md b/content/doc/applications/golang.md new file mode 100644 index 000000000..589bfb6b9 --- /dev/null +++ b/content/doc/applications/golang.md @@ -0,0 +1,155 @@ +--- +type: docs +title: Go +description: Go, otherwise known as Golang, is an open source, compiled, garbage-collected, concurrent system programming language +tags: +- deploy +keywords: +- go +- golang +aliases: +- /applications/golang +- /deploy/application/golang/go +- /doc/deploy/application/golang +- /doc/deploy/application/golang/go +- /doc/getting-started/by-language/go +- /doc/go +- /doc/go/go +- /doc/golang +- /doc/partials/language-specific-deploy/go +- /go/go +- /go +- /golang +--- + +## Overview + +Clever Cloud allows you to deploy any Go application. This page explains how to set up your project to run it on our service. You won't need to change a lot, the *requirements* will help you configure your applications with some mandatory files to add, and properties to set up. + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +## Configure your Go application + +### Mandatory needs + +By default, we consider that your repository contains a single application. Be sure that: +* It listens to the wild network `0.0.0.0`, not only `localhost` or `127.0.0.1` +* It listens on port `8080` +* You follow our build/run instructions + +In most cases you won't need to change anything to your application, except host/port and some configuration variables. + +### Complementary runtime + +If you need a runtime environment such as [Node.js](/developers/doc/applications/nodejs) or tools to build a frontend for example, some are available in our Go instances. You can use them through scripts launched by [deployments hooks](/developers/doc/develop/build-hooks) and [Environment variables](/developers/doc/reference/reference-environment-variables) sometimes allow you to configure them. So if you need a specific version of Node.js, set `CC_NODE_VERSION` (it could be `node` (latest), `lts/*`, `20` or `21.5.0`). + +### Modern Go project structure + +There are multiple ways to build/run a Go application, and this has evolved over the years. In its modern form a Go project can be a: +- `Package`: one or more `.go` files you can `build` or `run`. `main` package and `main()` function are the default entry point +- `Module`: one or more packages you can `install`, defined in a `go.mod` file (`go.sum` for checksums) +- `Workspace`: one or more modules seamlessly combined, defined in a `go.work` file + +Install any module locally or from a remote repository by passing its URL to the `install` command. A `Makefile` is sometimes used to define how to build, run and/or clean a Go project. The lightest form of a Go project is a `main.go` file to build. The `src/` folder was often used for source code, but using the `cmd/` folder instead is now a common practice. + +If you want to limit from where a package can be imported, [place it](https://docs.google.com/document/d/1e8kOo3r51b2BWtTs_1uADIA5djfXhPT36s6eHVRIvaU/edit) in a folder named `ìnternal/`. Access to functions in `.go` files is defined depending [on their name](https://go.dev/tour/basics/3): if it starts with a capital letter it's a public function, if not it's a private function. + +For a complete project, a common files/folders organisation can be: +{{< filetree/container >}} + {{< filetree/folder name="application-root/" >}} + {{< filetree/file name="go.work" >}} + {{< filetree/file name="Makefile" >}} + {{< filetree/folder name="cmd/" >}} + {{< filetree/file name="main.go" >}} + {{< filetree/file name="other-file.go" >}} + {{< filetree/file name="other-package.go" >}} + {{< filetree/file name="…" >}} + {{< /filetree/folder >}} + {{< filetree/folder name="module/" >}} + {{< filetree/file name="go.mod" >}} + {{< filetree/file name="go.sum" >}} + {{< filetree/file name="main.go" >}} + {{< filetree/file name="other-module-file.go" >}} + {{< filetree/folder name="internal/" >}} + {{< filetree/folder name="internal-package/" >}} + {{< filetree/file name="internal-package-file.go" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + +### Go build and deploy on Clever Cloud + +In such a situation, our strategy is to let the user choose how to build/run its application and make the deployment easy anyway. At first, we used the `goget` method, which is now deprecated. Thus, you can now use `gobuild` (for packages), `gomod` (for modules) or `makefile`. The latter will allow you to define custom build steps and a `main` executable to start the application. + +{{< callout type="info" >}} + If the required Go version declared in the `go.mod` is superior to the version built in the instance, it will be automatically updated. +{{< /callout >}} + +### Environment variables + +If you don't want to add a file to your project, you can set one of these environment variables: + +| Name | Description | +| :------- | :---- | +| `CC_GO_BUILD_TOOL` | Available values: `gomod`, `gobuild`, `makefile`. Build and install your application. `goget` still exists but is deprecated. | +| `CC_GO_BINARY` | Mandatory for a `Makefile` build, path to the built binary, used to launch your application. | +| `CC_GO_PKG` | Tell the `CC_GO_BUILD_TOOL` which file contains the `main()` function, default `main.go`. | +| `CC_GO_RUNDIR` | Run the application from the specified path, relative to `$GOPATH/src/`, now deprecated. | + +{{< callout type="info" >}} + The default `GO_PATH` is `${HOME}/go_home`. + The command executed to launch the application is `go install $CC_GO_PKG`. \ + Your project may include vendored dependencies (in the `vendor/` folder). +{{< /callout >}} + +#### gobuild + +To build a Go package. `CC_GO_PKG` can be set to define the main file of your application (default `main.go`). + +#### gomod + +To build a Go module, be sure that the `go.mod` file is in your git tree and at the root of your application. Your project's entry point should be in the same folder as the `go.mod` file and be named `main.go`. If it isn't, you have to set `CC_GO_PKG=path/to/entrypoint.go`. + +#### makefile + +To build a Go project with a `Makefile`. You have to set `CC_GO_BINARY` with the path to the built binary, used to launch your application. If a `Makefile` is present with a `CC_GO_BINARY` set and no `go.mod` file at the root of your project, the `makefile` method will automatically be used. + +An example of a `Makefile`, to use with `CC_GO_BINARY=bin/myApp`: + +```Makefile {filename="Makefile"} +BINARY=bin/myApp + +build: +# To install a specific Go version, you can add: +# go install golang.org/dl/gox.xx.x@latest +# ${HOME}/go_home/bin/gox.xx.x download +# Then use `${HOME}/go_home/bin/gox.xx.x` instead of `go` + echo "Build the application as ./${BINARY}" + go build -o ${BINARY} main.go +``` + +- [A more complex project using a Go Workspace and a Makefile](https://github.com/CleverCloud/go-workspaces) + +{{< callout type="warning" >}} + Using `clevercloud/go.json` to define Makefile and binary paths is a deprecated method and should no longer be used. +{{< /callout >}} + + {{% content "env-injection" %}} + +To access environment variables from your code, just get them from the environment with `PATH`: `os.Getenv("MY_VARIABLE")`. + +{{% content "deploy-git" %}} + +{{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} + +## See also + +* [Deploy EchoIP guide](/developers/guides/go-echoip/) diff --git a/content/doc/applications/haskell.md b/content/doc/applications/haskell.md new file mode 100644 index 000000000..986253e17 --- /dev/null +++ b/content/doc/applications/haskell.md @@ -0,0 +1,130 @@ +--- +type: docs +title: Haskell +description: Haskell is love, haskell is life +tags: +- deploy +keywords: +- haskell +- stack +aliases: +- /doc/deploy/application/haskell +- /doc/deploy/application/haskell/haskell +- /doc/getting-started/by-language/haskell +- /doc/haskell/ +- /doc/haskell/haskell +- /doc/partials/language-specific-deploy/haskell +- /haskell +--- + +## Overview + +Haskell is a purely functional language, especially suited for robust web applications. + +There are many ways to write web applications in Haskell, from raw [WAI](https://hackage.haskell.org/package/wai) to full-stack frameworks like [Yesod](https://www.yesodweb.com/), simple libraries like [scotty](https://hackage.haskell.org/package/scotty) or type-safe solutions like [servant](https://haskell-servant.GitHub.io/). + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +## Configure your Haskell application + +### Mandatory configuration + +Be sure that: + +* you have pushed in **master branch** +* you listen on **port 8080** +* you have one and only one binary target in your [`.cabal` file](#dependencies) +* your project has a `stack.yaml` file + +The steps ran in order are: + +* `stack setup` +* `stack install --only-dependencies` +* `stack install` +* `.//my-exe` (or the contents of `CC_RUN_COMMAND`) + +The executable built by `stack build` (or the command you specify) must start a web server listening on `0.0.0.0:8080`. + +For instance, a minimal [scotty](https://hackage.haskell.org/package/scotty) application can look like this: + +```haskell {linenos=table} +{-# LANGUAGE OverloadedStrings #-} + +import Web.Scotty + +main = scotty 8080 $ do + get "/" $ do + html $ "Hello world" +``` + +### Dependencies + +Make sure to list all your dependencies in your `.cabal` file. + +For the example above, you need: + +```haskell {linenos=table} +executable myfirstapp + main-is: Main.hs + build-depends: base + , scotty +``` + +### Cached dependencies + +You can enable dependencies caching by adding the `CC_CACHE_DEPENDENCIES=true`. +It is enabled by default only for rust and haskell applications. + +To disable dependencies caching completely, you can remove the `CC_CACHE_DEPENDENCIES` environment variable or by setting it to `false`. +To fully remove cached dependencies, you have to rebuild your application from scratch. + +You can select **rebuild and restart** from the console or launch `clever restart --without-cache` with the Clever Tools CLI. + +### Custom run command + +If you need to run a custom command (or just pass options to the binary built by stack), you can specify it through the `CC_RUN_COMMAND` environment variable. + +For instance, for a [hakyll](https://jaspervdj.be/hakyll/) website, you can define: + +```bash +CC_RUN_COMMAND="~./local/bin/site server --host 0.0.0.0 --port 8080" +``` + +To access environment variables from your code, just get them from the environment with `getEnv :: String -> IO String` in `System.Environment`. + +If some environment variables are critical to your application, here is an approach you can use: + +```haskell {linenos=table} +{-# LANGUAGE OverloadedStrings #-} +module Main where + +import Data.Text.Lazy (pack) +import System.Environment (getEnv) +import Web.Scotty (get, html, scotty) + +envVar = getEnv "MY_VAR" + +main = do + myVar <- envVar + scotty 8080 $ do + get "/" $ do + html . pack $ "Hello world " ++ myVar +``` + +This loads the environment variable in your `main` function and tests it. This way, the application will refuse to start with an helpful error message if `MY_VAR` is not defined. + +### Specify Stack package target + +You may have several packages in your application which can be time consuming when building them, if you don't want to build every packages you can target a package by using the `CC_HASKELL_STACK_TARGET` [environnement variable](#setting-up-environment-variables-on-clever-cloud). + +```bash +CC_HASKELL_STACK_TARGET="mypackage" +``` + +{{% content "deploy-git" %}} + +{{% content "link-addon" %}} + +{{% content "more-config" %}} diff --git a/content/doc/applications/java/_index.md b/content/doc/applications/java/_index.md new file mode 100644 index 000000000..3a0c5dfad --- /dev/null +++ b/content/doc/applications/java/_index.md @@ -0,0 +1,47 @@ +--- +type: docs +title: Java +description: Deploy your Java applications on Clever Cloud with Gradle, Maven, or as a JAR/WAR/EAR file +tags: +- deploy +keywords: +- java +aliases: +- /doc/deploy/application/java +- /doc/deploy/application/java/java +- /doc/deploy/application/java/by-framework +- /doc/getting-started/by-language/java +- /doc/java +- /doc/java/select-java-version +- /doc/java-hosting +- /doc/partials/language-specific-deploy/java +comments: false +--- + + +{{< hextra/hero-subtitle >}} +Find detailed instructions according to your framework +{{< /hextra/hero-subtitle >}} + +{{< cards >}} + {{< card link="/developers/doc/applications/java/java-gradle" title="Gradle" icon="gradle" >}} + {{< card link="/developers/doc/applications/java/java-jar" title="Jar" icon="java" >}} + {{< card link="/developers/doc/applications/java/java-maven" title="Maven" icon= "maven">}} + {{< card link="/developers/doc/applications/java/java-war" title="War/Ear" icon="java" >}} + {{< card link="/developers/guides/play-framework-1" title="Play 1" icon="play" >}} + {{< card link="/developers/guides/play-framework-2" title="Play 2" icon="play" >}} + +{{< /cards >}} + +### More Frameworks + +Looking for instructions on a specific framework deployment? + +{{< cards >}} +{{< card + title="Check our Guides" + link="/developers/guides" + icon="science" + >}} + {{< /cards >}} + diff --git a/content/doc/applications/java/java-gradle.md b/content/doc/applications/java/java-gradle.md new file mode 100644 index 000000000..173253097 --- /dev/null +++ b/content/doc/applications/java/java-gradle.md @@ -0,0 +1,129 @@ +--- +type: docs +title: Gradle +description: Gradle is a project automation tool that builds… +tags: +- deploy +keywords: +- java +- gradle +aliases: +- /doc/deploy/application/java/java-gradle +- /doc/java/java-gradle +- /java/java-gradle +comments: false +--- + +## Overview + +Clever Cloud offers you to run your Gradle projects. You can deploy this kind of project without changing your code, but running it on Clever Cloud needs some configuration files or environment variables, to add parameters like your gradle task for example. + +Gradle is a project automation tool that builds upon the concepts of Apache Ant and Apache Maven and introduces a Groovy-based domain-specific language (DSL) instead of the more traditional XML form of declaring the project configuration. + +Note : like other runtimes, Java application need listen on `0.0.0.0:8080` + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +{{% content "java-versions" %}} + +Accepted values are the following: + +{{< runtimes_versions java >}} + +(`graalvm-ce` for GraalVM 21.0.0.2, based on OpenJDK 11.0) + +## Configure your Java application + +You *must* provide a `clevercloud/gradle.json` file (gradle.json file in +clevercloud folder which is at the root of your repository) that +contains at least the following: + +```json +{ + "deploy": { + "goal": "grails:run" + } +} +``` + +That is the only option you really need to supply. + +### Optional configuration + +The full configuration can look like the following: + +```json +{ + "build": { + "type": "", + "goal": "" + }, + "deploy": { + "goal": "" + } +} +``` + +You can use the following properties: + +| Usage | Field | Description | +|----------|-------------------|---------------------------------------------------------------------------| +| Optional | **build → type** | can be maven, gradle or ant | +| Optional | **build → goal** | is the target you want to use to build your project | +| Required | **deploy → goal** | the goal/target and options you want to execute to deploy/run you project | + +## Custom run command + +If you need to run a custom command +you can specify it through the `CC_RUN_COMMAND` environment variable. +This will override the default way of running your application. + +Example: + +```bash +CC_RUN_COMMAND="java -jar somefile.jar " +``` + +### Environment injection + +Clever Cloud can inject environment variables that are defined in the +dashboard and by add-ons linked to your application. + +For Java applications, the environment is injected in the `System.getProperties()` object. + +So, to use a variable, you just need `System.getProperties().getProperty("MY_VARIABLE")`. + +For Groovy applications, just use the `System.getProperty("MY_VARIABLE")`. + +## The Gradle Wrapper + +Since Gradle can come in many versions, Clever Cloud automatically support the [Gradle Wrapper ↗](https://www.gradle.org/docs/current/userguide/gradle_wrapper.html). + +Just create and commit the `gradlew` file and the wrapper `jar` and `properties` files. Your working repository should look like this: + +{{< filetree/container >}} + {{< filetree/folder name="." >}} + {{< filetree/folder name="clevercloud" >}} + {{< filetree/file name="gradle.json" >}} + {{< /filetree/folder >}} + {{< filetree/file name="gradlew" >}} + {{< filetree/folder name="graddle" >}} + {{< filetree/folder name="wrapper" >}} + {{< filetree/file name="gradle-wrapper.jar" >}} + {{< filetree/file name="gradle-wrapper.properties" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} + {{< filetree/folder name="src" >}} + {{< /filetree/folder >}} + {{< /filetree/folder >}} +{{< /filetree/container >}} + + {{% content "new-relic" %}} + + {{% content "deploy-git" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/java/java-jar.md b/content/doc/applications/java/java-jar.md new file mode 100644 index 000000000..5bf0bee26 --- /dev/null +++ b/content/doc/applications/java/java-jar.md @@ -0,0 +1,141 @@ +--- +type: docs +title: Jar +description: Deploy a jar on Clever Cloud… +keywords: +- deploy +tags: +- java +aliases: +- /deploy/application/java/java-jar +- /doc/deploy/application/java/java-jar +- /doc/java/java-jar +comments: false +--- + +## Overview + +Clever Cloud offers you to run any Java ARchive file. You do not need to change your code, but running it on Clever Cloud needs some configuration files or environment variable to specify the JAR path. + +Note : like other runtimes, Java application needs to listen on `0.0.0.0:8080` + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +{{% content "java-versions" %}} + +{{< runtimes_versions java >}} + +(`graalvm-ce` for GraalVM 21.0.0.2, based on OpenJDK 11.0) + +## Configure your Java application + +You *must* either have the `CC_JAR_PATH` environment variable containing the +path to your jar or provide a `clevercloud/jar.json` file (jar.json file in +clevercloud folder which is at the root of your repository) that +contains at least the following: + +```json +{ + "deploy": { + "jarName": "path/to/jar" + } +} +``` + +That is the least you need to do. Note that `path/to/jar` *must not* start with a `/` and that the path should be relative to your repository's root. + +### Build options + +You do not need to build and commit a JAR. Instead you can push your +sources and build them with either gradle, ant or maven. Here is the +configuration you need to provide in the `clevercloud/jar.json` file: + +```json +{ + "build": { + "type": "maven"|"gradle"|"ant", + "goal": "package" + } +} +``` + +The `goal` field is what will be asked to the build command, like `mvn package` for a `maven` build with the `package` goal. + +An configuration example with a maven build that generates a JAR with +embedded dependencies is: + +```json +{ + "build": { + "type": "maven", + "goal": "package" + }, + "deploy": { + "jarName": "target/myproject-1.0-jar-with-dependencies.jar" + } +} +``` + +### An example of full configuration + +You can pass extra arguments to the `java` command by using the environment +variable `CC_EXTRA_JAVA_ARGS` and to your JAR by using `CC_JAR_ARGS` + +The full configuration can look like the following: + +```json +{ + "build": { + "type": "", + "goal": "" + }, + "deploy": { + "goal": "", + "jarName": "" + } +} +``` + +You can use the following properties: + +| Usage | Field | Description | +|----------|---------------------|---------------------------------------------------------------------------| +| Optional | **build → type** | can be `maven`, `gradle` or `ant` | +| Optional | **build → goal** | is the target you want to use to build your project | +| Optional | **deploy → goal** | the goal/target and options you want to execute to deploy/run you project | +| Required | **build → jarName** | jar file name of your application | + + {{% content "new-relic" %}} + +## Custom run command + +If you need to run a custom command (or just pass options to the program), +you can specify it through the `CC_RUN_COMMAND` environment variable. +This will override the default way of running your application. + +Example: + +```bash +CC_RUN_COMMAND="java -jar somefile.jar " +``` + +### Environment injection + +Clever Cloud can inject environment variables that are defined in the +dashboard and by add-ons linked to your application. + +For Java applications, the environment is injected in the `System.getProperties()` object. + +So, to use a variable, you just need `System.getProperties().getProperty("MY_VARIABLE")`. + +For Groovy applications, just use the `System.getProperty("MY_VARIABLE")`. + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/java/java-maven.md b/content/doc/applications/java/java-maven.md new file mode 100644 index 000000000..c0aa2f59d --- /dev/null +++ b/content/doc/applications/java/java-maven.md @@ -0,0 +1,134 @@ +--- +type: docs +title: Maven +description: Maven is essentially a project management and comprehension tool… +tags: +- deploy +keywords: +- java +- maven +aliases: +- /deploy/application/java/java-maven +- /doc/deploy/application/java/java-maven +- /doc/deploy/application/java/old_java-maven +- /doc/java/java-maven +--- + +## Overview + +Clever Cloud offers you to run your Java Maven projects. You can deploy this kind of project without changing your code, but running it on Clever Cloud needs specific environment variables or configuration files, to add parameters like your targeted container for instance. + +Note : like other runtimes, Java application needs to listen on `0.0.0.0:8080` + +Maven is essentially a project management and comprehension tool and as such provides a way to help with managing: + +* Builds +* Documentation +* Reporting +* Dependencies +* SCMs +* Releases +* Distribution + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +## Configure your Java application + +### About Cargo + +To run your app, you can, for example, use plugins like cargo ([Find it here](https://codehaus-cargo.github.io/cargo/Maven+3+Plugin.html)). +Your application must be set to listen on the port 8080. + +{{% content "java-versions" %}} + +{{< runtimes_versions java >}} + +(`graalvm-ce` for GraalVM 21.0.0.2, based on OpenJDK 11.0) + +### Mandatory configuration + +#### Option 1: JSON file in repository + +The `clevercloud/maven.json` (maven.json file in clevercloud folder which is at the root of your repository) file must contain the _goal_ field to indicate how to start your application: + +```json + { + "deploy": { + "goal": "yourgoal" + } + } +``` + +An example of what can be found as a goal value is: + +```txt +"-Dtest.active=false -Dexec.mainClass=\"com.example.Main\" assembly:jar-with-dependencies exec:java" +``` + +#### Option 2: Environment variable + +If you don't want to add a file to your repository, or if you're using a monorepo with multiple applications in directories configured with the `APP_FOLDER` environment variable, you'll probably prefer to use an environment variable for deployment configuration. + +Simply define `MAVEN_DEPLOY_GOAL="yourgoal"` and it's OK + +Eg. `MAVEN_DEPLOY_GOAL="spring-boot:run"` for a Spring Boot application with spring-boot-maven-plugin + +### Optional configuration + +The full configuration can look like the following: + +```json +{ + "build": { + "type": "", + "goal": "" + }, + "deploy": { + "goal": "" + } +} +``` + +You can use the following properties: + +| Usage | Field | Description | +|----------|-------------------|---------------------------------------------------------------------------| +| Optional | **build → type** | can be `maven`, `gradle` or `ant` | +| Optional | **build → goal** | is the target you want to use to build your project | +| Required | **deploy → goal** | the goal/target and options you want to execute to deploy/run you project | + +### Specifying a profile + +If you need to specify a maven profile (either for the `build` or the `deploy` goal, you can add it in the `goal` section: + +```txt +"-Pmyprofile package" +``` + +Or use the `CC_MAVEN_PROFILES` environment variable. + +Eg. `CC_MAVEN_PROFILES="prod"`. + +## Custom run command + +If you need to run a custom command +you can specify it through the `CC_RUN_COMMAND` environment variable. +This will override the default `maven run` we use to run your application. + +Example: + +```bash +CC_RUN_COMMAND="java -jar somefile.jar " +``` + + {{% content "new-relic" %}} + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/java/java-war.md b/content/doc/applications/java/java-war.md new file mode 100644 index 000000000..213048d3d --- /dev/null +++ b/content/doc/applications/java/java-war.md @@ -0,0 +1,181 @@ +--- +type: docs +title: War/Ear +description: In JEE, applications modules are packaged as EAR and WAR based on their functionality +tags: +- deploy +keywords: +- java +- war +aliases: +- /deploy/application/java/java-war +- /doc/deploy/application/java/java-war +- /doc/java/java-war +- /doc/java-war +comments: false +--- + +## Overview + +Clever Cloud allows you to run WAR or EAR applications. You can deploy these projects without changing your code. We just need a configuration file with your targeted container. + +In {{< tooltip title="JEE">}}JEE{{< /tooltip >}}, application modules are packaged as EAR and WAR based on their purpose. + +* {{< tooltip title="WAR" >}}WAR{{< /tooltip >}}: Web modules which contains Servlet class files, JSP FIles, supporting files, GIF and HTML files are packaged as JAR file with *.war* extension. + +* {{< tooltip title="EAR" >}}EAR{{< /tooltip >}}: `*.war` and `*.jar` files are packaged as JAR file with `.ear` extension and deployed into Application Server. EAR file contains configuration such as application security role mapping, EJB reference mapping and context root URL mapping of web modules. + +Note : like other runtimes, Java application needs to listen on `0.0.0.0:8080` + +## Available containers + +Clever Cloud supports many servlet containers. +The supported containers are listed below: + +| Apache Tomcat | Jetty | Payara | Wildfly | +|-------------------------------|------------------------|-------------------------|----------------------------| +| Apache Tomcat 6.0 (TOMCAT6) | Jetty 9.0 (JETTY9) | Payara 5.2022 (PAYARA5) | WildFly 26.0.0 (WILDFLY26) | +| Apache Tomcat 8.8 (TOMCAT8) | Jetty 11.0.6 (JETTY11) | Payara 6.2023 (PAYARA6) | WildFly 27.0.1 (WILDFLY27) | +| Apache Tomcat 10.0 (TOMCAT10) | | | WildFly 33.0.1 (WILDFLY33) | + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +{{% content "java-versions" %}} + +{{< runtimes_versions java >}} + +(`graalvm-ce` for GraalVM 21.0.0.2, based on OpenJDK 11.0) + +## Configure your Java application + +{{< callout type="warning" >}} +You **must** provide a `clevercloud/war.json` file in your application repository. +{{< /callout >}} + +### Full configuration example + +Here's what your configuration file can look like: + +```json +{ + "build": { + "type": "maven", + "goal": "package" + }, + "deploy": { + "container": "TOMCAT8", + "war": [ + { + "file": "target/my-app-1.0-SNAPSHOT.war", + "context": "/app1", + "checkMe": "/app1/ping" + }, + { + "file": "my-second-app.war", + "context": "/app2", + "checkMe": "/app2/web/foobar" + } + ] + } +} +``` + +### Breaking down the configuration + +#### Requirements + +Here are the mandatory fields: + +```json +{ + "deploy": { + "container":"", + "war": [ + { + "file": "", + "context": "/", + "checkMe": "/" + } + ] + } +} +``` + +|Usage |Field |Description| +|----------|--------|------------------------------------------------------------------------| +|Required |**container**|Name of the container to use. Should contain one of the values inside parentheses in the containers table (uppercase).| +|Required |file |Should contain the path of the war/ear file relative to your application root.| +| Optional |context |- Must start with a slash (/), can be "/"
- Defines the base path you want your app to be under. If your app has a /foobar endpoint, it will be available under the `/{my-context}/foobar` path.
- Not needed for an `ear` file.
- The default value for a war is the name of the war without the extensions: helloworld-1.0.war will be deployed under the `/helloworld-1.0` context.| +| Optional |checkMe |- This field is recommended.
- A path to GET in order to test if the application is really running.
- By default we will consider that the application is up if the container is up.
- With this option, we will try to GET `/{checkMe}` for each one of your wars and consider the app down until every single checkMe path that replies a 200.| + +#### Let Clever Cloud build your application + +The mandatory part alone is enough… if you directly push a dry war file to deploy. You +might want to just push your code to Clever Cloud and let us build the app and generate +the war. + +That you can do, by setting the "build" field object in the `war.json` file: + +```json +{ + "build": { + "type": "", + "goal": "" + } +} +``` + +| Usage | Field | Description | +|---------------------------------|-------|------------------------------------------------| +|Required | **type** |- The tool you want to use to build your app.
- Can be "maven", "gradle", "sbt" or "ant" | +|Required | **goal** |- The goal you want the tool to execute.
- Basically, for maven, you want to put "package" in here. | + +## Available containers for war.json + +Here's the list of the configuration values for the "container" field in `war.json` (with **End Of Life** versions tagged as `EOL`): + +| Value | Description | EOL | +|------------|----------------------------------------------------------------------------------------------|-----| +| GLASSFISH3 | Use Glassfish 3.x (see ) | | +| GLASSFISH4 | Use Glassfish 4.x (see ) | | +| JBOSS6 | Use JBoss AS 6.x (see ) | | +| JBOSS7 | Use JBoss AS 7.x (see ) | | +| RESIN3 | Use Resin AS 3.x (see ) | | +| RESIN4 | Use Resin AS 4.x (see ) | | +| JETTY6 | Use Jetty servlet container 6.x (see ) | EOL | +| JETTY7 | Use Jetty servlet container 7.x (see ) | EOL | +| JETTY8 | Use Jetty servlet container 8.x (see ) | EOL | +| JETTY9 | Use Jetty servlet container 9.x (see ) | EOL | +| TOMCAT4 | Use Tomcat servlet container 4.x (see ) | | +| TOMCAT5 | Use Tomcat servlet container 5.x (see ) | | +| TOMCAT6 | Use Tomcat servlet container 6.x (see ) | | +| TOMCAT7 | Use Tomcat servlet container 7.x (see ) | | +| TOMCAT8 | Use Tomcat servlet container 8.x (see ) | | +| PAYARA4 | Use Payara servlet container 4.x (see ) | | +| WILDFLY9 | Use Wildfly servlet container 9.x (see ) | | +| WILDFLY17 | Use Wildfly servlet container 17.x (see ) | | +| WILDFLY23 | Use Wildfly servlet container 23.x (see ) | | + +{{% content "url_healthcheck" %}} + +## Custom run command + +If you need to run a custom command +you can specify it through the `CC_RUN_COMMAND` environment variable. +This will override the default way of running your application. + +Example: + +```bash +CC_RUN_COMMAND="java -jar somefile.jar " +``` + + {{% content "new-relic" %}} + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} diff --git a/content/doc/applications/linux.md b/content/doc/applications/linux.md new file mode 100644 index 000000000..478a9b09e --- /dev/null +++ b/content/doc/applications/linux.md @@ -0,0 +1,67 @@ +--- +type: docs +linkTitle: Linux +title: Linux application runtime +description: Build and deploy any application with Mise and your favorite tools +aliases: +- /doc/deploy/application/other +- /doc/deploy/not-supported +--- + +## Overview + +Clever Cloud platform provides a multi-runtime environment, including many tools to deploy and run your applications. The Linux runtime is a versatile solution to build and deploy any kind of application. The Mise package manager helps you to install and manage any supported dependencies Clever Cloud doesn't provide by default such as Dart, Gleam, Zig for example. + +> [!NOTE] Linux is a new runtime +> Help us to improve it by reporting any issue or suggestion on the [Clever Cloud Community](https://github.com/CleverCloud/Community/discussions/categories/paas-runtimes) + +## Create your Linux application + +To create a new Linux application, use the [Clever Cloud Console](https://console.clever-cloud.com) or [Clever Tools](https://github.com/CleverCloud/clever-tools): + +```bash +clever create --type linux +``` +* [Learn more about Clever Tools](/developers/doc/cli/) +* [Learn more about Clever Cloud application deployment](/developers/doc/quickstart/#create-an-application-step-by-step) + +## Configure your Linux application + +### Mandatory needs + +Linux runtime only requires a `CC_RUN_COMMAND` to execute, with a working web application listening on `0.0.0.0:8080`. + +* [Learn more about environment variables on Clever Cloud](/developers/doc/reference/reference-environment-variables/) + +### Build phase + +During the build phase, Clever Cloud will run the `CC_BUILD_COMMAND` if provided. You can use it to install dependencies, compile your code, or any other task you need to perform before running your application. + +- [Learn more about Deployment hooks](/developers/doc/develop/build-hooks/) + +> [!TIP] Use Mise package manager to define build/run commands +> If you define `build` and `run` tasks in the `mise.toml` file [or as File Tasks](https://mise.jdx.dev/tasks/#tasks-in-mise-toml-files), Clever Cloud will automatically use them. `CC_BUILD_COMMAND` and `CC_RUN_COMMAND` have precedence over the `build` and `run` tasks defined by Mise. + +## Clever Task and Multi-runtime approach + +Linux runtime is perfect fit to run on-demand workloads on Clever Cloud: configure an application as Tasks from the `Information` panel in [the Console](https://console.clever-cloud.com) or with [Clever Tools](/developers/doc/cli/applications/#tasks): + +```bash +clever create --type linux --task "your-task-command --and arguments" +clever deploy # or clever restart if there is no code change +``` + +- [Learn more about Clever Tasks](/developers/doc/develop/tasks/) + +## Expand your toolbox with Mise package manager + +{{% content "mise" %}} + +### Mise configuration examples + +- [Deploy a Dart application with Mise](https://github.com/CleverCloud/dart-with-mise-example) +- [Deploy a Swift application with Mise](https://github.com/CleverCloud/swift-hello-world-example) +- [Deploy a Zig application with Mise](https://github.com/CleverCloud/zig-with-mise-example) + +{{% content "redirectionio" %}} +{{% content "varnish" %}} diff --git a/content/doc/applications/meteor.md b/content/doc/applications/meteor.md new file mode 100644 index 000000000..c3fff32ce --- /dev/null +++ b/content/doc/applications/meteor.md @@ -0,0 +1,104 @@ +--- +type: docs +title: Meteor.js +description: Meteor is an open source platform for web, mobile, and desktop +tags: +- deploy +keywords: +- meteor +- meteorjs +- nodejs +aliases: +- /deploy/application/javascript/by-framework/meteor +- /doc/applications/javascript/meteor +- /doc/applications/javascript/by-framework/meteor +- /doc/nodejs/meteor +--- + +## Overview + +Clever Cloud allows you to deploy any Meteor.js application. This page will explain how to set up your application to run it on our services. + +Be sure your `.meteor` folder is in your git repository. + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +## Configure your Meteor.js based application + +### Mandatory configuration + +#### Set up environment variables + +To run your Meteor.js application you need a few mandatory environment variables: + +* `MONGO_URL`: this is the mongo uri you can find in your mongodb's dashboard, it has to start with `mongodb://` +* `ROOT_URL`: this is your application's root url. It has to start with `http://` or `https://` +* `PORT`: keep the current value of 8080 + +With Meteor 2.6.n comes MongoDB 5.n and [the new npm driver](https://guide.meteor.com/2.6-migration.html). You need to append `?directConnection=true` in your `MONGO_URL` to avoid the new mongo driver Service Discovery feature. + +#### Optional Meteor settings as environment variable + +Some application require a `settings.json` file to [store api keys and other various private and public Meteor variables](https://v2-docs.meteor.com/api/core#Meteor-settings). +You can declare a `METEOR_SETTINGS` environment variable and past the content of the json file as the value of this key. + +## Specify required Node.js version + +Since building with the latest version of Node.js might fail, you should specify in the `package.json` file of the application the version needed for your Meteor application ; as shown in [Deploying Node.js apps](/developers/doc/applications/nodejs/#requirements) documentation. +To find out which version is required by your application type the following command `meteor node -v` inside root folder. + +Currently with Meteor *2.6.1* the Node.js version is *14.18.3* so you should add the following inside the `package.json` file. + +```json + … + "engines": { + "node": "14.18.3" + }, + … +``` + +You may change the node version value according to the application requirements. + +### Activate the dedicated build + +Meteor.js uses a lot of memory during the build. You most likely will need to activate the [dedicated build feature](/developers/doc/administrate/apps-management/#edit-application-configuration) and set your vertical scaling size at least to **M**. + +If your build still fails after you enabled the feature, please contact us on the support so we can set you a bigger scaler. + +### Automatic HTTPS redirection + +You can use the [force-ssl](https://atmospherejs.com/meteor/force-ssl) atmosphere package to redirect your users to the HTTPS version of your application. + +### Custom start parameters + +If you want to set custom start parameters, the main entry point of built meteor applications is: `.build/bundle/main.js`. +Add in the `scripts.start` field of the package.json: `node .build/bundle/main.js ` + +### Deployment process on Clever Cloud + +At each deployment, the needed Meteor.js version will be read from `.meteor/release` and installed. +Your application will then be built using `meteor build --server-only` and deployed from the files created by this command. + + {{% content "env-injection" %}} + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +### Oplog Tailing + +Oplog tailing is supported on dedicated databases (starting from Hazelnut size). Contact the support to enable oplog. Once enabled, set the following environment variable: + +* `MONGO_OPLOG_URL`: `mongodb://[…]mongodb.services.clever-cloud.com:{DB_PORT}/local?authSource={DB_NAME}` + +Since Meteor 2.6.n the mongo driver detect the `MONGO_OPLOG_URL` by itself and you should not add this to your environment variables. + +## Migrate from a Node.js instance + +If you want to migrate from your classic node.js app to a meteor application, contact [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice) with the application id. + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/nodejs.md b/content/doc/applications/nodejs.md new file mode 100644 index 000000000..ae4b2b076 --- /dev/null +++ b/content/doc/applications/nodejs.md @@ -0,0 +1,256 @@ +--- +type: docs +linkTitle: Node.js & Bun +title: Node.js & Bun runtime +description: Run JavaScript applications on Clever Cloud with Node.js and npm, or alternative tools (Bun, Deno, pnpm or Yarn) +aliases: +- /applications/javascript/nodejs +- /deploy/application/javascript/by-framework/nodejs +- /doc/applications/javascript +- /doc/applications/javascript/by-framework/nodejs +- /doc/applications/javascript/nodejs +- /doc/deploy/application/node +- /doc/getting-started/by-language/node +- /doc/deploy/application/javascript +- /doc/deploy/application/javascript/by-framework/meteor +- /doc/deploy/application/javascript/by-framework/nodejs +- /doc/deploy/application/javascript/nodejs +- /doc/nodejs +- /doc/nodejs/nodejs +- /doc/nodejs-hosting +- /doc/partials/language-specific-deploy/node +- /getting-started/by-language/node +--- + +## Overview + +Clever Cloud allows you to deploy any [Node.js](https://nodejs.org) application. We do support **any stable version of Node.js**. Learn more about [Node.js release schedule](https://nodejs.org/en/about/previous-releases). This page explains how to set up your application to run it on our service. + +## Configure your Node.js application + +### Mandatory configuration + +Be sure that: + +* you listen on HTTP port **0.0.0.0:8080** +* you have a `package.json` file +* your `package.json` either has a **scripts.start** or **main** field +* the folder `/node_modules` is mentioned in your `.gitignore` file +* you enable production mode by setting the [environment variable](#setting-up-environment-variables-on-clever-cloud) `NODE_ENV=production` + +### About package.json + +A valid `package.json` file should look like the following: + +```json +{ + "name" : "myApp", + "version" : "0.1.0", + "main" : "myApp.js", +} +``` + +or + +```json +{ + "name" : "myApp", + "version" : "0.1.0", + "scripts" : { + "start" : "node myApp.js" + } +} +``` + +You can use additional scripts as an alternative to [Clever Cloud hooks](/developers/doc/develop/build-hooks/#hooks-types); see [the npm documentation](https://docs.npmjs.com/cli/using-npm/scripts#npm-install). For example, `scripts.preinstall`, `scripts.install` and `scripts.postinstall` are executed during the build phase if defined. `scripts.prestart` and `scripts.poststart` are executed before and after the `scripts.start` command. Thus, your `package.json` can look like this: + +```json +{ + "name" : "myApp", + "version" : "0.1.0", + "scripts" : { + "preinstall": "./download.sh", // during build phase, before dependencies installation + "postinstall": "./cleanup.sh", // during build phase, after dependencies installation + "prestart": "./prepare.sh", // during run phase, before the start command + "start" : "node myApp.js", + } +} +``` + +### Custom run command + +If you need to run a custom command (or just pass options to the program), you can specify it through the `CC_RUN_COMMAND` [environment variable](#setting-up-environment-variables-on-clever-cloud). For instance, to launch `scripts.start` with a yarn based application, you must have `CC_RUN_COMMAND="yarn start"`. + +### Dependencies + +If you need some modules you can easily add some with the *dependencies* field in your `package.json`. Here is an example: + +```json {linenos=table} +{ + "name" : { … }, + "engines": { … }, + "dependencies": { + "express": "5.x", + "socket.io": "4.8.x", + "underscore": "1.13.7" + } +} +``` + +If your application has private dependencies, you can add a [private SSH key](/developers/doc/reference/common-configuration/#private-ssh-key). + +## Supported package managers + +We support any package manager compatible with Node.js. The [environment variable](#setting-up-environment-variables-on-clever-cloud) `CC_NODE_BUILD_TOOL` allows you to define which one you want to use. The default value is set to `npm`, but it can be any of these values: + +* `bun`: uses [Bun](https://bun.sh) as a package manager and as a runtime +* `npm` or `npm-install`: default, uses [npm install](https://docs.npmjs.com/cli/install) +* `npm-ci`: uses [npm clean-install](https://docs.npmjs.com/cli/ci) +* `yarn`: uses [Yarn Classic (v1)](https://classic.yarnpkg.com/lang/en/) +* `yarn2`: uses [Yarn Berry (v2 or later)](https://yarnpkg.com/) +* `custom`: use another package manager, defined with `CC_CUSTOM_BUILD_TOOL` + +You can also deploy using Deno with additional configuration. See the [Lume with Deno guide](/developers/guides/lume-deno/) for example. + +> [!NOTE] +> If a `bun.lock` or a `yarn.lock` file exists in your application's main folder, `bun`/`yarn` is used. To overwrite this behavior, either delete the `bun.lock`/`yarn.lock` file or set the `CC_NODE_BUILD_TOOL` environment variable. + +### Set Node.js version + +If you need a specific version or branch of Node.js, set `CC_NODE_VERSION`. You can use major, minor, patch version, such as `24`, `23.11` or `22.15.1` for example. If this environment variable isn't set, the latest LTS version available on Clever Cloud is used. + +{{< runtimes_versions node >}} + +> [!NOTE] +> For legacy reasons, the system prioritizes to the `engines.node` value in `package.json` over the `CC_NODE_VERSION` environment variable when both are set. + +### Bun version + +If you use Bun, your application is deployed with the latest available version on Clever Cloud: + +{{< runtimes_versions bun >}} + +### Yarn 3.x and 4.x support + +With recent versions of Yarn, you need to put the global folder within your application to manage restarts from build cache. You can do it by setting `YARN_GLOBAL_FOLDER` to `$APP_HOME/.yarncache/` for example, in the [Console](https://console.clever-cloud.com) or through [Clever Tools](https://github.com/CleverCloud/clever-tools): + +``` +clever env set YARN_GLOBAL_FOLDER '$APP_HOME/.yarncache/' +``` + +### Corepack and packageManager support + +Since Node.js v14.19.0 and v16.9.0, you can use [Corepack](https://nodejs.org/api/corepack.html) as an experimental feature to select a package manager—npm, pnpm, or yarn—and specify its version. You can do this with a simple command (e.g.: `corepack use yarn@*`) or the [`packageManager`](https://nodejs.org/api/packages.html#packagemanager) field in `package.json`. Always set `CC_NODE_BUILD_TOOL` when using `pnpm` or `yarn`, and make sure to set `CC_CUSTOM_BUILD_TOOL` when using `pnpm`. + +#### Example: Deploy with pnpm + +To deploy an application with pnpm, set the following environment variables: + +{{< tabs items="npm, Corepack" >}} + {{< tab >}}**Install with `npm`**: + ```bash + CC_NODE_BUILD_TOOL="custom" + CC_PRE_BUILD_HOOK="npm install -g pnpm" + CC_CUSTOM_BUILD_TOOL="pnpm install && pnpm build" + ``` + {{< /tab >}} + + {{< tab >}}**Enable with Corepack**: + ```bash + CC_NODE_BUILD_TOOL="custom" + CC_PRE_BUILD_HOOK="corepack enable pnpm" + CC_CUSTOM_BUILD_TOOL="pnpm install && pnpm build" + ``` + {{< /tab >}} +{{< /tabs >}} + +This performs the following steps: + +1. `CC_NODE_BUILD_TOOL` indicates that your applications is using a custom build tool +2. `CC_PRE_BUILD_HOOK` installs/enable `pnpm` globally +3. `CC_CUSTOM_BUILD_TOOL` installs the dependencies and builds the app + +Depending on your stack, you may also need to add `CC_RUN_COMMAND` to your environment variables, with the appropriate command to run your application. For example, to deploy an [Astro](https://astro.build/) application in a Node.js runtime, use `CC_RUN_COMMAND="pnpm start --port 8080 --host 0.0.0.0"`. + +{{< callout type="info" >}} +`CC_RUN_COMMAND` depends on your framework and your stack. The one in this example starts an Astro app, [which takes the port and the host as arguments](https://docs.astro.build/en/reference/cli-reference/#--port-number). To run your app, make sure you are using the correct command by checking the accurate framework documentation. +{{< /callout >}} + +#### Development Dependencies + +Development dependencies aren't automatically installed during the deployment. You can control their installation setting `CC_NODE_DEV_DEPENDENCIES` environment variable to `install` or `ignore`. This variable overrides the default behavior of `NODE_ENV`. + +Here are various scenarios: + +* `CC_NODE_DEV_DEPENDENCIES=install`: Development dependencies are installed. +* `CC_NODE_DEV_DEPENDENCIES=ignore`: Development dependencies aren't installed. +* `NODE_ENV=production` and `CC_NODE_DEV_DEPENDENCIES=install`: Development dependencies are installed. +* `NODE_ENV=production` and `CC_NODE_DEV_DEPENDENCIES=ignore`: Development dependencies aren't installed. +* `NODE_ENV=production`: Package manager (npm/yarn) default behavior. Development dependencies aren't installed. +* Neither `NODE_ENV` nor `CC_NODE_DEV_DEPENDENCIES` are defined: Package manager (npm/yarn) default behavior. Development dependencies are installed. + +### Use private repositories with CC_NPM_REGISTRY and NPM_TOKEN + +Since April 2015, `npm` allows you to have private repositories. If you want to use such a feature, you only need to provide the auth token. Add it to your application through the `NPM_TOKEN` environment variable: + +```bash +NPM_TOKEN="00000000-0000-0000-0000-000000000000" +``` + +Then, the `.npmrc` file is created automatically for your application, with the registry URL and the token. + +```txt +//registry.npmjs.org/:_authToken=00000000-0000-0000-0000-000000000000 +``` + +Or you can set `CC_NPM_BASIC_AUTH` to use basic authentication + +```bash +CC_NPM_BASIC_AUTH="user:password" +``` + +To authenticate to another registry (like GitHub), you can use the `CC_NPM_REGISTRY` environment variable to define its host. + +```bash +CC_NPM_REGISTRY="npm.pkg.github.com" +NPM_TOKEN="00000000-0000-0000-0000-000000000000" +``` + +```txt +//npm.pkg.github.com/:_authToken=00000000-0000-0000-0000-000000000000 +``` + +## Deployment video + +{{< youtube id="9ww_t0o-GmA" >}} + +## Automatic HTTPS redirection + +You can use the [X-Forwarded-Proto header](/developers/doc/find-help/faq#how-to-know-if-a-user-comes-from-a-secure-connection) to enable it. + +If you are using [Express.js](https://expressjs.com/), you can use [express-sslify](https://www.npmjs.com/package/express-sslify) by adding: + +```javascript +app.use(enforce.HTTPS({ + trustProtoHeader: true +})); +``` + +{{% content "new-relic" %}} + +## Troubleshooting your application + +If you are often experiencing auto restart of your Node.js instance, maybe you have an application crashing that we automatically restart. +To target this behavior, you can gracefully shut down with events handlers on `uncaughtExeption` `unhandledRejection` `sigint` and `sigterm` and log at this moment, so you can fix the problem. + +{{% content "env-injection" %}} + +To access environment variables from your code, you can use `process.env.MY_VARIABLE`. + +{{% content "deploy-git" %}} + +{{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/php.md b/content/doc/applications/php.md new file mode 100644 index 000000000..9685cfef2 --- /dev/null +++ b/content/doc/applications/php.md @@ -0,0 +1,627 @@ +--- +type: docs +title: PHP with Apache +description: Deploy PHP applications with Apache HTTP server on Clever Cloud +tags: +- php +- deploy +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](/developers/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](/developers/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](/developers/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](/developers/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](/developers/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.4 for now: `amqp`, `apcu`, `blackfire`, `event`, `gnupg`, `grpc`, `imagick`, `imap`, `mailparse`, `maxminddb`, `memcache`, `memcached`, `mongodb`, `newrelic`, `oauth`, `opentelemetry`, `pdo_sqlsrv`, `protobuf`, `pspell`, `rdkafka`, `redis`, `solr`, `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) + +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](/developers/doc/reference/reference-environment-variables/) to disable an extension. + +## Configure the session storage + +By default, an [FS Bucket](/developers/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`](/developers/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 Redis to store PHP Sessions + +We provide the possibility to store the PHP sessions in a [Redis database](/developers/doc/addons/redis) to improve reliability. + +If your application is under heavy load, redis persistence for sessions can improve latency. + +To enable this feature, you need to: + +- enable Redis support on the application (create an [environment variable](/developers/doc/develop/env-variables) named `ENABLE_REDIS` with the value `true`.) +- create and link a Redis add-on +- create an [environment variable](#setting-up-environment-variables-on-clever-cloud) named `SESSION_TYPE` with the value `redis`. + +{{< callout type="warning" >}} +You must have a [Redis](/developers/doc/addons/redis) add-on [linked with your application](#linking-a-database-or-any-other-add-on-to-your-application) to enable PHP session storage in Redis. If no Redis add-on is linked with your application, the deployment will fail. +{{< /callout >}} + +## 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](/developers/guides/proxysql) + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/python.md b/content/doc/applications/python.md new file mode 100644 index 000000000..0eaf5aae2 --- /dev/null +++ b/content/doc/applications/python.md @@ -0,0 +1,235 @@ +--- +type: docs +title: Python +description: Python 2.7 and 3.12 are available on our platform. You can use git to deploy your application. +tags: +- deploy +keywords: +- python +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 +comments: false +--- + +## 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](/developers/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/* application/json application/xml application/javascript image/svg+xml`. + +##### Basic authentication + +If you need basic authentication, you can enable it using [environment variables](/developers/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/ruby.md b/content/doc/applications/ruby.md new file mode 100644 index 000000000..3a904bfe1 --- /dev/null +++ b/content/doc/applications/ruby.md @@ -0,0 +1,69 @@ +--- +type: docs +title: Ruby on Rails +description: Ruby on Rails is an open source web application framework which runs on the Ruby programming language +tags: +- deploy +keywords: +- ruby +- rails +aliases: +- /applications/ruby +- /doc/deploy/application/ruby +- /doc/deploy/application/ruby/by-framework +- /doc/deploy/application/ruby/by-framework/ruby-on-rails +- /doc/deploy/application/ruby/ruby-rack +- /doc/en/ruby-hosting +- /doc/getting-started/by-language/ruby +- /doc/partials/language-specific-deploy/ruby +- /doc/ruby +- /doc/ruby-hosting +- /doc/ruby/ruby +- /doc/ruby/ruby-on-rails +- /getting-started/by-language/ruby +comments: false +--- + +## Overview + +Ruby on Rails is an open source web application framework which runs on the Ruby programming language. It is a full-stack framework: it allows creating pages and applications that gather information from the web server, talk to or query the database, and render templates out of the box. As a result, Rails features a routing system that is independent of the web server. + +Clever Cloud allows you to deploy any Ruby on Rails application. This page will explain you how to set up your application to run it on our service. +You do not need to change a lot in your application, the *requirements* will help you configure your applications with some mandatory files to add, and properties to setup. + +- [An example of Ruby on Rails application on Clever Cloud](https://github.com/CleverCloudDemos/demo-rubyonrails-pg-rest) + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +{{% content "ruby" %}} + +{{% content "new-relic" %}} + +{{% content "env-injection" %}} + +To access environment variables from your code, just get them from the environment with `ENV["MY_VARIABLE"]`. + +## Make sure to log on stdout + +Since January 2024, your logs may no longer show in your Clever Cloud console. +In production.rb, you should find something like: + +```ruby +if ENV['RAILS_LOG_TO_STDOUT'].present? + logger = ActiveSupport::Logger.new($stdout) + logger.formatter = config.log_formatter + config.logger = ActiveSupport::TaggedLogging.new(logger) +end +``` + +It means you need to add `RAILS_LOG_TO_STDOUT=true` in your environment variables. + +{{% content "deploy-git" %}} + +{{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/rust.md b/content/doc/applications/rust.md new file mode 100644 index 000000000..7becdd452 --- /dev/null +++ b/content/doc/applications/rust.md @@ -0,0 +1,176 @@ +--- +type: docs +title: Rust +description: Rust is a system programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety +tags: +- deploy +keywords: +- rust +- cargo +aliases: +- /applications/rust +- /deploy/application/rust/rust +- /doc/deploy/application/rust +- /doc/deploy/application/rust/rust +- /doc/getting-started/by-language/rust +- /doc/partials/language-specific-deploy/rust +- /doc/rust +- /doc/rust/rust +- /doc/rust-hosting +- /rust-hosting +comments: false +--- + +## Overview + +Rust is a system programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety. You can build Rust web services with frameworks like [Actix](https://actix.rs/) or [Iron](https://github.com/iron/iron). + +Clever Cloud allows you to deploy Rust web applications. This page will explain you how to set up your application to run it on our service. + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +## Configure your Rust application + +### Mandatory configuration + +Make sure that: + +* you have pushed in **master** branch +* you listen on port **8080** +* you have committed `Cargo.lock` +* you have at least one binary target in `Cargo.toml` + +The result of `cargo build --release --locked` must be an executable which starts a web server listening on `0.0.0.0:8080`. + +For instance, a minimal [iron](https://github.com/iron/iron) application can look like this: + +```rust +extern crate iron; + +use iron::prelude::*; +use iron::status; + +fn main() { + fn hello_world(_: &mut Request) -> IronResult { + Ok(Response::with((status::Ok, "Hello World!"))) + } + + let _server = Iron::new(hello_world).http("0.0.0.0:8080").unwrap(); + println!("On 8080"); +} +``` + +### Multiple binary targets + +If your `Cargo.toml` defines multiple targets, you must specify the one you want to run, with the `CC_RUST_BIN` environment variable. +If `CC_RUST_BIN` is specified, then the executable produced by this target is used to start the application. + +### Custom run command + +If you need to run a custom command (or just pass options to the program), you can specify it through the `CC_RUN_COMMAND` [environment variable](#setting-up-environment-variables-on-clever-cloud). + +For instance, you can have `CC_RUN_COMMAND=./target/release/myapp `. + +### Dependencies + +Make sure to list all your dependencies in `Cargo.toml`. For the example above, you need: + +```toml +[package] +name = "my-app" +version = "0.1.0" +authors = [] + +[dependencies] +iron = "0.4.0" +``` + +### Cached dependencies + +#### Enabling dependencies caching + +You can enable dependencies caching by adding the `CC_CACHE_DEPENDENCIES=true` [environment variable](#setting-up-environment-variables-on-clever-cloud) in your application. + +#### Disabling dependencies caching + +You can disable dependencies caching completely by removing the `CC_CACHE_DEPENDENCIES` environment variable from the Clever Cloud console, in the **Environment variables** menu of your application. Or by setting it to `CC_CACHE_DEPENDENCIES=false`. + +To fully remove cached dependencies, you have to rebuild your application from scratch. You can select "rebuild and restart" from the Clever Cloud console or launch `clever restart --without-cache` with the Clever Tools CLI. + +### Private dependencies + +If you use dependencies on a private git repository inside your project, it needs a bit of configuration until [this cargo issue](https://github.com/rust-lang/cargo/issues/1851) has been resolved. + +First, you need to use the `HTTPS` url as the git url for your dependency in your `Cargo.toml`: + +`private-dep = { git = "https://github.com/user/my-private-dep.git" }` + +Then, you need to create a personal access token. It allows to not use your password: + +* `Github`: +* `GitLab`: (API rights are needed) + +Once you have the token, we need to tell Git to use a credential store. For that, we are going to create it. + +Create a `clevercloud/pre-build.sh` file at the root of your application and paste: + +```bash +#! /usr/bin/env bash + +git config --global credential.helper store +echo "https://${GIT_USERNAME}:${GIT_PASSWORD}@gitlab.com" > ~/.git-credentials +chmod 600 ~/.git-credentials +``` + +If you have multiple private repositories, add them accordingly. + +Now, go into the environment variables page of your application and create those environment variables: + +* `GIT_USERNAME`: your Github / gitlab / other username +* `GIT_PASSWORD`: your Github / gitlab / other password +* `CC_PRE_BUILD_HOOK`: clevercloud/pre-build.sh +* `CC_POST_BUILD_HOOK`: rm /home/bas/.git-credentials + +This adds the git configuration before the build start and it cleans it after the build has been done. + +### Rust channels + +By default, your application is built with the latest stable rust version. If you require beta, nightly or a specific Rust version, you can set `CC_RUSTUP_CHANNEL` [environment variable](#setting-up-environment-variables-on-clever-cloud) value to `beta`, `nightly` or a specific version (eg. `1.36.0`). + +The build uses `rustup` to select the Rust version you need. + +### Cargo features + +You can enable specific features for your crate by settings the `CC_RUST_FEATURES` +environment variable to the list of features to enable. + +To access environment variables from your code, just get them from the environment with `std::env::var()`. + +If some environment variables are critical to your application, here is an approach you can use: + +```rust +use std::env; + +fn main() { + let my_config_value = env::var("MY_VAR").expect("Missing env var `MY_VAR`"); + + something_that_runs_a_web_server(my_config_value); +} +``` + +This loads the environment variable in your `main` function and use `.expect` to fail early. This way, the application will refuse to start with an helpful error message if `MY_VAR` is not defined. + +{{% content "deploy-git" %}} + +### Deployment Video + +{{< youtube id="mz_8jzrM13Y" >}} + +{{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} + diff --git a/content/doc/applications/scala.md b/content/doc/applications/scala.md new file mode 100644 index 000000000..161925c13 --- /dev/null +++ b/content/doc/applications/scala.md @@ -0,0 +1,111 @@ +--- +type: docs +title: Scala +description: Scala is an object-functional programming and scripting language that runs on the Java platform… +tags: +- deploy +keywords: +- scala +aliases: +- /applications/scala +- /deploy/application/scala/scala +- /doc/getting-started/by-language/scala +- /doc/deploy/application/scala +- /doc/deploy/application/scala/scala +- /doc/partials/language-specific-deploy/scala +- /doc/sbt +- /doc/scala +- /doc/scala/scala +- /doc/scala-hosting +- /scala/scala +comments: false +--- + +## Overview + +Clever Cloud allows you to deploy Scala (and Java) applications built with SBT. This document will explain you how to set up your app to run it on our service. + +If you're looking to deploy a [Play Framework](https://www.playframework.com) application, you can have a look at our dedicated [deployment guide for play framework applications](/developers/guides/play-framework-2) + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +## Configure your Scala application + +### Mandatory configuration + +Your application has to listen on port `8080` for worldwide connections (`0.0.0.0`). We set the system variable `http.port` to `8080` for you so in many cases (like for play applications) you don't have anything to do. +You need to use the [sbt-native-packager](#the-sbt-native-packager) in your project. + +### The sbt-native-packager + +We rely on `sbt-native-packager` to run applications. This plugin provides a `stage` task which is run during deployment. + +If your project doesn't already use [sbt-native-packager](https://github.com/sbt/sbt-native-packager), you need to add it to `project/plugins.sbt`. Please make sure you use an up-to-date version. + +In `project/plugins.sbt`: + +```scala +addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "1.7.0") +``` + +Then you need to configure the package type: + +In `build.sbt`: + +```scala +enablePlugins(JavaAppPackaging) + +# Disable javadoc packaging +mappings in (Compile, packageDoc) := Seq() +``` + +For more information, please have a look at the [documentation for sbt-native-packager](https://www.scala-sbt.org/sbt-native-packager/index.html) + +#### Custom sbt goal + +By default, the deployment system execute `sbt stage` and runs the first binary found into `/target/universal/stage/bin`. If you want to run another goal, you can specify it with the `SBT_DEPLOY_GOAL` [environment variable](#setting-up-environment-variables-on-clever-cloud). + +#### Multi-module build + +If you have a single repository with multiple modules or want to build a specific module in a monorepo (and no top-level `stage` task), then you can specify the sbt task with `SBT_DEPLOY_GOAL`. + +`CC_SBT_TARGET_DIR` must be set to the relative path of the module and `CC_SBT_TARGET_BIN` to the name of the binary to run. + +For instance, if you want to deploy a module named `service1` that produce a binary named "my-binary", you have to define the following variables: + +```shell +SBT_DEPLOY_GOAL=service1/stage +CC_SBT_TARGET_DIR=service1 +CC_SBT_TARGET_BIN=my-binary +``` + +Check details on [environment variables](#setting-up-environment-variables-on-clever-cloud). + +Our engine will execute the `sbt service1/stage` and will run `service1/target/universal/stage/bin/my-binary` + +**Note:** even when `CC_RUN_COMMAND` is configured `CC_SBT_TARGET_DIR` and `CC_SBT_TARGET_BIN` should be set to the correct values. + +### HOCON users + +If you're using +[HOCON](https://github.com/typesafehub/config/blob/master/HOCON.md#hocon-human-optimized-config-object-notation) configuration files, then you can have direct acces to environment variables from the configuration file: + +```shell +application.secret=${APPLICATION_SECRET} +``` + +{{% content "new-relic" %}} + +{{% content "env-injection" %}} + +To access environment variables from your code, just get them from the environment with `System.getenv("MY_VARIABLE")`. Be aware that it can return null. + +{{% content "deploy-git" %}} + +{{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/doc/applications/static-apache.md b/content/doc/applications/static-apache.md new file mode 100644 index 000000000..33722746a --- /dev/null +++ b/content/doc/applications/static-apache.md @@ -0,0 +1,95 @@ +--- +type: docs +title: Static with Apache +description: Deploy Static files with Apache HTTP server on Clever Cloud +comments: false +--- + +## Overview + +If you only need to serve static files without executing any code on the backend, for instance for a javascript Single Page Application (SPA), you can create a static application. + +This runtime is based on apache, so shares a lot with the [PHP runtime](/developers/doc/applications/php). This means you can use `.htaccess` files for redirection or access control. + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +{{% content "env-injection" %}} + +Application deployment on Clever Cloud is via **Git or FTP**. + + {{% content "deploy-git" %}} + +{{% content "deploy-ftp" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} + +## Serving index.html for SPA (Single Page Application) routers + +When you work with an SPA framework like React, Vue.js, Angular…, you're using client side routing. +This means when you click on a link going to `/the-page`, your browser doesn't make an HTTP request for `/the-page`. +Instead, the client side router highjacks the clicks on links, changes the DOM to display the page and ask the browser to change the URL in the address bar to `/the-page`. + +What happens if you try to refresh the page? +If you do this, the browser will try to make an HTTP request for `/the-page`. +In most situations, SPA only have one HTML document at the root called `index.html`. +This is why, you'll probably get a 404 error. + +To fix this, most people using SPA frameworks configure their HTTP server to serve the `index.html` for all unkown requests. +By this we mean for all requests that don't have a matching file on disk to serve. + +To do this with our static applications, you need a `.htaccess` file like this at the root of your project: + +```ApacheConf +RewriteEngine On + +# If an existing asset or directory is requested, serve it +RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR] +RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d +RewriteRule ^ - [L] + +# If the requested resource doesn't exist, use index.html +RewriteRule ^ /index.html +``` + +## Prerendering with Prerender.io + +When you use a SPA framework, you are using Client side rendering. +One of the problem with this method is a poor SEO as search engine crawlers have more difficulty reading the content of this type of application. +To minimize this issue, prerendering can be a solution. + +If you want to Prerender your application on Clever Cloud, one solution is to use [Prerender.io](https://prerender.io/). +To use it with our static applications, you need a `.htaccess` file like this at the root of your project: + +```ApacheConf + + RequestHeader set X-Prerender-Token "" + RequestHeader set X-Prerender-Version "prerender-apache@2.0.0" + + + + RewriteEngine On + + + RewriteCond %{HTTP_USER_AGENT} googlebot|bingbot|yandex|baiduspider|facebookexternalhit|twitterbot|rogerbot|linkedinbot|embedly|quora\ link\ preview|showyoubot|outbrain|pinterest\/0\.|pinterestbot|slackbot|vkShare|W3C_Validator|whatsapp|redditbot|applebot|flipboard|tumblr|bitlybot|skypeuripreview|nuzzel|discordbot|google\ page\ speed|qwantify|bitrix\ link\ preview|xing-contenttabreceiver|google-inspectiontool|chrome-lighthouse|telegrambot [NC,OR] + RewriteCond %{QUERY_STRING} _escaped_fragment_ + RewriteCond %{REQUEST_URI} ^(?!.*?(\.js|\.css|\.xml|\.less|\.png|\.jpg|\.jpeg|\.gif|\.pdf|\.doc|\.txt|\.ico|\.rss|\.zip|\.mp3|\.rar|\.exe|\.wmv|\.doc|\.avi|\.ppt|\.mpg|\.mpeg|\.tif|\.wav|\.mov|\.psd|\.ai|\.xls|\.mp4|\.m4a|\.swf|\.dat|\.dmg|\.iso|\.flv|\.m4v|\.torrent|\.ttf|\.woff|\.svg)) + + RewriteRule ^(index\.html|index\.php)?(.*) http://service.prerender.io/%{REQUEST_SCHEME}://%{HTTP_HOST}$2 [P,END] + + +``` +You can find your `PRERENDER_TOKEN` on your [Prerender.io account](https://prerender.io/). + +You can verify your configuration work using [this guide](https://docs.prerender.io/docs/how-to-test-your-site-after-you-have-successfully-validated-your-prerender-integration). +## Apache Configuration with `CC_WEBROOT` + +If you set the `CC_WEBROOT = /` environment variable, make sure you put your `.htaccess` file at the root of your `/`. This is where Apache will look for directives when you deploy an application in a Static runtime. + +If you don't set the [`CC_WEBROOT`](/developers/doc/reference/reference-environment-variables/#php) environment variable, the root of your project is the root of your web server. + +## 🎓 Static Site Generators (SSG) guides +{{% content-raw "static-guides" %}} diff --git a/content/doc/applications/static.md b/content/doc/applications/static.md new file mode 100644 index 000000000..445936465 --- /dev/null +++ b/content/doc/applications/static.md @@ -0,0 +1,124 @@ +--- +type: docs +linkTitle: Static +title: Static Site Generators (SSGs) runtime +description: Deploy static websites. Astro, Docusaurus, Hugo, mdBook and Mkdocs autobuild +aliases: +- /doc/deploy/application/static +- /doc/deploy/application/static/static +- /doc/partials/language-specific-deploy/static +- /doc/static +- /doc/static/static +--- + +## Overview + +Static is a flexible, light and simple runtime dedicated to static sites generators (SSG), designed for minimum configuration effort with Auto-build feature. Pico instances are available, it allows users to put services in front of it, such as [Redirection.io](/developers/doc/reference/reference-environment-variables/#use-redirectionio-as-a-proxy) or [Varnish](/developers/doc/administrate/cache/). + +> [!NOTE] Static is a new runtime +> Help us to improve it by reporting any issue or suggestion on the [Clever Cloud Community](https://github.com/CleverCloud/Community/discussions/categories/paas-runtimes) + +## Create your Static application + +To create a new Static application, use the [Clever Cloud Console](https://console.clever-cloud.com) or [Clever Tools](https://github.com/CleverCloud/clever-tools): + +```bash +clever create --type static +``` +* [Learn more about Clever Tools](/developers/doc/cli/) +* [Learn more about Clever Cloud application deployment](/developers/doc/quickstart/#create-an-application-step-by-step) + +## Configure your Static application + +### Mandatory needs + +Static runtime only requires a working web application, with an `index.htm` or `index.html` file. If you need to serve files from a specific directory, set the `CC_WEBROOT` environment variable, relative to the root of your project (for example `/public`, default is `/`). + +* [Learn more about environment variables on Clever Cloud](/developers/doc/reference/reference-environment-variables/) + +### Build phase + +During the build phase, Clever Cloud will run the `CC_BUILD_COMMAND` if provided. You can use it to install dependencies, build your static website, or any other task you need to perform before running your application. If no `CC_BUILD_COMMAND` is provided, Clever Cloud will try to detect your Static Site Generator (SSG), build and deploy your website automatically. + +- [Learn more about Deployment hooks](/developers/doc/develop/build-hooks/) +- [Learn more about Static Site Generators (SSGs) Auto-build](#static-site-generators-ssg-auto-build) + +### Optimized build cache + +When [auto-build](#static-site-generators-ssg-auto-build) activates, or if you define `CC_WEBROOT`, the build cache contains only some configuration files and the served directory to optimize size, reduce archive time. When neither option applies, the system caches the entire application root directory instead. + +To override this behavior, set the `CC_OVERRIDE_BUILD_CACHE` environment variable with a colon-separated list of directories and files, relative to the application root. For example: `CC_OVERRIDE_BUILD_CACHE=myScript.sh:/myBuildDir`. + +## Supported web servers + +By default, the Rust-based [Static Web Server (SWS)](https://static-web-server.net) serves your website. If a valid Caddyfile is present at the root of your project, it will be used with [Caddy](https://caddyserver.com) and the `caddy run` command, you can also set its location with `CC_STATIC_CADDYFILE` (Default is `./Caddyfile`). + +You can force the use of Caddy by setting the `CC_STATIC_SERVER` environment variable to `caddy`. It configures your application to serve the website with the `caddy file-server` command which don't rely on a Caddyfile. + +## Custom configuration and port + +Caddy and SWS can be configured with a configuration file or through environment variables. You can also pass your own command line flags with `CC_STATIC_FLAGS`. To define a custom listen port, use `CC_STATIC_PORT` (default is `8080`). + +- Caddy configuration: + - [Command Line Arguments](https://caddyserver.com/docs/command-line) + - [Environment Variables](https://caddyserver.com/docs/caddyfile/concepts#environment-variables) + - [Caddyfile](https://caddyserver.com/docs/caddyfile) +- Static Web Server (SWS) configuration: + - [Command Line Arguments](https://static-web-server.net/configuration/command-line-arguments/) + - [Environment Variables](https://static-web-server.net/configuration/environment-variables/) + - [TOML Configuration File](https://static-web-server.net/configuration/config-file/) + +## Static Site Generators (SSG) Auto-build + +If you don't set a `CC_BUILD_COMMAND`, Clever Cloud try to detect and configure the Static Site Generator (SSG) through the presence of specific files in the project root. If detected the static website is built in the `cc_static_autobuilt` folder (or `CC_STATIC_AUTOBUILD_OUTDIR`), used as `CC_WEBROOT` and build cache content. If you defined a `CC_WEBROOT`, it will be used instead of `cc_static_autobuilt`. + +Supported Static Site Generators (SSG) are: + +### Astro + +* Build command: `npm i && npm run astro build -- --outDir ` +* Detected file: `astro.config.mjs`, `astro.config.ts`, `astro.config.js`, `astro.config.cjs` + +### Docusaurus + +* Build command: `npm i && npm run docusaurus build -- --out-dir ` +* Detected file: `docusaurus.config.js`, `docusaurus.config.ts` + +### Hugo + +* Build command: `hugo --gc --minify --destination ` +* Detected file: `hugo.json`, `hugo.toml`, `hugo.yaml` + +> [!TIP] Set the Hugo version +>Use a specific Hugo version by setting the `CC_HUGO_VERSION` environment variable to `0.145`, `0.146`, `0.147` (default) or `0.148` + +### mdBook + +* Build command: `mdbook build --dest-dir ` +* Detected file: `book.toml` + +### Mkdocs + +* Build command: `uvx mkdocs build --site-dir ` +* Detected file: `mkdocs.yml` + +### Nuxt.js + +* Build command: `npm i && npm run generate && mv .output/public ` +* Detected file: `nuxt.config.ts` + +### Vitepress + +* Build command: `npm i && npm run docs:build -- --outDir ` +* Detected file: `vitepress.config.js`, `vitepress.config.ts`, `vitepress.config.mjs`, `vitepress.config.mts` + +### Zola + +* Build command: `zola build --minify --output-dir ` +* Detected file: `config.toml` + +## 🎓 Static Site Generators (SSG) guides +{{% content-raw "static-guides" %}} + +{{% content "redirectionio" %}} +{{% content "varnish" %}} diff --git a/content/doc/applications/v.md b/content/doc/applications/v.md new file mode 100644 index 000000000..f24342554 --- /dev/null +++ b/content/doc/applications/v.md @@ -0,0 +1,55 @@ +--- +type: docs +linkTitle: V (Vlang) +title: V (Vlang) application runtime +description: Build and deploy your V (Vlang) based API and applications +--- + +## Overview + +[V](https://vlang.io) is a very simple modern language, similar to Go. It's a statically typed compiled programming language designed for building maintainable software. Its design has also been influenced by Oberon, Rust, Swift, Kotlin, and Python. One of its forces is it comes with [a strong standard library](https://modules.vlang.io/), built-in modules and a package manager. Thus, it includes a web server easy to use in V applications : [Veb](https://modules.vlang.io/veb.html). + +> [!NOTE] V (Vlang) is a new runtime +> Help us to improve it by reporting any issue or suggestion on the [Clever Cloud Community](https://github.com/CleverCloud/Community/discussions/categories/paas-runtimes) + +## Create your V (Vlang) application + +To create a new V (Vlang) application, use the [Clever Cloud Console](https://console.clever-cloud.com) or [Clever Tools](https://github.com/CleverCloud/clever-tools): + +```bash +clever create --type v +``` +* [Learn more about Clever Tools](/developers/doc/cli/) +* [Learn more about Clever Cloud application deployment](/developers/doc/quickstart/#create-an-application-step-by-step) + +## Configure your V (Vlang) application + +### Mandatory needs + +V (Vlang) runtime only requires a working application listening on `0.0.0.0:8080`. + +* [Learn more about environment variables on Clever Cloud](/developers/doc/reference/reference-environment-variables/) + +### Build phase + +During the build phase, the V (Vlang) application is built with the `v . -prod` command. To compile without the `-prod` flag, set `ENVIRONMENT=development`. You can choose a custom output binary name with the `CC_V_BINARY` environment variable, default is `${APP_HOME}/v_bin_${APP_ID}`. + +- [Deploy an example V application on Clever Cloud](https://github.com/CleverCloud/v-example) + +### V (Vlang) version and tools + +The currently deployed version of V (Vlang) on Clever Cloud is `0.4.11`. + +## V scripts (.vsh), Clever Tasks + +V (Vlang) can be used to execute [shell scripts (.vsh)](https://docs.vlang.io/other-v-features.html#cross-platform-shell-scripts-in-v). On Clever Cloud, to run such workloads as Clever Tasks, configure an application as Tasks from the `Information` panel in [the Console](https://console.clever-cloud.com) or with [Clever Tools](/developers/doc/cli/applications/#tasks): + +```bash +clever create --type v --task "./your-script.vsh --and arguments" +clever deploy # or clever restart if there is no code change +``` + +- [Learn more about Clever Tasks](/developers/doc/develop/tasks/) + +{{% content "redirectionio" %}} +{{% content "varnish" %}} diff --git a/content/doc/best-practices/12-factors.md b/content/doc/best-practices/12-factors.md new file mode 100644 index 000000000..6d4158c88 --- /dev/null +++ b/content/doc/best-practices/12-factors.md @@ -0,0 +1,26 @@ +--- +type: docs +title: The Twelve-Factor App +description: 12 factors are a great way to learn about cloud deployment +tags: +- develop +- best-practices +keywords: +- twelve factors +- cloud +- best practices +aliases: +- /doc/develop/12-factors +- /doc/develop/best-practices/12-factors +comments: false +--- + +The twelve-factor app is a methodology for writing software delivered as a service, which is what you are doing by pushing your code to Clever Cloud and for container deployment in general. By writing code following these principles, your application will be cloud ready by design. + +As a lot has already been written on the subject, we strongly recommend that you read some of the following links to begin with this methodology: + +- [https://en.wikipedia.org/wiki/Twelve-Factor_App_methodology](https://en.wikipedia.org/wiki/Twelve-Factor_App_methodology) +- [https://www.clearlytech.com/2014/01/04/12-factor-apps-plain-english/](https://www.clearlytech.com/2014/01/04/12-factor-apps-plain-english/) +- [https://12factor.net/](https://12factor.net/) + +Happy learning ! diff --git a/content/doc/best-practices/_index.md b/content/doc/best-practices/_index.md new file mode 100644 index 000000000..4bd53263d --- /dev/null +++ b/content/doc/best-practices/_index.md @@ -0,0 +1,21 @@ +--- +type: docs +weight: 9 +title: Best practices +description: Learn best practices on Clever Cloud +tags: +- getting-started +keywords: +- quickstart +aliases: +- /doc/quickstart +- /doc/develop/best-practices +comments: false +--- + +{{< cards >}} + {{< card link="/developers/doc/best-practices/blue-green" title="Blue/green deployment" icon="traffic-light" >}} + {{< card link="/developers/doc/best-practices/cloud-storage" title="Cloud storage" icon="cloud-arrow-up" >}} + {{< card link="/developers/doc/best-practices/load-testing" title="Load testing" icon= "chart-bar-square">}} + {{< card link="/developers/doc/best-practices/12-factors" title="The Twelve-Factor app " icon="checklist" >}} +{{< /cards >}} diff --git a/content/doc/best-practices/blue-green.md b/content/doc/best-practices/blue-green.md new file mode 100644 index 000000000..7c1439491 --- /dev/null +++ b/content/doc/best-practices/blue-green.md @@ -0,0 +1,49 @@ +--- +type: docs +title: Blue/Green Deployments +description: An explanation of what is Blue/Green deployment +tags: +- develop +- best-practices +keywords: +- blue/green +- deployment +aliases: +- /doc/develop/blue-green +- /doc/develop/best-practices/blue-green +comments: false +--- + +Blue/Green deployment is a technique used in automated deployment of applications, databases and services. +Its main goal is to minimize the downtime and risks of an application by running two identical environment instances, one called *Blue* and the other one called *Green*. + +## Contextual example + +Let's say you have a production environment called *Blue*, running for instance an e-commerce application. Your customers are routed to this *Blue* instance. In parallel, you will have a "sleeping clone" of *Blue*, named *Green*. +Now let's say you have achieved a new feature and want your customers to benefit of it. Using the "Blue/Green" technique, the new code will be used in *Green*. Once *Green* is ready, you will redirect your customers to *Green*, and we will put *Blue* in "sleeping mode". When you will add new modification you will do it on *Blue* this time, then on *Green* again, and so on. + +There are many benefits to this approach: + +- if *Green* fails to deploy there will be no downtime for your customers or users as you will not use the broken *Green* and stay on "Blue" until you fix your code so it can start +- if you are not happy with the changes you added in *Green*, you can "awake" *Blue* and get back to the previous version easily by routing the traffic to it + +## In the Clever Cloud context + +When you push your source code to the Clever Cloud git remote, Clever Cloud will automatically use the "Blue/Green" pattern to apply your changes to your production. + +A new VM, let's call it *Blue* is created. The deployment is successful when there's no error in the build phase and the [deployment healthcheck](/developers/doc/develop/healthcheck) is successful. And that's it, you will use the new version on production within seconds. + +If you push new changes, a *Green* VM will be created. + +### Deployment succeeds + +If the deployment succeeds, *Green* will be the version in production and *Blue* will be turned off minutes later. +This way, if you are not happy with the changes you made, just go the Clever Cloud web console, select your application and in the **Overview** menu, click the "Start last pushed commit" button, this will "awake" *Blue* and reverse your changes in production within a few minutes. + +#### Deployment fails + +If there is an error during the build phase or if the *Green* servers answers an error code on :8080/, we will alert you by email and *Blue* will remain the production server. + +Next time you push code a new *Green* VM will be created, then a *Blue* one, and so on. + +You also may see some deployments that you haven't triggered in your logs. It's because Clever Cloud uses "Blue/Green" pattern to update VMs, either security patches or versions updates. diff --git a/content/doc/best-practices/cloud-storage.md b/content/doc/best-practices/cloud-storage.md new file mode 100644 index 000000000..458f6ef41 --- /dev/null +++ b/content/doc/best-practices/cloud-storage.md @@ -0,0 +1,91 @@ +--- +type: docs +title: Cloud Storage +description: This will help you understand the difference between Cellar and FS Buckets +tags: +- develop +- best-practices +keywords: +- S3 +- amazon +- Storage +- file +- files +aliases: +- /doc/develop/best-practices/cloud-storage +- /doc/develop/cloud-storage +comments: false +--- + +You want to store files but you can't decide between FS Buckets and Cellar. This article will compare them: usage, pros/cons, pricing. + +Clever Cloud uses immutable disposable VMs. +Every time you redeploy your application, you lose the old instances and all the files stored on their filesystems. +If you want to avoid that, you have to store your important files outside of your instances. + +Cellar and FS Buckets both allow you to store files outside of your instances for later use. But there are some differences between them. + +{{< callout type="info" >}} +If you are coding a new project and need to store files, use Cellar. It will be cheaper and give you way more flexibility. If your want to run a WordPress site or some OSS PHP application and are in a hurry, you may not get to choose: use FS Buckets. +{{< /callout >}} + +## What is FS Bucket? + +Configuring FS Buckets in your application will give you a folder _in your filesystem_. This folder is shared between instances/applications. It's mounted over the network. As for any network filesystem there are upsides and downsides. + +### Upsides of FS Bucket + +If your application manages files on a filesystem, you don't have to change anything. +Just setup your FS Bucket to mount on a given folder, setup your application to write in that folder and you are good to go! + +Since the folder is mounted over the network, multiple instances/applications can read it like any file on the system. At the same time. + +### Downsides of FS Bucket + +Since it's a file on a filesystem, you can be tempted to store a SQLite (or equivalent) database in it. This would be wrong. +If many instances try to write in it at the same time, you might end up with a corrupted database. + +For the same reason, anything accessing a file in write at the same time might corrupt the data you put in it. + +## What is Cellar? + +Cellar is an Amazon S3 API implementation using [Ceph Rados Gateway](https://ceph.com/ceph-storage/object-storage/). +It provides an HTTP API that can be used with any S3 API Client. +Clients exist for a lot of languages. +You can use any S3 Client, from the official Amazon ones to the community ones. + +If you already use S3, you will be in your element. + +To store a file, issue a PUT HTTP request to Cellar's API. +To get a file, issue a GET request to the API. +You need secret and public keys to authenticate your requests. +You can manage ACLs and generate signed URLs with an expiration date. + +### Upsides of Cellar + +You can move the file uploads to your client entirely. +Just give it a temporary signed URL (generated by your backend) and it will be able to upload directly to Cellar. +That way, you don't have to handle the receive-and-upload part on the server side. + +Your files are stored in a secure way outside of your apps FS. So an attacker will have a harder time to find it. + +You can delegate the authorization part to Cellar by giving signed urls for file downloads and uploads. + +The files are stored with a replication factor of 3, meaning that there are 2 replicas in addition of the original data. + +### Downsides of Cellar + +When deploying an application you did not write, file uploads may already be developed using local files. Like in WordPress, PrestaShop, etc. So you would have to use plugins or hack it to upload to Cellar. + +## What should I choose? + +Well, you read the upsides and downsides of both. +You may understand where our preference goes, by now! +If you can, use Cellar. +S3 Client library exist in almost all languages. +It's [cheaper](/developers/doc/addons/cellar). +It's more resilient to hardware failures. +It gives you free processing power: when using files on your filesystem, you have to process them yourself. +When using Cellar, you can delegate the handling of the upload to Cellar itself. + +If you don't have a choice, use whatever you have to use. diff --git a/content/doc/best-practices/load-testing.md b/content/doc/best-practices/load-testing.md new file mode 100644 index 000000000..915e21071 --- /dev/null +++ b/content/doc/best-practices/load-testing.md @@ -0,0 +1,69 @@ +--- +type: docs +title: Load testing +description: Considerations and methods to perform a load test on Clever Cloud +tags: +- develop +- best-practices +keywords: +- test +- stress +- load +- performance +aliases: +- /doc/develop/load-testing +--- +## Overview + +Performing a performance test is the best way to determine how your application will perform under heavy load. + +In general, these tests make it possible to identify: + +* the maximum number of concurrent users +* whether the current resources are sufficient to operate your application in good conditions +* and the maximum operational capacity of your application + +## Considerations to take into account + +In the event that you use public front-ends, it is necessary to notify the support. Indeed, depending on the nature of the load, it is possible that a form of network blocking is performed by our teams if they are not notified. + +In case you have dedicated frontends, note that too much load could impact your other applications behind this frontend. Because in general, the amount of private front-ends is lower than the number of public front-ends (new public front-ends are added on a regular basis). + +## Why carry out these tests + +Performing these tests will allow you: + +* to have perspective on the performance and stability of your infrastructure. +* to be able to identify bottlenecks in particular stress scenarios +* to identify and remove any weaknesses in architectures via supervision and performance management strategies and increase scalability + +The determining elements are: + +* The response time of your transactions (poorly optimized requests, etc.) +* The performance of the application (single-threaded application, expectations of external services, generation of logs in a file, etc.) +* The performance of managed services such as databases (lack of indexes, unnecessary iterations, etc.) +* Software design in general +* Hardware limitations such as CPU, RAM, network, etc. +* bad middleware configurations (databases, server, etc.) +* The response time between the client and the application + +## Online and local load tools + +Choosing a load-testing solution will depend on several factors. If simplicity and speed are the most important factors, online tools are the most appropriate. On the other hand, if you have to test particular protocols, and have fine configuration options via a little programming / scripting and for a lower cost, you may want to use dedicated, local solutions. + +### Online + +Online services are available to perform your tests. Most offer typical user journey scenarios to allow you to simulate a user: + +* [K6](https://k6.io) +* [Octoperf](https://octoperf.com) +* [Loader.io](https://loader.io) + +### Local, with open source alternatives + +Some open source services to be installed on an infrastructure (workstation or IaaS in the best case) are also available: + +* [Gatling](https://gatling.io) +* [Drill](https://github.com/fcsonline/drill) +* [Locust](https://locust.io) +* [Jmeter](https://jmeter.apache.org) diff --git a/content/doc/best-practices/tips_and_tricks.md b/content/doc/best-practices/tips_and_tricks.md new file mode 100644 index 000000000..6e3d80921 --- /dev/null +++ b/content/doc/best-practices/tips_and_tricks.md @@ -0,0 +1,366 @@ +--- +title: Tips & Tricks +description: Discover some useful tips and tricks to improve your experience with Clever Cloud tools +tags: +- reference +- tips +- tricks +keywords: +- tips +- tricks +type: docs +--- +{{< hextra/hero-subtitle >}} + Clever Cloud offers many powerful features designed to make your development work easier. This guide reveals useful capabilities you might not know about, from shortcuts to time-saving tools. +{{< /hextra/hero-subtitle >}} + +## Web Console Features + +The [Clever Cloud Console](https://console.clever-cloud.com) is your control center for managing applications, add-ons, and organisations. Here are features that can enhance your workflow: + +### Advanced Menu Filtering + +The left sidebar menu includes a powerful search function. Beyond simple name searches, you can use special keywords to filter your resources: + +| Keyword | What it Shows | +| ------- | ----------- | +| `is:addon` | Lists all your add-ons | +| `is:app` | Shows only applications | +| `is:[addon]` | Filters specific add-on types (Examples: `is:postgresql`, `is:redis`, `is:mysql`) | +| `is:[runtime]` | Shows applications by runtime (Examples: `is:node`, `is:php`, `is:java`) | + +### OpenSearch support + +Clever Cloud supports OpenSearch, allowing you to add [the Console](https://console.clever-cloud.com) as a search engine in your browser, such as [Chrome](https://support.google.com/chrome/answer/95426) or [Firefox](https://support.mozilla.org/kb/add-or-remove-search-engine-firefox). Then, you can quickly search for applications, add-ons or organisations directly from your address bar. For example, add: + +``` +name: Clever Cloud +shortcut: cc +search URL: https://console.clever-cloud.com/search?q=%s +``` + +### Multi-line Environment Variables + +Environment variables support more than just single-line values. When editing variables in simple mode: + +1. Click in any variable's value field +2. Press `Enter` to create multiple lines +3. Add configuration files, long texts, or structured data + +This works across all input modes (simple, expert, and JSON) as well as through Clever Tools and the API. + +[Learn more about environment variables](/developers/doc/reference/reference-environment-variables/) + +### Quick Variable Creation + +Speed up environment variable creation with these shortcuts: + +- Use the `Add` button or press `CTRL+Enter` to create new variables +- Switch between simple, expert, and JSON modes for different input styles + +{{< callout type="info" >}} +Always select `UPDATE CHANGES` before leaving the environment variables page to save your modifications +{{< /callout >}} + +### Enhanced Logging System + +The Console includes a sophisticated logging interface with features for debugging and monitoring: + +- Filter logs by: + - Date and time ranges + - Text content + - Regular expressions + - Specific instances +- Customize your view with: + - Multiple color themes + - ANSI code stripping + - Line wrapping + - Configurable date formats and time zones +- Share logs easily by selecting and copying lines + +Clever Cloud retains your logs for 7 days as part of the standard service. + +[Explore logging features](/developers/doc/administrate/log-management/) + +### Universal Resource Access + +Navigate quickly to any resource using these features: + +#### Quick Access Link + +Access any application or add-on directly using its ID: + +```shell +https://console.clever-cloud.com/goto/id +``` + +#### Global Search + +Press the `/` key anywhere in the Console to search for applications, add-ons, or organisations by name or ID. + +#### Keyboard Navigation + +Use these shortcuts when viewing applications or add-ons: + +| Key | Takes You To | +| --- | ----------- | +| `?` | Keyboard shortcuts help | +| `a` | Application activity | +| `d` | Domain settings | +| `e` | Environment variables | +| `i` | Resource information | +| `l` | Logs view | +| `m` | Application metrics | +| `o` | Overview page | +| `s` | Scalability settings | + +### Running One-Time Tasks + +While Clever Cloud primarily runs continuous services, you can also execute one-time tasks: + +1. Define an application as a task in the `Information` panel, or +2. Create it through Clever Tools: `clever create --type TYPE --task "command to execute"` + +After pushing your code, the application: + +1. Starts normally +2. Installs dependencies +3. Completes the build process +4. Executes your specified command +5. Stops automatically when finished + +[Learn more about task execution](/developers/doc/develop/tasks/) + +### Database Management Tips + +Need to update your database? The Console's migration tool offers several options: + +- Upgrade to new major/minor versions without downtime +- Move databases between zones +- Apply patch updates +- Redeploy existing databases + +To get the latest patch version or redeploy, simply migrate to the same version, plan, and zone. + +[Database add-ons documentation](/developers/doc/addons/) +[Migration guide](/developers/doc/administrate/database-migration/) + +## Clever Tools Features + +The Clever Cloud CLI provides powerful command-line capabilities. Install it with: + +```bash +npm i -g clever-tools +``` + +Then run `clever login` to get started. + +### SSH Access Made Simple + +While the platform uses immutable infrastructure, sometimes you need SSH access for debugging. Use these commands: + +```bash +clever ssh # Connect to default app +clever ssh --app app_id_or_name # Connect to specific app +clever ssh -a app_id_or_name -i ~/.ssh/id_ed25519 # Use specific key +``` + +For extended debugging sessions, set `CC_TROUBLESHOOT=true` as an environment variable. This keeps your application running for up to 1 hour, even if errors occur. + +[SSH key management guide](/developers/doc/account/ssh-keys-management/) + +### Domain Configuration Diagnostics + +Check your domain setup with the built-in diagnostic tool: + +```bash +clever domain diag # Check current application +clever domain diag -a app_id_or_name # Check specific application +clever domain diag --app app_id_or_name --filter keyword # Filter results +``` + +{{< callout type="info" >}} + This tool may not catch all scenarios involving CDNs or private load balancers. +{{< /callout >}} + +### Application Management + +View all your applications with: + +```bash +clever applications list +``` + +This command groups applications by organisation for easy reference. + +### JSON Output Support + +Add `--format json` or `-f json` to most commands for machine-readable output: + +```bash +clever applications list --format json +``` + +This works well with tools like `jq`, `jless`, or `jql` for further processing. + +### The Power of `clever curl` + +Access the Clever Cloud API without managing authentication tokens using `clever curl`. It automatically handles credentials for you: + +```bash +# Get your account details +clever curl https://api.clever-cloud.com/v2/self + +# View all resources with JSON viewer +clever curl https://api.clever-cloud.com/v2/summary | jless +``` + +This tool helps you: + +- Test API endpoints quickly +- Create automation scripts +- Set up CI/CD pipelines +- Explore available resources + +[Explore the API documentation](/developers/api/) + +### Browser Integration + +Open your applications directly from the command line: + +```bash +# Open default application +clever open +clever open --app app_id_or_name + +# Access Console +clever console +clever console --app app_id_or_name +``` + +### Authentication Options + +Multiple ways to authenticate with Clever Tools: + +```bash +# Use environment variables for login +export CLEVER_TOKEN=TOKEN +export CLEVER_SECRET=SECRET +clever login + +# Direct login with credentials +clever login --token TOKEN --secret SECRET + +# One-time use without saving credentials +CLEVER_TOKEN=TOKEN CLEVER_SECRET=SECRET clever profile +``` + +### Contributing to Clever Tools + +Clever Tools is open source and built with Node.js. You can: + +- Report issues +- Suggest new features +- Submit pull requests +- Join the development community + +[Clever Tools documentation](/developers/doc/cli/) + +## Did You Know? + +### Stay Updated with Clever Cloud + +Track platform improvements through: + +- [Technical Changelog](/developers/changelog/) +- [RSS Feed](/developers/changelog/index.xml) +- [Blog Updates](https://www.clever-cloud.com/blog/) + +### Built-in Runtime Tools + +Every runtime includes useful tools: + +- Node.js (customize version with `CC_NODE_VERSION`) +- Python +- Ruby +- Development tools (`jq`, `tmux`) +- Local Redis server (`redis-server`) + +### Path Routing Capabilities + +Thanks to the [open source load-balancer Sōzu](https://github.com/sozu-proxy/sozu/), you can host multiple applications under one domain: + +```bash +mydomain.com/blog → Blog application +mydomain.com/api → API application +``` + +Each application maintains: + +- Independent scaling +- Separate logs +- Individual environment variables +- Automatic TLS certificate generation + + +[Path routing documentation](/developers/doc/administrate/domain-names/#path-routing) + +### Create Custom Add-ons + +Distribute your services through Clever Cloud: + +1. Create an add-on provider +2. Make it available in your organisations +3. Optionally list it in the Clever Cloud Marketplace + +[Marketplace API documentation](/developers/doc/marketplace/) + +### Domain Management + +The `cleverapps.io` domain system offers: + +- Automatic `app_id.cleverapps.io` domains for new applications +- Custom subdomain creation +- Perfect for testing and staging environments + +Remove these domains when moving to production with your custom domain. + + +### API-First Platform + +Clever Cloud's entire platform runs on its public API: + +- Console interface +- Clever Tools +- SDK features +- Custom integrations + +This ensures API reliability and continuous improvement. + +[API documentation](/developers/api/) + +### Web Components + +Build custom Clever Cloud interfaces using : + +- Open source Web Components +- Standard-based architecture +- Accessibility-focused design + +Available through: + +- [npm package](https://www.npmjs.com/package/@clevercloud/components) +- [Public repository](https://github.com/CleverCloud/clever-components/) +- [Storybook documentation](https://www.clever.cloud/developers/clever-components/) + +### Custom Solutions + +Clever Cloud offers: + +- Public cloud hosting +- On-premise deployments +- Edge computing solutions +- Custom service integration +- Dedicated support + +[Contact the sales team](https://www.clever-cloud.com/contact/) to discuss your specific needs. diff --git a/content/doc/billing/_index.md b/content/doc/billing/_index.md new file mode 100644 index 000000000..a8d98d6d6 --- /dev/null +++ b/content/doc/billing/_index.md @@ -0,0 +1,25 @@ +--- +weight: 12 +type: docs +title: Billing +description: Learn best practices on Clever Cloud +tags: +- getting-started +keywords: +- quickstart +aliases: +- /billing +- /doc/administrate/billing +- /doc/administrate/log-management/billing +- /doc/billing +- /doc/doc/billing +- /doc/quickstart +comments: false +--- + +{{< cards >}} + {{< card link="/developers/doc/billing/analytics-consumption" title="Analytics consumption" icon="chart-bar" >}} + {{< card link="/developers/doc/billing/payments-invoicing" title="Payments & invoicing" icon="banknotes" >}} + {{< card link="https://www.clever-cloud.com/pricing/" title="Pricing" icon="currency-euro" >}} + {{< card link="/developers/doc/billing/unified-invoices" title="Unified invoicing" icon="user-group" >}} +{{< /cards >}} diff --git a/content/doc/billing/analytics-consumption.md b/content/doc/billing/analytics-consumption.md new file mode 100644 index 000000000..3ed8eea38 --- /dev/null +++ b/content/doc/billing/analytics-consumption.md @@ -0,0 +1,35 @@ +--- +type: docs +title: Analytics and consumption +description: How credit consumption and add-on billing works +tags: +- billing +keywords: +- billing +- consumption +aliases: +- /doc/admin-console/analytics-consumption +--- + +Clever Cloud's billing is based on several types of products: applications (Java, PHP, Jenkins, etc.), managed services (MySQL, PostgreSQL, etc.), storage services (via FTP with FS Buckets, or via the S3 protocol with Cellar) and other services (Heptapod, Pulsar, etc). + +## Billing calculation + +The calculation of consumption is based on the second of running. Once your monthly bill has been generated, you can refer to it to find out by service: + +* the size of the instances used +* the execution time +* the unit price per second +* the total monthly amount + +To find your consumption history, it is visible in the **Metrics in Grafana** service via a specific Grafana dashboard. This is called the **Uptime Service**. + +![Grafana dashboard](/images/analytics.png "The Uptime Service dashboard in Grafana") + +## Upscale & Downscale Impacts + +If the auto-scalability option is activated, it is possible that the size of the instances of your applications will vary during the month. This variation will not be systematically identical from one month to the next, which explains the variation in the amount of your bills. + +Most of our cutomers apps running with auto-scaling enabled have less than a ±5% variation between consecutive months in their invoice. Especially because upscale events don't last for long before a downscale occurs, usually after 2-3 hours. High traffic is most of the time temporary (a newsletter sendings, a TV show appearance, Techcrunch effect etc.). + +In the end, auto-scaling is pretty useful to avoid applications slowdown without a significant impact on your billing. diff --git a/content/doc/billing/payments-invoicing.md b/content/doc/billing/payments-invoicing.md new file mode 100644 index 000000000..9ae6f76d7 --- /dev/null +++ b/content/doc/billing/payments-invoicing.md @@ -0,0 +1,71 @@ +--- +type: docs +title: Payments & invoicing +description: Managing invoices and payment on Clever Cloud +tags: +- billing +keywords: +- invoices +- tax +- pricing +- billing +- payment +- stripe +- sepa +aliases: +- /doc/admin-console/invoices-payments +--- + +## Make a payment + +In the sidebar of the organisation section, there are three alternatives to buy credit for your applications: + +* Credit card (powered by Stripe) +* Paypal +* Bank transfer: we accept international bank transfers. This option will generate a reference that you will have to add to your bank transfert, as a note. +* SEPA Direct Debit: we support payment via SEPA debit. More information in the [SEPA Direct Debit section](#sepa-direct-debit) + +## Invoices + +Invoices are available in the *Invoices* tab in the sidebar of the organisation section. Once paid, invoices are moved to the "Paid invoice" table. + +### Receive invoices + +You can change the billing email for an organisation in *Information > Billing details > Billing email*. + +Also an organisation member with the accountant role can receive invoices as described in the organisation [roles]({{< ref "/doc/account/organisations/#roles-and-privileges" >}}). + +## Change Billing Information + +* for personal account: available in *Profile > Informations* + +* for organisation: available in *Information > Billing details* + +![Clever Cloud Console: "Information menu from the organisation"](/images/billing-infos.png "organisation information") + +## SEPA Direct Debit + +When adding your IBAN in the admin console, you accept the following SEPA Direct Debit +Mandate: + +> By providing your IBAN or confirming this payment, you are authorizing Clever Cloud and +> Stripe, our payment service provider, to send instructions to your bank to debit your +> account and your bank to debit your account in accordance with those instructions. +> You also agree to be debited in the future 2 days after receiving a debit notification. +> +> You are entitled to a refund from your bank under the terms and conditions of your +> agreement with your bank. A refund must be claimed within 8 weeks starting from the date +> on which your account was debited. +> +> Debit instructions are issued in the following cases: +> +> * when you confirm an invoice payment; +> * starting 5 days after issuing the invoice, would you set your IBAN as default payment method; +> * would the first debit fail, new attempts will be made every day up to 15 days after invoice issuance and every 5 days after that. +> Your rights are explained in a statement that you can obtain from your bank. + +### About invoices issuance and notifications + +As explained in the [Monthly Invoice documentation](/developers/doc/billing/unified-invoices#monthly-invoice), Clever Cloud issues an invoice at the beginning of every month. +This invoice is sent to both primary and secondary email address of any Admin or Accountant within the organisation. +In accordance with SEPA rules and the mandate your agreed to, this email also notifies you that a debit will be attempted 5 days after invoice issuance. diff --git a/content/doc/billing/unified-invoices.md b/content/doc/billing/unified-invoices.md new file mode 100644 index 000000000..12946ad9e --- /dev/null +++ b/content/doc/billing/unified-invoices.md @@ -0,0 +1,95 @@ +--- +type: docs +title: Unified Invoicing +description: Each month, for each organisation, a single invoice is generated, including the whole activity (credits, add-on etc) +tags: +- billing +keywords: +- invoice +- invoicing +- billing +- bill +- payment +- payments +aliases: +- /clever-cloud-overview/unified-invoicing +- /doc/clever-cloud-overview/unified-invoicing +--- + +Each month, for each organisation, a single invoice is generated, including the whole activity (credits, add-on etc). + +## Monthly invoice + +At the beginning of each month, a new invoice is generated for each organisation. It details the consumption of services, and the provisioning of your account for the coming month. + +The invoice is made up of three distinct sections: + +* A summary of the total amount to be paid for the current month +* An exploded view of the invoice calculation, including credits used, coupons, provision for the coming month etc. +* and full details of the operating time of each service, of each service invoiced, of storage used etc. + +To find your invoices, go to your organisation and click on **Invoices** to see a list of them and their payment status: + +![List of invoices from the console](/images/invoice-list.png "The list of invoices") + +### First section + +This first section shows the fee for the use of Clever Cloud over a month. Any discounts are explained here. + +![First section of the invoice](/images/invoice-amount-to-pay.png "The first section of the invoice") + +### Second section + +This part details line by line the evolution of your credit with: + +* The balance of free credits (a) +* Pre-paid credits (b) +* The use of free credits (c) +* Expired credits (d) +* Use of your prepaid credits (e) +* Estimated consumption for the next period (f) +* Invoiced credits pending payment (g) +* Amount of prepaid credits to be topped up (h) + +The **amount of prepaid credits to be topped up** and the **new balance of credits after settlement** are explained via calculations of the different types of credits and their use over time. + +![Credit balance on invoice](/images/invoice-credits-balance.png "The second section of the invoice") + +### Third section + +This section of the invoice details the usage of each cloud service. + +![Runtime section on invoice](/images/invoice-runtime-detail.png "The third section of the invoice") + +## Managed Services + +While applications are billed on a per second basis, this may be different for managed services. +From a billing point of view there are X categories + +* time-based billing (per second) +* resource consumption billing + +For example, dedicated databases are charged by the second, just like applications. +In contrast, services such as Cellar object storage or Pulsar are charged according to the volume of data stored and the volume of outgoing traffic. + +## Specific invoices + +For specific services performed by the support teams, specific invoices can be created by the administration or support teams. These invoices usually indicate a specific service act. + +## Management of payment methods + +For each organisation it is possible to register one or more payment methods ([see list of payment methods here](/developers/doc/billing/payments-invoicing/)). Invoices will be automatically paid with the default payment method a few days after their generation. For the one-off invoices mentioned above, the invoice must be paid manually, via the invoice page via the "Pay" button. + +## Payments and reminders + +As long as an invoice remains *pending*, we'll perform these actions on specific days: + +* Try to issue an automatic payment using your favorite payment method everyday from the + 5th to the 15th day after issuing the invoice, then every 5 days after that. +* Send a reminder via email every 5 days if the payment remains unsuccessful. +* Shutdown of your services everyday starting day 31 after invoice issue. + +This schedule can adapt according to your company's payment delays. +Please reach out to us via the support to ensure the best experience. + +Support and access to your account will remain available to regularise non-payment situations. diff --git a/content/doc/ci-cd/_index.md b/content/doc/ci-cd/_index.md new file mode 100644 index 000000000..a3fbe8b4a --- /dev/null +++ b/content/doc/ci-cd/_index.md @@ -0,0 +1,21 @@ +--- +weight: 9 +title: 'CI/CD' +date: 2024-03-15T13:14:53+01:00 +description: Deploy to Clever Cloud from GitLab or GitHub +draft: false +type: docs +aliases: +- /ci-cd +- /doc/administrate/ci-cd +--- + +{{< hextra/hero-subtitle >}} + There are several ways to automate your workflow when deploying your application to Clever Cloud from either GitHub or GitLab. This section explains how to set up you CI/CD from both platforms. +{{< /hextra/hero-subtitle >}} + +{{< cards >}} + {{< card link="/developers/doc/ci-cd/github" title="Deploy from GitHub" subtitle="Deploy directly from GitHub and automate review apps." icon="github" >}} + {{< card link="/developers/doc/ci-cd/gitlab" title="Deploy from GitLab" subtitle="Deploy directly from GitLab and automate review apps." icon="gitlab" >}} + {{< card link="/developers/doc/ci-cd/custom-scripts" title="Write your own CI/CD" subtitle="Write your own scripts to deploy to Clever Cloud and automate tasks." icon="command-line" >}} +{{< /cards >}} diff --git a/content/doc/ci-cd/custom-scripts.md b/content/doc/ci-cd/custom-scripts.md new file mode 100644 index 000000000..59fa9b925 --- /dev/null +++ b/content/doc/ci-cd/custom-scripts.md @@ -0,0 +1,59 @@ +--- +type: docs +title: Write your own CI/CD +description: Write your own CI/CD to deploy to Clever Cloud from GitHub or GitLab +--- + +{{< hextra/hero-subtitle >}} + There are several ways to automate your workflow when deploying your application to Clever Cloud from either GitHub or GitLab. This page explains how to write your custom CI/CD from both platforms. +{{< /hextra/hero-subtitle >}} + +## Use Clever Tools + +You can write your own pipeline to deploy from either GitHub or GitLab. Use [Clever Cloud CLI](https://github.com/CleverCloud/clever-tools) with either Docker or Node image. Place the following snippets at the top of your `.gitlab-ci.yml` file: + +{{< tabs items="Docker image, Node image" >}} + + {{< tab >}}**Docker image**: + + ```yaml + variables: + GIT_DEPTH: "0" # Unshallow the repository by default + +image: + name: clevercloud/clever-tools:latest + entrypoint: [""] + ``` + + {{< /tab >}} + + {{< tab >}}**Node image**: + + ```yaml + variables: + GIT_DEPTH: 0 # Unshallow the repository by default + +before_script: # Download clever-tools before any script executes + - CC_VERSION=latest + - curl -s -O https://clever-tools.clever-cloud.com/releases/${CC_VERSION}/clever-tools-${CC_VERSION}_linux.tar.gz + - tar -xvf clever-tools-${CC_VERSION}_linux.tar.gz + - PATH=${PATH}:$(pwd)/clever-tools-${CC_VERSION}_linux + ``` + + {{< /tab >}} + +{{< /tabs >}} + +{{< callout type="warning" >}} + Using `before_script` in your GitLab pipeline affects your other scripts as well. Consider including it **in a separate job** if you run other test scripts unrelated to Clever Cloud deployments in your pipeline. +{{< /callout >}} + +{{% content "ci-cd-configuration" %}} + +## 🎓 Go further + +{{< cards >}} + {{< card link="https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables" title="GitHub variables" subtitle="List of GitHub default CI/CD variables" icon="github" >}} + {{< card link="https://docs.gitlab.com/ee/ci/variables/predefined_variables.html" title="GitLab variables" subtitle="List of GitLab predefined variables" icon="gitlab" >}} + {{< card link="/developers/doc/cli" title="Clever Tools CLI" subtitle="Deploy and manage your applications and dependencies from your terminal." icon="command-line" >}} +{{< /cards >}} diff --git a/content/doc/ci-cd/github.md b/content/doc/ci-cd/github.md new file mode 100644 index 000000000..0693921dc --- /dev/null +++ b/content/doc/ci-cd/github.md @@ -0,0 +1,81 @@ +--- +type: docs +title: Deploy from GitHub +description: How to set up you CI/CD from GitHub to deploy to Clever Cloud +--- + +{{< hextra/hero-subtitle >}} + How to set up you CI/CD from GitHub directly from Clever Cloud, and how to deploy review apps. +{{< /hextra/hero-subtitle >}} + +## Use the GitHub integration + +Clever Cloud provides a GitHub integration to deploy any repository hosted on GitHub to Clever Cloud. You can deploy the same repository to multiple Clever Cloud applications from different branches. Select the appropriate branch in you application menu, in **Information** > **Application edition** > **Used GitHub branch for deployment**. + +![GitHub branch deployment](/images/github-branches.png) + +Clever Cloud asks for permission to access your GitHub repositories. Accept the permissions to allow the deployment. You can deploy both public or private repositories. + +### Deploy review apps from a PR on GitHub + +You can automate deployments for review apps when a Pull Request opens on your GitHub repository by using Clever Cloud [GitHub Action](https://github.com/marketplace/actions/clever-cloud-review-app-on-prs). This action uses [Clever Tools](/developers/doc/cli) to deploy a new app from the branch the Pull Request is based on and post a comment with the URL of the review app. The action redeploys the app on every new commit and deletes it when the Pull Request is closed (merged or not). + +#### How to use the Review App GitHub Action + +Two things are necessary to use the action: + +1. **A workflow file to run the action**. For example, `.github/workflow/review-app.yml`. At the top of this file, define the event trigger for running the action: + +```yaml +on: + pull_request_target: + types: [opened, closed, synchronize, reopened] + branches: [ main ] +``` +Then, use the action and define the mandatory input: + +```yaml +- name: Create review app + uses: CleverCloud/clever-cloud-review-app@latest + env: + CLEVER_SECRET: ${{ secrets.CLEVER_SECRET }} + CLEVER_TOKEN: ${{ secrets.CLEVER_TOKEN }} + ORGA_ID: ${{ secrets.ORGA_ID }} + with: + type: '' +``` + +2. **Inject the environment variables from your repository:** From your GitHub repository go to **Settings** > **Secrets and variables**. Inject them both in "Environment secrets" and "Repository secrets" to allow deployments from forked repositories. Then add them with an `GH_` prefix in your workflow file (this will prevent the injection of the GitHub runner variables in your app). Finally, enable the injection with `set-env: true`: + +```yaml +name: Create review app + uses: CleverCloud/clever-cloud-review-app@latest + env: + CLEVER_SECRET: ${{ secrets.CLEVER_SECRET }} + CLEVER_TOKEN: ${{ secrets.CLEVER_TOKEN }} + ORGA_ID: ${{ secrets.ORGA_ID }} + GH_CC_RUN_SUCCEEDED_HOOK: ${{ secrets.CC_RUN_SUCCEEDED_HOOK }} # This environment variable will be set on Clever Cloud + with: + type: '' + set-env: true # Enables the command to set en vars on Clever Cloud +``` + + +{{% content "ci-cd-configuration" %}} + +Full instructions are available on the [Action project](https://github.com/CleverCloud/clever-cloud-review-app). + +#### Review App workflow example + +To see a Review App workflow already in use, see [this workflow on GitHub](https://github.com/CleverCloud/clever-cloud-review-app/blob/main/.github/workflows/main.yml). + +## Troubleshooting + +If you encounter troubles or bugs using the GitHub Action, feel free to open an issue [on the repository](https://github.com/CleverCloud/clever-cloud-review-app/issues/new). + +## 🎓 Go further + +{{< cards >}} + {{< card link="https://docs.github.com/en/actions" title="GitHub Actions documentation" subtitle="Find help in GitHub Actions documentation" icon="github" >}} + {{< card link="/developers/doc/cli" title="Clever Tools CLI" subtitle="Deploy and manage your applications and dependencies from your terminal." icon="command-line" >}} +{{< /cards >}} diff --git a/content/doc/ci-cd/gitlab.md b/content/doc/ci-cd/gitlab.md new file mode 100644 index 000000000..a838f662c --- /dev/null +++ b/content/doc/ci-cd/gitlab.md @@ -0,0 +1,83 @@ +--- +type: docs +title: Deploy from GitLab +description: How to set up you CI/CD from GitLab to deploy to Clever Cloud +aliases: +- /ci-cd/gitlab +--- + +{{< hextra/hero-subtitle >}} +How to set up you CI/CD from GitLab to deploy to Clever Cloud. +{{< /hextra/hero-subtitle >}} + +## Use the Components Catalog + +GitLab provides its own way of deploying applications to any host provider. The CI/CD system differs from GitHub Actions, but Clever Cloud has already worked on ways to ease the process. Find components in [GitLab Components Catalog](https://gitlab.com/explore/catalog/CleverCloud/clever-cloud-pipeline) to build a modular pipeline for your project. + +To use a component, add this snippet to your `.gitlab-ci.yml` file: + +```yaml +include: + - component: $CI_SERVER_HOST//@~latest +``` + +{{% content "ci-cd-configuration" %}} + +### GitLab pipeline example + +For example, to deploy any commit on your production app, use: + +```yaml +include: + - component: $CI_SERVER_HOST//deploy-to-prod@~latest +``` + +This assumes you have a running app on Clever Cloud. Any commit on your default branch (`main`, `master` or other name) triggers a deployment for this app. [Inject the following variables in your GitLab repository settings](https://docs.gitlab.com/ee/ci/variables/index.html#for-a-project): + +- `APP_ID`: Find it at the top right in [Clever Cloud Console](https://console.clever-cloud.com), in your application tab. +- `CLEVER_TOKEN` and `CLEVER_SECRET` + +### `` configuration + +In the project you want to deploy, replace `` with the actual path of the components, otherwise this variable fetches your project current path (which doesn't host the CI/CD components). Depending on your platform, path can be different. + +#### On gitlab.com + +```yaml +- component: $CI_SERVER_HOST/CleverCloud/clever-cloud-pipeline/deploy-to-prod@~latest +``` + +#### On Heptapod + +```yaml +- component: $CI_SERVER_HOST/pipelines/clever-cloud-pipeline/deploy-to-prod@~latest +``` + +#### On your self-hosted instance + +```yaml +- component: $CI_SERVER_HOST///deploy-to-prod@~latest +``` + +### Deploy from a self-hosted GitLab instance + +You can use pipeline components to deploy from a self-hosted GitLab instance, by including it as a project and mirroring the pipeline repository. Follow [GitLab documentation](https://docs.gitlab.com/ee/ci/components/#use-a-gitlabcom-component-in-a-self-managed-instance) to get full instructions. + +#### Deploy directly from Heptapod + +The self-hosted GitLab service on Clever Cloud with [Heptapod](/developers/doc/addons/heptapod) already hosts the components, you don't need to do any set up like you would in a self-hosted instance: + +1. Create a `.gitlab-ci.yml` at the root of your repository with [the component to use](/developers/doc/ci-cd/gitlab/#use-the-components-catalog) +2. Add [the variables](/developers/doc/ci-cd/gitlab/#mandatory-configuration) to your repository settings +3. Run the pipeline + +## Troubleshooting + +If you encounter troubles or bugs using the GitLab component, feel free to open an issue [on the repository](https://gitlab.com/CleverCloud/clever-cloud-pipeline/-/issues): + +## 🎓 Go further + +{{< cards >}} + {{< card link="https://docs.gitlab.com/ee/ci/components" title="GitLab Components" subtitle="Learn how to use GitLab components" icon="gitlab" >}} + {{< card link="/developers/doc/cli" title="Clever Tools CLI" subtitle="Deploy and manage your applications and dependencies from your terminal." icon="command-line" >}} +{{< /cards >}} diff --git a/content/doc/cli/_index.md b/content/doc/cli/_index.md new file mode 100644 index 000000000..ff6d51d8f --- /dev/null +++ b/content/doc/cli/_index.md @@ -0,0 +1,233 @@ +--- +type: "docs" +weight: 8 +title: Clever Tools (CLI) +description: Use Clever Cloud CLI, Clever Tools +aliases: +- /clever-tools/getting_started +- /cli +- /doc/administrate/clever-tools/getting_started +- /doc/administrate/cli +- /doc/clever-cloud-cli +- /doc/clever-tools/getting_started +- /doc/clever-tools/manage +- /doc/cli +- /doc/CLI +- /doc/cli/getting_started +- /doc/getting-started/cli +- /doc/quickstartcli +- /doc/reference/clever-tools/getting_started +- /doc/reference/clever-tools +- /getting-started/cli +--- + +Clever Tools is the command line interface (CLI) of Clever Cloud. You can use it to create and manage multiple services of the platform as applications, databases or storage add-ons. It also provides easy authenticated access to Clever Cloud public APIv2 and APIv4 through the [`clever curl` command](#curl). It's an [easy to set up](install) multiplatform and open source tool, based on Node.js. + +You can contribute to it through [issue](https://github.com/CleverCloud/clever-tools/issues) or [pull requests](https://github.com/CleverCloud/clever-tools/pulls). Ask for new features, enhancements or help us to provide them to our community. + +- [How to install Clever Tools](install) +- [Create a Clever Cloud account](https://console.clever-cloud.com) + +You'll find below the first commands to know to connect Clever Tools to your account, get its information and manage some options. Others are developed in dedicated pages: + +{{< cards >}} + {{< card link="/developers/doc/cli/install" title="Install" icon="arrow-down-tray" >}} + {{< card link="/developers/doc/cli/addons" title="Create and manage add-ons" icon= "wrench-screwdriver" >}} + {{< card link="/developers/doc/cli/applications" title="Create and manage applications" icon="code-bracket" >}} + {{< card link="/developers/doc/cli/kv-stores" title="Manage KV stores" icon="server-stack" >}} + {{< card link="/developers/doc/cli/logs-drains" title="Manage logs, drains" icon="command-line" >}} + {{< card link="/developers/doc/cli/network-groups" title="Network Groups" icon="tcp-ip-service" >}} + {{< card link="/developers/doc/cli/notifications-webhooks" title="Notifications, Web hooks" icon="bell" >}} + {{< card link="/developers/doc/cli/operators" title="Operators (Managed services)" icon="document-check" >}} + {{< card link="/developers/doc/cli/services-depedencies" title="Services dependencies" icon="endpoints" >}} +{{< /cards >}} + +## basic commands + +To show Clever tools available commands, use: + +``` +clever +clever help +``` + +For each of them, you can add these parameters: + +``` +[--help, -?] Display help about this program (default: false) +[--version, -V] Display the version of this program (default: false) +[--color] Choose whether to print colors or not. You can also use --no-color (default: true) +[--update-notifier] Choose whether to use update notifier or not. You can also use --no-update-notifier (default: true) +[--verbose, -v] Verbose output (default: false) +``` + +> [!TIP] +> For commands returning a list of items, you can use `--format json` or `-F json` to get a JSON output. + +## features + +Some features are available as experimental, before they're completely ready for prime time. They usually work well, but this testing phase allows us to get feedbacks, refine some details, documentation, and break things between two releases. + +Experimental features can be (de)activated on-demand. To list them, use: + +``` +clever features +``` + +To (de)activate an experimental feature, use: + +``` +clever features enable theFeature +clever features disable theFeature +``` + +To get information about how to use an experimental feature, use: + +``` +clever features info theFeature +``` + +## diag | version + +To check the current version or get information about your setup, use: + +``` +clever version +clever diag +clever diag --format json +``` + +> [!NOTE] +> Such information are nice to provide in your issues report or when you contact Clever Cloud technical support team. + +## login | logout + +To connect to your Clever Cloud account, use: + +``` +clever login +``` + +It will open your default browser and start an Open Authorization ([OAuth](https://en.wikipedia.org/wiki/OAuth)) process to get a `token` and `secret` pair added in your account if it succeeds. You can manage it from the [Console](https://console.clever-cloud.com/users/me/oauth-tokens). Clever Tools will automatically store these `token` and `secret` values in a hidden `clever-tools.json` config file in the current local user home folder. + +If you already know them, you can use: + +``` +clever login --secret SECRET --token TOKEN +``` + +> [!TIP] +> If environment variables `CLEVER_SECRET` and `CLEVER_TOKEN` are set, Clever Tools will use them, `login` is not needed. + +To log out, delete this file or use: + +``` +clever logout +``` + +## profile + +To get information about the current logged-in user (ID, name, email, 2FA activation, etc.), use: + +``` +clever profile +clever profile open +clever profile -F json +``` + +## emails + +To list primary email and secondary emails associated with your Clever Cloud account, you can use: + +``` +clever emails +``` + +To open the email management page in your browser, use: + +``` +clever emails open +``` + +To add a secondary email, use: + +``` +clever emails add email@example.com +``` + +To set a secondary email as primary, use: + +``` +clever emails primary email@example.com +``` + +To remove one or all secondary emails, use: + +``` +clever emails remove email@example.com +clever emails remove-all +clever emails remove-all --yes +``` + +## ssh-keys + +To list public SSH keys associated with your Clever Cloud account, you can use: + +``` +clever ssh-keys +``` + +To open the public SSH keys management page in your browser, use: + +``` +clever ssh-keys open +``` + +To add a new public SSH key, use: + +``` +clever ssh-keys add myPublicKey ~/.ssh/id_ecdsa.pub +``` + +To remove one or all public SSH keys, use: + +``` +clever ssh-keys remove myPublicKey +clever ssh-keys remove-all +clever ssh-keys remove-all --yes +``` + +## curl + +To use our public API, you need to be authenticated for most endpoints. If you're logged in through Clever Tools, there is a simple way to make any request you want: `clever curl`. It's `curl`, but in an authenticated context for Clever Cloud API. + +- [Clever Cloud public APIv2 documentation](/developers/api/v2/) +- [Clever Cloud public APIv4 documentation](/developers/api/v4/) + +## tokens + +You can query [Clever Cloud public API](/developers/api/) with a bearer token thanks to the Auth Bridge. To create a token, use: + +``` +clever tokens create myTokenName +clever tokens create myTokenName --expiration 2w --format json +``` + +Once created, you can use it replacing the API endpoint with `https://api-bridge.clever-cloud.com`. For example: + +``` +curl https://api-bridge.clever-cloud.com/v2/self -H "Authorization: Bearer myToken" +``` + +To list all your tokens, use: + +``` +clever tokens +clever tokens -F json +``` + +To revoke a token, use: + +``` +clever tokens revoke myTokenId +``` diff --git a/content/doc/cli/addons.md b/content/doc/cli/addons.md new file mode 100644 index 000000000..c905769da --- /dev/null +++ b/content/doc/cli/addons.md @@ -0,0 +1,105 @@ +--- +type: "docs" +weight: 2 +title: Add-ons, Backups +description: Create and manage Clever Cloud add-ons, backups with Clever Tools +--- + +Add-ons on Clever Cloud are databases, storage services, tools or third party services you can enable through `clever addon provider`. For each of the following commands, you can target a specific user/organisation: + +``` +[--org, -o, --owner] Organisation ID (or name, if unambiguous) +``` + +## providers + +To use add-ons, you need to identify the corresponding provider. To get information about them (plans, regions, versions), use: + +``` +clever addon providers +clever addon providers show PROVIDER_NAME +``` + +## create | rename | delete + +To create an add-on, select a provider and choose a name: + +``` +clever addon create PROVIDER ADDON_NAME +``` + +You can set `plan`, `region`, `version`, `option` and directly `link` an add-on to an application through these parameters: + +``` +[--link, -l] ALIAS Link the created add-on to the app with the specified alias +[--yes, -y] Skip confirmation even if the add-on is not free (default: false) +[--plan, -p] PLAN Add-on plan, depends on the provider +[--region, -r] REGION Region to provision the add-on in, depends on the provider (default: par) +[--addon-version] ADDON-VERSION The version to use for the add-on +[--option] OPTION Option to enable for the add-on. Multiple --option argument can be passed to enable multiple options +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +> [!NOTE] +> If no plan is set, we use the cheapest by default + +To rename an add-on, use: + +``` +clever addon rename ADDON_ID_OR_NAME ADDON_NEW_NAME +``` + +To delete an add-on, use: + +``` +clever addon delete [--yes, -y] ADDON_ID_OR_NAME +``` + +## env + +Each add-on comes with environment variables. To get them, use: + +``` +clever addon env [--format, -F] FORMAT ADDON_ID +``` + +> [!NOTE] +> Available formats are: `human` (default), `json` and `shell` + +For some add-ons, an interface URL, default credentials or other instructions can be displayed after creation. + +If you're testing [Materia KV](/developers/doc/addons/materia-kv/), our next generation of serverless distributed database, synchronously-replicated, compatible with Redis® protocol, you can create an add-on and immediately use it: + +``` +clever addon create kv ADDON_NAME +source <(clever addon env ADDON_ID --format shell) +redis-cli -h $KV_HOST -p $KV_PORT --tls +``` + +> [!TIP] +> If you use the Fish shell, you can use the following command to set the environment variables: +> ``` +> clever addon env ADDON_ID --format shell | source +> ``` + +## database backups + +Databases are backup every day, with last 7 days of backups available to download. You can list them, available formats are: `human` (default) or `json`: + +``` +clever database backups DATABASE-ID [--format, -F] FORMAT +``` + +To download one of them, use: + +``` +clever database backups download [--output, --out] OUTPUT_FILE DATABASE_ID BACKUP_ID +``` + +This command is still under development and will evolve over time. To get information about backups and download them, you can use our API and `clever curl`. For example: + +``` +clever curl -X GET https://api.clever-cloud.com/v2/backups// +``` + +This will list available backups for the database, with creation and delete time. The answer will also contain a direct HTTPS `download_url`. diff --git a/content/doc/cli/applications/_index.md b/content/doc/cli/applications/_index.md new file mode 100644 index 000000000..5f04f90e5 --- /dev/null +++ b/content/doc/cli/applications/_index.md @@ -0,0 +1,137 @@ +--- +type: docs +weight: 3 +title: Applications +description: Create and manage Clever Cloud applications with Clever Tools +aliases: +- /clever-tools/create +- /doc/administrate/clever-tools/create +- /doc/clever-tools/create +- /doc/cli/create +--- + +## create + +You can create a new application on Clever Cloud, linked to your local folder. Only its `type` is required, it should be one of: `docker`, `elixir`, `frankenphp`, `go`, `gradle`, `haskell`, `jar`, `linux`, `maven`, `meteor`, `node`, `php`, `play1`, `play2`, `python`, `ruby`, `rust`, `sbt`, `static`, `static-apache`, `v` or `war`. Result can be printed in `human` or `json` format. + +``` +clever create -t TYPE APP_NAME +clever create -t TYPE --format json +``` + +> [!NOTE] +> Application name is optional. The current directory name is used if not specified. + +You can also use one of the following optional parameters: + +#### Tasks + +``` +[--task, -T] COMMAND +``` + +You can declare a new application as a Clever Task. Once deployed, a Task executes its command and then stops. This value can be set by an (optional) parameter or later through `clever env set CC_RUN_COMMAND command`. + +You can execute a Task whenever needed through a `clever restart` or modify it and `clever deploy` a new revision. You'll only be billed for the build/execution time, per second. + +> [!NOTE] +> Except its lifecycle, a Clever Task is identical to an application and accepts the same environment variables. + +#### GitHub repositories + +``` +--github owner/repo +``` + +If your Clever Cloud account is linked to a GitHub account, you can deploy any of your GitHub repositories as an application thanks to this parameter. + +#### Other optional parameters + +You can ask to deploy your application in a specific organisation/user account, region, with an alias different from its name: + +``` +[--org, -o, --owner] ID/NAME +[--alias, -a] ALIAS +[--region, -r] ZONE +[--format, -F] FORMAT +``` + +Default region is our Paris datacenters (`par`), but it can be: + +- `par` (Paris, [Clever Cloud](https://www.clever-cloud.com/infrastructure/)) +- `parhds` (Paris, HDS infrastructure, [Clever Cloud](https://www.clever-cloud.com/infrastructure/)) +- `scw` (Paris, [Scaleway DC5](https://www.clever-cloud.com/blog/press/2023/01/17/clever-cloud-and-scaleway-join-forces-to-unveil-a-sovereign-european-paas-offering/)) +- `grahds` (Gravelines, HDS infrastructure, OVHcloud) +- `ldn` (London, Ionos) +- `mtl` (Montreal, OVHcloud) +- `rbx` (Roubaix, OVHcloud) +- `rbxhds` (Roubaix, HDS infrastructure, OVHcloud) +- `sgp` (Singapore, OVHcloud) +- `syd` (Sydney, OVHcloud) +- `wsw` (Warsaw, OVHcloud) + +> [!NOTE] To benefit from certified hosting for health data, you need to deploy in an HDS zone and to sign up to a specific contract +> This begins by having [an initial discussion with Clever Cloud team](https://www.clever-cloud.com/fr/hebergement-donnees-de-sante/contact-hds/) + +After the application creation, you can ask for a `json` formatted report instead of an `human` sentence: + +``` +[--format, -F] FORMAT +``` + +## (un)link and make-default + +If an application already exists in your Clever Cloud account, you can link it to any local directory to control it easily. You can even link several applications to a single folder, each one with a different name and/or alias. This is done through the `.clever.json` file. + +``` +clever link APP_ID_OR_NAME [--alias, -a] ALIAS [--org, -o, --owner] ORG_ID_OR_NAME +``` + +If multiple applications are linked, you can define one as default with it alias: + +``` +clever make-default ALIAS +``` + +To unlink an application: + +``` +clever unlink ALIAS +``` + +## applications + +You can list linked applications of a folder, you'll get : ID, alias and deployment URL. + +``` +clever applications +``` + +If you only need to get aliases or the result in the JSON format: + +``` +[--only-aliases] List only application aliases (default: false) +[--json, -j] Show result in JSON format (default: false) +``` + +## list + +To list all applications across all organisations you have access to, you can use: + +``` +clever applications list -F json +clever applications list --org ORG_ID_OR_NAME +``` + +## delete + +To delete an application and unlink it from the current folder you only need to: + +``` +clever delete +clever delete --alias ALIAS +clever delete --app APP_ID_OR_NAME +``` + +> [!TIP] +> You can skip confirmation adding the `--yes` or `-y` parameter. diff --git a/content/doc/cli/applications/configuration.md b/content/doc/cli/applications/configuration.md new file mode 100644 index 000000000..b1a887487 --- /dev/null +++ b/content/doc/cli/applications/configuration.md @@ -0,0 +1,167 @@ +--- +type: docs +title: Configuration +description: Configure Clever Cloud applications with Clever Tools +aliases: +- /clever-tools/tcp-redirections +- /doc/administrate/clever-tools/configure +- /doc/clever-tools/configure +- /doc/clever-tools/tcp-redirections +- /doc/cli/applications/deployment-lifecycle/applications-config +- /doc/cli/configure +--- + +A Clever Cloud application can easily be configured once created, through following commands. Each can target a specific application, adding `--app APP_ID_OR_NAME` or a local alias (`--alias`, `-a`). + +## config + +Each application has options you can get/set: `cancel-on-push`, `description`, `force-https`, `name`, `sticky-sessions`, `task`, `zero-downtime`. + +``` +clever config get parameter +clever config set parameter value +``` + +To update multiple configuration parameters at a time, use: + +``` +clever config update --option1 value1 --option2 value2 --option3 value3 +``` + +Available parameters are : + +``` +[--name] Set name +[--description] Set description +[--enable-zero-downtime] Enable zero-downtime (default: false) +[--disable-zero-downtime] Disable zero-downtime (default: false) +[--enable-sticky-sessions] Enable sticky-sessions (default: false) +[--disable-sticky-sessions] Disable sticky-sessions (default: false) +[--enable-cancel-on-push] Enable cancel-on-push (default: false) +[--disable-cancel-on-push] Disable cancel-on-push (default: false) +[--enable-force-https] Enable force-https (default: false) +[--disable-force-https] Disable force-https (default: false) +[--enable-task] Enable task (default: false) +[--disable-task] Disable task (default: false) +``` + +## env + +Environment variables of Clever Cloud applications can easily be modified: + +``` +clever env set VARIABLE VALUE +clever env rm VARIABLE +``` + +You can import local environment variables (comma separated) or from a file through `stdin`. If it's a JSON file, each object should be composed of a `name` and a `value`. + +``` +clever env import-vars VAR_NAME1,VAR_NAME2 +clever env import < .env +cat .env.json | clever env import --json +``` + +To show or export environment variables of an application, use: + +``` +clever env +clever env > .env +``` + +You can also export environment variable in a sourceable format (`export ENV_NAME="VALUE";`): + +``` +clever env --add-export +``` + +## domain + +By default, a Clever Cloud application gets `app_id.cleverapps.io` as fully qualified domain name ([FQDN](https://fr.wikipedia.org/wiki/Fully_qualified_domain_name)). To see it, use: + +``` +clever domain +``` + +To get an overview of domains linked to any of your applications and organisations, use: + +``` +clever domain overview +clever domain overview --filter domain.tld +clever domain overview --filter .tld --format json +``` + +> [!TIP] +> The JSON output of this command plays nicely with tools such as [jless](https://jless.io/) to navigate through your domains. + +To add/remove a domain to an application, use: + +``` +add Add a domain name to a Clever Cloud application +rm Remove a domain name from a Clever Cloud application +``` + +> [!TIP] +> You can set the same domain with multiple apps thanks to [prefix routing](/developers/doc/administrate/domain-names/#prefix-routing). For example, you can add `mydomain.com/app1` domain to an application and `mydomain.com/app2` to another. + +To (un)set [the favourite domain](/developers/doc/administrate/domain-names/#primary-favourite-domain-name), use: + +``` +clever domain favourite set FQDN +clever domain favourite unset FQDN +``` + +To check if the domains of an application are properly configured, use: + +``` +clever domain diag +clever domain diag --format json +clever domain diag --app APP_ID_OR_NAME +``` + +You can only diagnose some domains of the application using a text filter: + +``` +clever domain diag --filter .tld +clever domain diag --filter mydomain.tld +``` + +> [!NOTE] +> Domain diagnosis is not made for applications using a 3rd party CDN or a dedicated load balancer. + +## scale and dedicated build + +You can easily change the number of instances and `flavor` for an application. It can have a different `flavor` used for build phase, to get it done faster. We also provide horizontal and vertical scaling: you can set a minimal/maximal `flavor` and number of instance, then we autoscale depending on incoming load. To change this, use `clever scale` with the following options: + +``` +[--flavor] FLAVOR The scale of your application +[--min-flavor] MINFLAVOR The minimum scale for your application +[--max-flavor] MAXFLAVOR The maximum scale for your application +[--instances] INSTANCES The number of parallels instances +[--min-instances] MININSTANCES The minimum number of parallels instances +[--max-instances] MAXINSTANCES The maximum number of parallels instances +[--build-flavor] BUILDFLAVOR The size of the build instance, or `disabled` +``` + +> [!NOTE] +> Available instances flavors are: `pico`, `nano`, `XS`, `S`, `M`, `L`, `XL`, `2XL`, `3XL` +> +> Due to its low memory (256 MiB) `pico` is not always available. When selected, a dedicated `S` instance is used for build by default. + +## tcp-redirs + +A Clever Cloud application activate TCP redirections in `default` or `cleverapps` namespace: + +``` +clever tcp-redirs add --namespace NAMESPACE +clever tcp-redirs remove --namespace NAMESPACE PORT +``` + +To list enabled TCP redirection, use: + +``` +clever tcp-redirs +clever tcp-redirs --format json +``` + +- [Learn more about TCP redirections](/developers/doc/administrate/tcp-redirections/) diff --git a/content/doc/cli/applications/deployment-lifecycle.md b/content/doc/cli/applications/deployment-lifecycle.md new file mode 100644 index 000000000..d7a218146 --- /dev/null +++ b/content/doc/cli/applications/deployment-lifecycle.md @@ -0,0 +1,115 @@ +--- +type: docs +title: Deploy, Lifecycle +description: Manage your application using the Clever Cloud CLI tool +aliases: +- /doc/administrate/clever-tools/lifecycle +- /doc/administrate/clever-tools/manage +- /doc/administrate/clever-tools/ssh-access +- /doc/clever-tools/lifecycle +- /doc/clever-tools/ssh-access +- /doc/cli/commands/restart +- /doc/cli/lifecycle +- /doc/cli/manage +- /doc/cli/ssh-access +--- + +A Clever Cloud application can easily be deployed and accessed once created, through following commands. Most can target a specific application, adding `--app APP_ID_OR_NAME` or a local alias (`--alias`, `-a`). + +## deploy + +Once changes are committed in your local git repository, you can deploy it: + +``` +clever deploy +``` + +It will `git push` your code on the remote repository of your application on Clever Cloud automatically. You can, of course, use option to `force push` or use specific local branch for example: + +``` +[--branch, -b] BRANCH Branch to push (current branch by default) (default: ) +[--tag, -t] TAG Tag to push (none by default) (default: ) +[--quiet, -q] Don't show logs during deployment (default: false) +[--force, -f] Force deploy even if it's not fast-forwardable (default: false) +[--follow] Continue to follow logs after deployment has ended (default: false) +[--same-commit-policy, -p] POLICY What to do when local and remote commit are identical (error, ignore, restart, rebuild) (default: error) +[--exit-on, -e] STEP Step at which the logs streaming is ended, steps are: deploy-start, deploy-end, never (default: deploy-end) +``` + +> [!TIP] +> You can cancel a deployment with `clever cancel-deploy` command. You can also [configure an application](/developers/doc/cli/applications/configuration/#config) so that a new deployment cancels the current one. + +## console | open + +Once deployed, you can open the application on your default browser or [Clever Cloud Console](https://console.clever-cloud.com): + +``` +clever open +clever console +``` + +## status + +To get application state, options or running/scaling status, use: + +``` +clever status +clever status --format json +``` + +## restart + +Once deployed, an application can be restarted: + +``` +clever restart +``` + +By default, it will use its build cache when available. But you can override it or use other available options: + +``` +[--commit] COMMIT ID Restart the application with a specific commit ID +[--without-cache] Restart the application without using cache (default: false) +[--quiet, -q] Don't show logs during deployment (default: false) +[--follow] Continue to follow logs after deployment has ended (default: false) +[--exit-on, -e] STEP Step at which the logs streaming is ended, steps are: deploy-start, deploy-end, never (default: deploy-end) +``` + +## stop | cancel-deploy + +To stop an application or cancel any ongoing deployment, use: + +``` +clever stop +clever cancel-deploy +``` + +## ssh + +A Clever Cloud application is a running virtual machine you can ssh to, as a user (`bas`). By default, it will use `OpenSSH` configuration, but you can target a specific identity file: + +``` +clever ssh [--identity-file, -i] IDENTITY-FILE +``` + +To ssh a specific application, use: + +``` +clever ssh --app APP_ID_OR_NAME +``` + +## activity + +To get deployment activity, use: + +``` +clever activity +``` + +By default, it will show you last 10 deployments. You can show all or listen to a stream of incoming deployments through options: + +``` +[--follow, -f] Track new deployments in activity list (default: false) +[--show-all] Show all activity (default: false) +[--format, -F] FORMAT Output format (human, json, json-stream) +``` diff --git a/content/doc/cli/install/_index.md b/content/doc/cli/install/_index.md new file mode 100644 index 000000000..044d7700d --- /dev/null +++ b/content/doc/cli/install/_index.md @@ -0,0 +1,188 @@ +--- +type: docs +weight: 1 +title: Install Clever Tools +description: Getting started with Clever Cloud CLI +aliases: +- /cli/install +- /doc/cli-setup +- /doc/install +--- + +Clever Cloud CLI is based on Node.js. We thought it to be easily available on any platform. Thus, you can download Clever Tools as [a npm package](https://www.npmjs.com/package/clever-tools), but also through package managers or as a binary on many systems: + +- [GNU/Linux](#gnulinux) + - [Arch Linux (AUR)](#arch-linux-aur) + - [CentOS/Fedora (.rpm)](#centosfedora-rpm) + - [Debian/Ubuntu (.deb)](#debianubuntu-deb) + - [Exherbo](#exherbo) + - [Other distributions (.tar.gz)](#other-distributions-targz) +- [macOS](#macos) + - [Homebrew](#homebrew) + - [Binary (.tar.gz)](#binary-targz) +- [Windows](#windows) + - [Winget](#winget) + - [Chocolatey](#chocolatey) + - [Binary (.zip)](#binary-zip) +- [Docker](#docker) + - [Dockerfile](#dockerfile) +- [Nix package manager](#nix-package-manager) +- [Enabling autocompletion](#enabling-autocompletion) + +## GNU/Linux + +### Arch Linux (AUR) + +If you use Arch Linux, install packages [from AUR](https://aur.archlinux.org/packages/clever-tools-bin/). If you don't know how to use this, run: + +``` +git clone https://aur.archlinux.org/clever-tools-bin.git clever-tools +cd clever-tools +makepkg -si +``` + +### CentOS/Fedora (.rpm) + +If you use a GNU/Linux distribution that uses `.rpm` packages like CentOS or Fedora, run: + +``` +curl -s https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo > /etc/yum.repos.d/cc-nexus-rpm.repo +yum update +yum install clever-tools +``` + +> [!TIP] +> The `.rpm` packages are hosted on Clever Cloud's public Nexus instance available at [https://nexus.clever-cloud.com](https://nexus.clever-cloud.com) + +### Debian/Ubuntu (.deb) + +If you use a GNU/Linux distribution that uses `.deb` packages like Debian or Ubuntu, run: + +``` +curl -fsSL https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key | gpg --dearmor -o /usr/share/keyrings/cc-nexus-deb.gpg +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/cc-nexus-deb.gpg] https://nexus.clever-cloud.com/repository/deb stable main" | tee -a /etc/apt/sources.list +apt update +apt install clever-tools +``` + +> [!TIP] +> The `.deb` packages are hosted on Clever Cloud's public Nexus instance available at [https://nexus.clever-cloud.com](https://nexus.clever-cloud.com). \ +> Our PGP key is required to trust the repository + +### Exherbo + +If you are using Exherbo, run: + +``` +cave resolve repository/CleverCloud -zx1 +cave resolve clever-tools-bin -zx +``` + +### Other distributions (.tar.gz) + +If you use another GNU/Linux distribution, download the `.tar.gz` archive and extract the binary in your `PATH`: + +``` +curl -O https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_linux.tar.gz +tar xvzf clever-tools-latest_linux.tar.gz +cp clever-tools-latest_linux/clever ~/.local/bin/ +``` + +> [!TIP] +> The packages are available on Clever Cloud's Cellar bucket: [clever-tools-latest_linux.tar.gz](https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_linux.tar.gz). \ +> Retrieve any release by replacing `latest` (path and filename) with the version number you need. + +## macOS + +### Homebrew + +If you use macOS and you have [Homebrew](https://brew.sh) installed, run: + +``` +brew install CleverCloud/homebrew-tap/clever-tools +``` + +### Binary (.tar.gz) + +If you use macOS, but you don't have [Homebrew](https://brew.sh) installed, download the `.tar.gz` archive and extract the binary in your `PATH`: + +``` +curl -O https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_macos.tar.gz +tar xvzf clever-tools-latest_macos.tar.gz +cp clever-tools-latest_macos/clever ~/.local/bin/ +``` + +> [!TIP] +> The packages are available on Clever Cloud's Cellar bucket: [clever-tools-latest_macos.tar.gz](https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_macos.tar.gz). \ +> Retrieve any release by replacing `latest` (path and filename) with the version number you need. + +## Windows + +### Winget + +If you use Windows run in a terminal: + +``` +winget install CleverTools +``` + +### Chocolatey + +If you prefer to use [Chocolatey](https://chocolatey.org), run: + +``` +choco sources add -n=clevercloud -s='https://nexus.clever-cloud.com/repository/nupkg/' +choco feature disable --name='usePackageRepositoryOptimizations' +choco install clever-tools +``` + +We need to disable `usePackageRepositoryOptimizations` feature because of [an incompatibility](https://github.com/chocolatey/choco/issues/3506) between Chocolatey and Nexus. + +### Binary (.zip) + +You can also download the `.zip` archive and extract the binary in your `PATH`: + +```PowerShell +Invoke-WebRequest https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_win.zip -OutFile clever-tools-latest_win.zip +Expand-Archive .\clever-tools-latest_win.zip -DestinationPath . +$env:PATH += ";$(Resolve-Path .\clever-tools-latest_win\)" +``` + +> [!TIP] +> The packages are available on Clever Cloud's Cellar bucket: [clever-tools-latest_win.zip](https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_win.zip). \ +> Retrieve any release by replacing `latest` (path and filename) with the version number you need. + +## Docker + +If you are using docker, use the image provided [here](https://hub.docker.com/r/clevercloud/clever-tools/). + +``` +docker pull clevercloud/clever-tools +docker run --rm clever-tools +``` + +### Dockerfile + +In your `Dockerfile` copy `clever-tools` from the image itself with a simple one liner: + +```Dockerfile +COPY --from=clevercloud/clever-tools /bin/clever /usr/local/bin/clever +``` + +## Nix package manager + +If you are using Nix on NixOS or any other compatible system, the package is available in both `stable` and `unstable` channels. Follow [these instructions](https://search.nixos.org/packages?channel=unstable&show=clever-tools&from=0&size=50&sort=relevance&type=packages&query=clever-tools). + +## Enabling autocompletion + +The clever-tools CLI comes with a comprehensive auto-completion system. Some installation methods through package managers will try to enable it automatically. If not, use this for bash: + +```bash +clever --bash-autocomplete-script $(which clever) | sudo tee /usr/share/bash-completion/completions/clever +``` + +or that for zsh: + +```bash +clever --zsh-autocomplete-script $(which clever) | sudo tee /usr/share/zsh/site-functions +``` diff --git a/content/doc/cli/install/nexus-config.md b/content/doc/cli/install/nexus-config.md new file mode 100644 index 000000000..004eb00df --- /dev/null +++ b/content/doc/cli/install/nexus-config.md @@ -0,0 +1,57 @@ +--- +type: docs +title: Nexus repository +description: Configure Clever Cloud Nexus repository for you distribution +--- + +We use a self hosted Nexus repository to distribute `.deb`, `.nupkg` and `.rpm`. It's available at [https://nexus.clever-cloud.com/](https://nexus.clever-cloud.com/). + +## Repositories + +### `.deb` repository + +We have a repository for `.deb` packages, available [here](https://nexus.clever-cloud.com/#browse/browse:deb). + +* stable: [deb](https://nexus.clever-cloud.com/#browse/browse:deb) + +The repository is signed with the PGP key `Clever Cloud Nexus (deb)`. The public key is published on the Cellar at [https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key](https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key). The private key, public key and passphrase are stored in our vault. + +### `.nupkg` repository + +We have a repository for `.nupkg` packages, available [here](https://nexus.clever-cloud.com/#browse/browse:nupkg) + +* Link to Nexus [nuget-repositories docs](https://help.sonatype.com/en/nuget-repositories.html) + +### `.rpm` repository + +We have a repository for `.rpm` packages, available [here](https://nexus.clever-cloud.com/#browse/browse:rpm). + +* Link to Nexus [yum-repositories docs](https://help.sonatype.com/en/yum-repositories.html) + +The repository is not signed, but the `.rpm` packages are. + +The repo description is maintained in this git repo at `templates/rpm/cc-nexus-rpm.repo`. It's published on the Cellar at [https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo](https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo). The public key is published on the Cellar at [https://clever-tools.clever-cloud.com/gpg/cc-nexus-rpm.public.gpg.key](https://clever-tools.clever-cloud.com/gpg/cc-nexus-rpm.public.gpg.key). The private key, public key and passphrase are stored in our vault. + +### GnuPG Keys + +Steps to follow to generate a new pair of GnuPG keys: + +* Prepare a random string for the passphrase (30+ chars is good) +* Run `gpg --gen-key` +* Name: `Clever Cloud Nexus (deb)` +* Email: ci@clever-cloud.com +* Get the ID of the new generated key with `gpg --list-keys` +* Export the public key in a file + * `gpg --armor --output cc-nexus-deb.public.gpg.key --export ` +* Publish the public key on the Cellar + * `s3cmd -c .s3cfg put --acl-public cc-nexus-deb.public.gpg.key s3://clever-tools.clever-cloud.com/gpg/` +* Export the private key in a file + * `gpg --armor --output cc-nexus-deb.private.gpg.key --export-secret-key ` +* Update the private key where it's needed + * The `deb` private key and passphrase need to be set in both `deb` and `deb-stable` repo in Nexus. + * The `rpm` private key and passphrase need to be set in Jenkins. +* Combine both keys into one file + * `cat cc-nexus-deb.*.gpg.key cc-nexus-deb.combined.gpg.key` +* Add the combined key to the vault along with the random passphrase. + +This is an example for `deb` but the same goes for `rpm`. diff --git a/content/doc/cli/kv-stores.md b/content/doc/cli/kv-stores.md new file mode 100644 index 000000000..5333874f3 --- /dev/null +++ b/content/doc/cli/kv-stores.md @@ -0,0 +1,54 @@ +--- +type: docs +title: KV stores +description: Use Materia KV and Redis directly from Clever Tools +aliases: +- /doc/kv-stores +--- + +If you're using [Materia KV](/developers/doc/addons/materia-kv/), our next generation of key-value databases, serverless, distributed, synchronously-replicated, compatible with the Redis® protocol (and later DynamoDB, GraphQL), you can easily create an add-on with Clever Tools: + +``` +clever addon create kv ADDON_NAME +``` + +And immediately use it with `clever kv` command: + +```bash +clever features enable kv # KV command is in testing stage +clever kv ADDON_NAME_OR_ID PING # It will answer PONG +clever kv ADDON_NAME_OR_ID PING Hello # It will answer Hello +``` + +It helps you to inspect and interact with your Materia KV. Each is provided with environment variables about its host, port, and [Biscuit-based](https://biscuitsec.org) tokens, in multiple forms (to ensure compatibility with tools such those made for Redis®). + +> [!Tip] +> Clever KV command is also compatible with Redis® on Clever Cloud add-ons. + +## Commands + +You can use `clever kv` to send any command supported by your add-on. Here are some examples: + +```bash +clever kv ADDON_NAME_OR_ID INCR myCounter # It will respond (integer) the incremented value +clever kv ADDON_NAME_OR_ID SET myKey myValue # It will respond OK +clever kv ADDON_NAME_OR_ID GET myKey # It will respond myValue +clever kv ADDON_NAME_OR_ID SET myKey myValue EX 120 # It will respond OK +clever kv ADDON_NAME_OR_ID TTL myKey # It will respond (integer) the remaining time to live of the key in seconds +``` + +> [!Tip] +> You can get a list of all supported commands with `clever kv ADDON_NAME_OR_ID COMMANDS` + +You can pass the result of JSON stringified values to tools like `jq` to query them, for example: + +```bash +clever kv ADDON_NAME_OR_ID SET myJsonFormatedKey '{"key": "value"}' +clever kv ADDON_NAME_OR_ID GET myJsonFormatedKey | jq .key +``` + +You can also use the `-F/--format` option to print a result in JSON format and query it with `jq`: + +```bash +clever kv ADDON_NAME_OR_ID scan 0 -F json | jq '.[1][0]' +``` diff --git a/content/doc/cli/logs-drains.md b/content/doc/cli/logs-drains.md new file mode 100644 index 000000000..a4f6039cd --- /dev/null +++ b/content/doc/cli/logs-drains.md @@ -0,0 +1,123 @@ +--- +type: docs +title: Logs, Drains +description: Use Clever Tools to get logs, access logs and manage logs drains +aliases: +- /doc/logs-drains +--- + +## logs + +When you deploy an application on Clever Cloud, we collect its logs, hosted in our internal Pulsar stack, all included. + +To listen the stream, use: + +``` +clever logs +``` + +You can also get logs from a specific timeline, deployment or add-on through options: + +``` +[--before, --until] BEFORE Fetch logs before this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h) +[--after, --since] AFTER Fetch logs after this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h) +[--search] SEARCH Fetch logs matching this pattern +[--deployment-id] DEPLOYMENT_ID Fetch logs for a given deployment +[--addon] ADDON_ID Add-on ID +[--format, -F] FORMAT Output format (human, json, json-stream) (default: human) +``` + +## access logs + +When you deploy an application on Clever Cloud, we collect its access logs, hosted in our internal Pulsar stack, all included. + +To listen the stream, use: + +``` +clever accesslogs +``` + +> [!TIP] +> This now uses our v4 API, it's available as Alpha feature for now. + +You can also get access logs from a specific timeline or add-on through options, in multiple formats: + +``` +[--before, --until] BEFORE Fetch logs before this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h) +[--after, --since] AFTER Fetch logs after this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h) +[--format, -F] FORMAT Output format (human, json, json-stream) (default: human) +``` + +You can for example get access logs in JSON stream format for the last hour with: + +``` +clever accesslogs --format json-stream --since 1h +clever accesslogs -F json-stream | jq '.source.ip' +``` + +or JSON if you add a date/time end limit: + +``` +clever accesslogs --app APP_NAME --since 2025-04-21T13:37:42 --until 1d -F json | jq '[.[] | {date, countryCode: .source.countryCode, ip: .source.ip, port: .source.port}]' +clever accesslogs --app APP_NAME --since 2025-04-21T13:37:42 --until 1d -F json | jq '.[] | [.date, .source.countryCode, .source.ip, .source.port] | @sh' +``` + +> [!TIP] +> `jq` offers multiple table formatting options, like `@csv`, `@tsv`, `@json`, `@html`, `@uri`, `@base64`, etc. + +## drain + +You can use Clever Tools to control logs drains, through following commands. Each can target a specific add-on with `--addon ADDON_ID ` or application, adding `--app APP_ID_OR_NAME` or a local alias (`--alias`, `-a`): + +``` +clever drain +clever drain --format json +clever drain create +clever drain remove +clever drain enable +clever drain disable +``` + +Where `DRAIN-TYPE` is one of: + +- `DatadogHTTP`: for Datadog endpoint (note that this endpoint needs your Datadog API Key) +- `ElasticSearch`: for ElasticSearch endpoint (note that this endpoint requires username/password parameters as HTTP Basic Authentication) +- `HTTP`: for TCP syslog endpoint (note that this endpoint has optional username/password parameters as HTTP Basic Authentication) +- `NewRelicHTTP`: for NewRelic endpoint (note that this endpoint needs your NewRelic API Key) +- `TCPSyslog`: for TCP syslog endpoint +- `UDPSyslog`: for UDP syslog endpoint + +Drain creation supports the following options: + +``` +[--username, -u] USERNAME (HTTP drains) basic auth username +[--password, -p] PASSWORD (HTTP drains) basic auth password +[--api-key, -k] API_KEY (NewRelic drains) API key +[--index-prefix, -i] INDEX_PREFIX (ElasticSearch drains) Index prefix (default: logstash-) +[--sd-params, -s] SD_PARAMS (TCP and UDP drains) sd-params string (e.g.: `X-OVH-TOKEN=\"REDACTED\"`) +``` + +### ElasticSearch logs drains + +ElasticSearch drains use the Elastic bulk API. To match this endpoint, specify `/_bulk` at the end of your ElasticSearch endpoint. + +### Datadog logs drains + +Datadog has two zones, EU and COM. An account on one zone is not available on the other, make sure to target the good EU or COM intake endpoint. To create a [Datadog](https://docs.datadoghq.com/api/?lang=python#send-logs-over-http) drain, you just need to use one of the following command depending on your zone: + +``` +# EU +clever drain create DatadogHTTP "https://http-intake.logs.datadoghq.eu/v1/input/?ddsource=clevercloud&service=&host=" +# US +clever drain create DatadogHTTP "https://http-intake.logs.datadoghq.com/v1/input/?ddsource=clevercloud&service=&host=" +``` + +The `host` query parameter is not mandatory: in the Datadog pipeline configuration, you can map `@source_host` which is the host provided by Clever Cloud in logs as `host` property. + +### NewRelic logs drains + +NewRelic has two zones, EU and US. An account on one zone is not available on the other, make sure to target the good EU or US intake endpoint. To create a [NewRelic](https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/) drain, you just need to use: + +``` +clever drain create NewRelicHTTP "https://log-api.eu.newrelic.com/log/v1" --api-key +``` diff --git a/content/doc/cli/network-groups.md b/content/doc/cli/network-groups.md new file mode 100644 index 000000000..48f68d244 --- /dev/null +++ b/content/doc/cli/network-groups.md @@ -0,0 +1,136 @@ +--- +type: docs +title: Network Groups +description: Use Network Groups directly from Clever Tools +--- + +[Network Groups](/developers/doc/develop/network-groups/) (NG) are a way to create a private secure network between resources inside Clever Cloud infrastructure, using [Wireguard](https://www.wireguard.com/). It's also possible to connect external resources to a Network Group. There are three components to this feature: + +* Network Group: a group of resources that can communicate with each through an encrypted tunnel +* Member: a resource that can be part of a Network Group (`application`, `addon` or `external`) +* Peer: Instance of a resource connected to a Network Group (can be `external`) + +A Network Group is defined by an ID (`ngId`) and a `label`. It can be completed by a `description` and `tags`. + +> [!NOTE] +> During beta testing phase, you can add add-ons and external peers to a Network Group, but these features are not yet fully supported. + +Tell us what you think of Network Groups and what features you need from it in [the dedicated section of our GitHub Community](https://github.com/CleverCloud/Community/discussions/categories/network-groups). + +- [Learn more about Network Groups](/developers/doc/develop/network-groups/) + +## How it works + +When you create a Network Group, a Wireguard configuration is generated with a corresponding [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). Then, you can, for example, add a Clever Cloud application and an associated add-on to the same Network Group. These are members, defined by an `id`, a `label`, a `kind` and a `domain name`. + +When an application connects to a Network Group, you can reach it on any port inside a NG through its domain name. Any instance of this application is a peer, you can reach independently through an IP (from the attributed CIDR). It works the same way for add-ons and external resources. During alpha testing phase, only applications are supported. + +> [!TIP] +> A Network Group member domain name is composed this way: `.m.cc-ng.cloud` + +## Prerequisites + +Activate `ng` feature flag to manage Network Groups: + +``` +clever features enable ng +``` + +Then, check it works with the following command: + +``` +clever ng +``` + +In all the following examples, you can target a specific organisation with the `--org` or `-o` option. + +## Create a Network Group + +A Network Group is simple to create: + +``` +clever ng create myNG +``` + +You can create it declaring its members: + +``` +clever ng create myNG --link app_xxx,addon_xxx +``` + +You can add a description and tags: + +``` +clever ng create myNG --description "My first NG" --tags test,ng +``` + +## Delete Network Groups + +You can delete a Network Group through its ID or label: + +``` +clever ng delete ngId +clever ng delete ngLabel +``` + +## List Network Groups + +Once created, you can list your Network Groups: + +``` +clever ng + +┌─────────┬───────-┬─────────-─┬───────────────┬─────────┬───────┐ +| (index) │ ID │ Label │ Network CIDR │ Members │ Peers │ +├─────────┼────────┼───────────┼───────────────┼─────────┼───────┤ +│ 0 │ 'ngId' │ 'ngLabel' │ '10.x.y.z/16' │ X │ Y │ +└─────────┴────────┴──────────-┴───────────────┴─────────┴───────┘ +``` + +A `json` formatted output is available with the `--format/-F json` option. + +## (Un)Link a resource to a Network Group + +To (un)link an application, add-on or external peer to a Network Group: + +``` +clever ng link app_xxx ngIdOrLabel +clever ng unlink addon_xxx ngIdorLabel +``` + +After an unlink, you may need to restart the application to apply the changes. + +## Get information of a Network Group, a member or a peer + +To get information about a network group or a resource (a `json` formatted output is available): + +``` +clever ng get ngIdOrLabel -F json +clever ng get resourceIdOrName +``` + +You can also search for network groups, members or peers: + +``` +clever ng search text_to_search -F json +``` + +> [!NOTE] +> The search command is case-insensitive and will return all resources containing the search string +> The get command look for an exact match and will return an error if multiple resources are found + +## Get the Wireguard configuration of a Peer + +To get the Wireguard configuration of a peer (a `json` formatted output is available): + +``` +clever ng get-config peerIdOrLabel myNG +``` + +## Demos & examples + +You can find ready to deploy projects using Network Groups in the following repositories: + +- https://github.com/CleverCloud/network-groups-example + +Create your own and [let us know](https://github.com/CleverCloud/Community/discussions/categories/network-groups)! diff --git a/content/doc/cli/notifications-webhooks.md b/content/doc/cli/notifications-webhooks.md new file mode 100644 index 000000000..84002454c --- /dev/null +++ b/content/doc/cli/notifications-webhooks.md @@ -0,0 +1,75 @@ +--- +type: docs +title: Notifications, WebHooks +description: Configure Clever Cloud Nexus repository for you distribution +aliases: +- /doc/administrate/clever-tools/notifications +- /doc/clever-tools/notifications/ +- /doc/cli/notifications +- /doc/reference/clever-tools/notifications +- /reference/clever-tools/notifications +--- + +When events happen on Clever Cloud, during add-ons or applications lifecycle for example, you can send email notifications or trigger webhooks. For each of the following command, you can list all items and/or target a specific user/organisation through these parameters: + +``` +[--org, -o, --owner] Organisation ID (or name, if unambiguous) +[--list-all] List all notifications for your user or for an organisation with the `--org` option (default: false) +``` + +## notify-email + +You can send email notifications when an event occurs. To list them, use: + +``` +clever notify-email +clever notify-email --format json +``` + +To add a notification process to an application, use: + +``` +clever notify-email add --notify ||"ORGANISATION" NAME +``` + +Available options are: + +``` +[--event] TYPE Restrict notifications to specific event types +[--service] SERVICE_ID Restrict notifications to specific applications and add-ons +--notify ||"ORGANISATION" Notify a user, a specific email address or the whole organisation (multiple values allowed, comma separated) +``` + +To delete a notification process, use: + +``` +clever notify-email remove NOTIFICATION-ID +``` + +## webhooks + +You can trigger Webhooks when an event occurs. To list them, use: + +``` +clever webhooks -F json +``` + +To add a webhook to an application, use: + +``` +clever webhooks add NAME URL +``` + +You can set the format, restrict to a service or event types through these parameters: + +``` +[--format] FORMAT Format of the body sent to the webhook ('raw', 'slack', 'gitter', or 'flowdock') (default: raw) +[--event] TYPE Restrict notifications to specific event types +[--service] SERVICE_ID Restrict notifications to specific applications and add-ons +``` + +To delete a webhook, use: + +``` +clever webhooks remove NOTIFICATION-ID +``` diff --git a/content/doc/cli/operators.md b/content/doc/cli/operators.md new file mode 100644 index 000000000..b16799583 --- /dev/null +++ b/content/doc/cli/operators.md @@ -0,0 +1,84 @@ +--- +type: docs +title: Operators +description: Manage Keycloak, Matomo, Metabase, Otoroshi from Clever Tools +--- + +Operators allow you to deploy services as turnkey solutions on Clever Cloud. They provision resources, configure them and expose an API and tools to ease their management during their lifecycle. To add operators commands to Clever Tools, enable the `operators` feature: + +``` +clever features enable operators +``` + +Then, you can use the commands to manage Keycloak, Matomo, Metabase and Otoroshi instances on Clever Cloud. For example to list them deployed services: + +``` +clever keycloak +clever matomo +clever metabase +clever otoroshi +``` + +To get information about a deployed service, use: + +``` +clever keycloak get myKeycloak +clever matomo get matomo_id --format json +``` + +> [!TIP] +> You can target a deployed service by its ID or name. +## Service management + +To restart or rebuild (restart without cache) a deployed service, use: + +``` +clever metabase restart myMetabase +clever otoroshi rebuild otoroshi_id +``` + +To open the deployed service dashboard in Clever Cloud Console, use: + +``` +clever keycloak open myKeycloak +``` + +You can also open the service web management interface or logs of the underlying application: + +``` +clever otoroshi open logs myOtoroshi +clever otoroshi open webui otoroshi_id +``` + +## Version management + +To check the version of a deployed service, use: + +``` +clever matomo version check matomo_id +clever metabase version check myMetabase --format json +``` + +To update to a specific version, use: + +``` +clever keycloak version update myKeycloak 24.0.1 +``` + +To see a list of available versions, don't provide a version number: + +``` +clever otoroshi version update otoroshi_id +``` + +## Network Groups + +Keycloak and Otoroshi can be easily linked to a [Network Group](/developers/doc/cli/network-groups/). To enable/disable this feature, use: + +``` +clever keycloak enable-ng myKeycloak +clever otoroshi disable-ng otoroshi_id +``` + +> [!NOTE] Keycloak secure cluster feature +> When you enable the Network group on a Clever Cloud Keycloak, the cluster is automatically configured and the Java application scaled to 2 instances. When you disable the Network Group, the application is scaled down to 1 instance and the cluster is removed. diff --git a/content/doc/cli/services-depedencies.md b/content/doc/cli/services-depedencies.md new file mode 100644 index 000000000..547270783 --- /dev/null +++ b/content/doc/cli/services-depedencies.md @@ -0,0 +1,64 @@ +--- +type: docs +title: Services Dependencies +description: Use Clever Tools to manage services dependencies +--- + +On Clever Cloud, applications can expose configuration to share environment variables with other services within the same account/organisation. Add-ons are preconfigured with an exposed configuration. Thus, when they're linked to an application, they automatically share credentials or important variables needed to configure and use them. Following commands help you with that. + +Each can target a specific application, adding `--app APP_ID_OR_NAME` or a local alias (`--alias`, `-a`). + +## published-config + +To list exposed configuration, use: + +``` +clever published-config +clever published-config --F json +clever published-config --format shell +``` + +To configure exposed configuration, use: + +``` +clever published-config COMMAND +``` + +Available commands are `set`, `rm` (remove) or `import`. The latter reads data from `stdin` so use it as is: + +``` +clever published-config import < file.config +``` + +## service + +To list services dependencies, use: + +``` +clever service +clever service --format json +``` + +You can filter results through these options. + +``` +[--only-apps] Only show app dependencies (default: false) +[--only-addons] Only show add-on dependencies (default: false) +[--show-all] Show all available add-ons and applications (default: false) +``` + +To create or delete services dependencies, use: + +``` +clever service COMMAND ADDON_OR_APP_ID +clever service COMMAND ADDON_OR_APP_NAME +``` + +Available commands are: + +``` +link-app Add an existing app as a dependency +unlink-app Remove an app from the dependencies +link-addon Link an existing add-on to this application +unlink-addon Unlink an add-on from this application +``` diff --git a/content/doc/contribute.md b/content/doc/contribute.md new file mode 100644 index 000000000..9e4e4be57 --- /dev/null +++ b/content/doc/contribute.md @@ -0,0 +1,39 @@ +--- +type: docs +weight: 14 +title: Contribute +description: Learn about the available shortcodes to write new documentation +tags: +- contribute +keywords: +- contribution +- shortcode +- writing +aliases: +- /administrate/guides/contribute +- /contribute +- /contribute/writing +- /doc/contribute/shortcodes/ +- /doc/contribute/writing +- /doc/get-help/community +- /readme +comments: false +--- + +Would you like to contribute to this documentation? + +## Before writing something new + +Before you start writing something new please create a [Github issue](https://github.com/CleverCloud/documentation/issues) so we can talk about it. Moslty to make sure someone is not already working on the same thing. + +## Writing new content + +There are a number of things you need to be aware of when writing new content. We use Markdown files and [Hugo](https://gohugo.io/) to generate this documentation. + +### Debug Mode + +If you add `debug=true` as params of your Hugo site, you should see every shortcode outlined on your website like so: + +```html +
myshortcode

This is a shortcode being used

+``` diff --git a/content/doc/develop/_index.md b/content/doc/develop/_index.md new file mode 100644 index 000000000..be124979e --- /dev/null +++ b/content/doc/develop/_index.md @@ -0,0 +1,17 @@ +--- +type: docs +weight: 6 +title: Develop +description: Learn how to develop your applications for Clever Cloud +comments: false +aliases: +- /develop +--- + +{{< cards >}} + {{< card link="/developers/doc/develop/build-hooks" title="Deployment hooks" icon="rocket-launch" >}} + {{< card link="/developers/doc/reference/reference-environment-variables" title="Environment variables reference" icon="creds" >}} + {{< card link="/developers/doc/develop/env-variables" title="How environment variables work" icon="question-mark-circle" >}} + {{< card link="/developers/doc/develop/workers" title="Workers" icon="arrow-path" >}} + {{< card link="/developers/doc/develop/healthcheck" title="Deployment healthcheck path" icon="check" >}} +{{< /cards >}} diff --git a/content/doc/develop/build-hooks.md b/content/doc/develop/build-hooks.md new file mode 100644 index 000000000..995a6c785 --- /dev/null +++ b/content/doc/develop/build-hooks.md @@ -0,0 +1,131 @@ +--- +type: docs +title: Deployment Hooks +description: Hooks allow to run custom tasks during deployment +tags: +- develop +keywords: +- apps +- hooks +aliases: +- /clever-cloud-overview/hooks +- /doc/build-hooks +- /doc/clever-cloud-overview/hooks +- /doc/deploy/build-hooks +--- +## Deployment lifecycle + +An application deployed on Clever Cloud goes through two distinct phases. The +`build` phase where dependencies are fetched and the application built, and the +`run` phase where the application is launched. Hooks allow you to run specific +tasks before and after those phases. + +The available hooks are: + +- Pre Build +- Post Build +- Pre Run +- On Run Succeeded +- On Run Failed + +## Setting hooks up + +Hooks are set up through [environment +variables](/developers/doc/develop/env-variables). +To set up a Post Build hook, you need to define a `CC_POST_BUILD_HOOK` +variable: + +```shell +CC_POST_BUILD_HOOK=echo "it works!" +``` + +You can directly put commands in the hook. Hooks have access to the environnement variables as well as a working Node.js installation. + +If you have complex things to do, the best way is to put the logic in a bash script *(dont forget to make it executable!)* +To use it, set the hook you want to trigger to the path of your script, relative to the root path of your repository. +E.g. if your script is in a clevercloud folder at the root of your project then you can define `CC_POST_BUILD_HOOK=./clevercloud/script.sh` + +## Can't I use $BUILD_TOOL? + +Hooks are designed as an escape hatch for steps you can't integrate properly in +your build tool. In many case, you can (and you should) integrate as much as +possible with your build tool, but sometimes it's not possible. Another reason +to use hooks is to integrate Clever Cloud-specific tasks which don't belong in +the project's build configuration. + +## Exceptions + +Some application types do not have hooks support or only some of them. + +### Docker + +For Docker, because you can do pretty much anything yourself inside your Dockerfile, only the following hooks are available: + +- `CC_RUN_SUCCEEDED_HOOK` + +If you need support for other hooks, please reach out to our support and explain your use case. + +## Hooks types + +### Pre Build + +**By using `CC_PRE_BUILD_HOOK`**. + +This hook is ran before the dependencies are fetched. If it fails, the +deployment fails. + +This hook is ran every time. + +This hook is perfect for: + +- build tool configuration (eg setting up a `.npmrc` with private tokens) +- extra dependencies fetching (eg `npm install` for frontend deps) + +### Post Build + +**By using `CC_POST_BUILD_HOOK`.** + +This hook is ran after the project is built, and before the cache archive is +generated. If it fails, the deployment fails. + +This hook is not ran during deployments from cache. + +This hook is perfect for: + +- extra build steps that you want to cache (eg bundling your frontend assets) + +{{< callout type="info" >}} + If you set [\`CC_DISABLE_BUILD_CACHE_UPLOAD\`](/developers/doc/develop/env-variables/#settings-you-can-define-using-environment-variables) environment variable to `true`, the cache archive won't be created nor uploaded. +{{< /callout >}} + +### Pre Run + +**By using `CC_PRE_RUN_HOOK`.** + +This hook is ran before the application is started, but after the cache archive +has been generated. If it fails, the deployment fails. + +This hook is ran every time. + +This hook is perfect for: + +- preparation tasks that need to be ran every time (eg a database migration check) + +### Run Success/Fail + +**By using `CC_RUN_SUCCEEDED_HOOK` or `CC_RUN_FAILED_HOOK`.** + +These hooks are ran once the application has started (or has failed starting). +Their failure doesn't cause the deployment to fail. + +One of these hooks is ran every time. + +These hooks are perfect for: + +- notifications +- clean-up + +{{< callout emoji="🧹" >}} +**This hook is deprecated** +These hooks replace the older `postDeploy` hook, which is now deprecated. +{{< /callout >}} diff --git a/content/doc/develop/env-variables.md b/content/doc/develop/env-variables.md new file mode 100644 index 000000000..a8d0e043f --- /dev/null +++ b/content/doc/develop/env-variables.md @@ -0,0 +1,253 @@ +--- +type: docs +title: Environment variables +description: How to setup and configure environment variables for apps and add-ons +tags: +- dashboard-setup +- apps +- develop +keywords: +- env +- variables +- environment variables +aliases: +- /develop/env-variables +--- + +Clever Cloud allows you to define environment variables that will be +injected in your application's environment. + +## How are variables defined? + +Variables are defined on a per-application basis. They are defined in four ways: + +* By provisioned add-ons linked to applications. The variables names + are listed in the add-on's information panel. + +* By linked applications with exposed configuration. + +* By adding variables yourself in the "Environment variables" panel of your application. + +* Some environment variables are added automatically for each application. + +Please note that if you define or modify environment variables, you will +need to redeploy your application to make it use the new variables. + +Check out our [environment variable reference](/developers/doc/reference/reference-environment-variables). + +## Special environment variables + +Some variables are injected to the environment of your application when you deploy it, +to inform you about the current context of your application and about the application itself. + +They can be accessed as classic environment variables. + +* `APP_ID`: the ID of the application. Each application has a unique identifier used to + identify it in our system. This ID is the same than the one you can find in the information + section of your application. + +* `INSTANCE_ID`: the ID of the current instance (scaler) of your application. It's unique for each + instance of your application and changes every time you deploy it. + +* `INSTANCE_TYPE`: The type of the instance (scaler). Its value can be `build` or `production`. + `build` is when your application is being built on a dedicated instance. + +* `COMMIT_ID`: the commit ID used as a base to deploy your application. As we remove + the `.git` directory before the deployment (to avoid security problems), it can be used + to know which version of your application is running on the server. + +* `APP_HOME`: The absolute path of your application on the server. Can be used to + create absolute links in your application (e.g. `${APP_HOME}/foo/bar`). + +* `CC_PRETTY_INSTANCE_NAME`: A random string name generated for each instance using pokemon names. + +* `INSTANCE_NUMBER`: See below + +[dedicated-instance]: /developers/doc/administrate/apps-management#edit-application-configuration + +### What is the `INSTANCE_NUMBER` variable used for? + +This variable allows your application to differentiate each running node on the application level. + +It will contain a different number for each instance of your application. + +For example, if three instances are running, it will contain `0` for the first, +`1` for the second and `2` for the third. +It's handy if you want to only run crons on 1 instance (e.g. only on instance 0). + +## Settings you can define using environment variables + +We use environment variables for some settings: + +* `CC_DISABLE_BUILD_CACHE_UPLOAD`: allows you to ask that the cache archive is neither + created nor uploaded after the build process. Thus, restarts won't be speeded up, + as the build process will be launched each time. +* `IGNORE_FROM_BUILDCACHE`: allows you to specify paths to ignore when the build + cache archive is created. Must be relative to your application root. + (e.g. `foo/bar:foo/baz` where `bar` or `baz` can be either a directory or a file) + +* `CC_OVERRIDE_BUILDCACHE`: allows you to specify paths that will be in the build cache. + Only those files/directories will be cached + (e.g. `foo/bar:foo/baz` where `bar` or `baz` can be either a directory or a file). + +## Environment variables rules and formats + +You will find below a list of rules applied to our environment variables keys and +examples of the formats available on our different modes. + +### Rules + +* Letters (ASCII only, upper and lower case) + * Valid: `user_id`, `USER_ID`, `UsERId`, `userid`, `USERID` + * Invalid: `user_id?`, `?userid`, `user.id`, `user id` +* Digits (but not for first character) + * Valid: `user2id`, `userid42` + * Invalid: `2userid`, `1user_Id` +* Underscores + * Valid: `user_id`, `all_user_id`, `_user_id`, `_user_id__` +* Everything else is not allowed + +#### Java properties rules exception + +In case of a Java application you can also use: + +* Dashes + * Valid: `spring-boot`, `spring-boot-database`, `--spring-boot`, `--spring` +* Dots + * Valid: `spring.boot`, `spring.datasource.url`, `.spring.url` + +### Format + +Here are some formats that you can use when editing your variables +in our ["expert"](#expert) and [JSON](#json) modes. + +#### Expert + +The format of an expert variable is `VAR_NAME="VAR_VALUE"`. + +Here are some examples: + +* Multiple variables examples: + + ```bash + EMPTY="" + MULTI="line one + line two + line three" + ONE="value ONE" + TWO="value TWO" + ``` + +* Multiline: + + ```bash + MULTI="line one + line two + line three" + ``` + +* Empty value: + + ```bash + EMPTY="" + ``` + +#### JSON + +The format of a JSON variable is `{ "name": "VAR_NAME", "value": "VAR_VALUE" }`. + +Note: You must put these variables in an array (see the multiple variable example to see how it goes). + +Here are some examples: + +* Multiline: + + ```json + { + "name": "MULTI", + "value": "line one\nline two\nline three" + } + ``` + +* Empty value: + + ```json + { + "name": "EMPTY", + "value": "" + } + ``` + +* Multiple variables examples: + + ```json + [ + { + "name": "EMPTY", + "value": "" + }, + { + "name": "MULTI", + "value": "line one\nline two\nline three" + }, + { + "name": "ONE", + "value": "value ONE" + }, + { + "name": "TWO", + "value": "value TWO" + } + ] + ``` + +## How do I use these variables? + +Depending on the type of your application, the code will differ. +You can find more information in the documentation pages related to your application type. + +Here is a non-exhaustive summary: + +| Language | Usage | +|----------|-------| +| Go | `os.Getenv("MY_VAR")`| +| Haskell | `Os.Getenv["MY_VAR"]` | +| Node.js | `process.env["MY_VAR"]`| +| Java WAR | `System.getProperties().getProperty("MY_VAR")` | +| PHP | `getenv("MY_VAR")` | +| Play! Framework 1 & Play! Framework 2 | `System.getenv("MY_VAR")` or `${MY_VAR}` in `application.conf` | +| Python | `os.getenv("MY_VAR")` | +| Ruby | `ENV["MY_VAR"]` | +| Rust | `std::env::var("MY_VAR")` | +| Scala | `System.getenv("MY_VAR")` | +| .NET | `System.Environment.GetEnvironmentVariable("MY_VAR")` | + +## Specific languages + +{{< cards >}} + {{< card link="/developers/doc/applications/docker" title="Docker" icon="docker" >}} + {{< card link="/developers/doc/applications/golang/#environment-injection" title="Go" icon="go" >}} + {{< card link="/developers/doc/applications/haskell/#environment-injection" title="Haskell" icon= "haskell">}} + {{< card link="/developers/doc/applications/java/java-war/#environment-injection" title="Java-war" icon="java" >}} + {{< card link="/developers/guides/play-framework-1/#environment-injection" title="Play-1" icon="play" >}} + {{< card link="/developers/guides/play-framework-2/#environment-injection" title="Play-2" icon="play" >}} + {{< card link="/developers/doc/applications/nodejs#environment-injection" title="Node.js" icon="node" >}} + {{< card link="/developers/guides/ruby-rack-app-tutorial/#environment-injection" title="Ruby" icon="ruby" >}} + {{< card link="/developers/doc/applications/php/#environment-injection" title="PHP" icon="php" >}} + {{< card link="/developers/doc/applications/python/#environment-injection" title="Python" icon="python" >}} + {{< card link="/developers/doc/applications/rust/#environment-injection" title="Rust" icon="rust" >}} + {{< card link="/developers/doc/applications/scala/#environment-injection" title="Scala" icon="scala" >}} + {{< card link="/developers/doc/applications/elixir/#setting-up-environment-variables-on-clever-cloud" title="Elixir" icon="elixir" >}} + {{< card link="/developers/doc/applications/dotnet/#environment-injection" title=".NET" icon="dotnet" >}} + {{< card link="/developers/doc/applications/static/#setting-up-environment-variables-on-clever-cloud" title=".Static" icon="feather" >}} + +{{< /cards >}} + +{{< callout type="info" >}} +Variables are available at build time +for runtimes that support build time instructions, such as +[Java WAR](/developers/doc/applications/java/java-war/#environment-injection), +[Play! Framework 1](/developers/guides/play-framework-1/#environment-injection), +[Play! Framework 2](/developers/guides/play-framework-2/#environment-injection) +or [Scala](/developers/doc/applications/scala/#environment-injection). +{{< /callout >}} diff --git a/content/doc/develop/healthcheck.md b/content/doc/develop/healthcheck.md new file mode 100644 index 000000000..8e47a6307 --- /dev/null +++ b/content/doc/develop/healthcheck.md @@ -0,0 +1,15 @@ +--- +type: docs +linkTitle: Deployment healthcheck +title: Deployment healthcheck path +description: Healthcheck allows to check if an url return always the 200 code +tags: +- develop +keywords: +- apps +- healthcheck +aliases: +- /doc/healthcheck +--- + +{{% content "url_healthcheck" %}} diff --git a/content/doc/develop/network-groups.md b/content/doc/develop/network-groups.md new file mode 100644 index 000000000..18786001f --- /dev/null +++ b/content/doc/develop/network-groups.md @@ -0,0 +1,106 @@ +--- +type: docs +title: Network Groups +description: Link resources over a private secure network based on WireGuard +tags: +- network +- groups +- wireguard +- members +- peers +keywords: +- network +- groups +- wireguard +- members +- peers +aliases: +- /doc/network-groups +--- + +Network Groups (NG) are a way to create a private secure network between resources inside Clever Cloud infrastructure, using [WireGuard](https://www.wireguard.com/). It's also possible to connect external resources to a Network Group. There are three components to this feature: + +* Network Group: a group of resources that can communicate with each through an encrypted tunnel +* Member: a resource that can be part of a Network Group (`application`, `addon` or `external`) +* Peer: Instance of a resource connected to a Network Group (can be `external`) + +A Network Group is defined by an ID (`ngId`) and a `label`. It can be completed by a `description` and `tags`. + +When you create a Network Group, a WireGuard configuration is generated with a corresponding [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). Then, you can, for example, link an application and an add-on to the same Network Group. These are members, defined by an `id`, a `label`, a `kind` and a `domain name`. + +{{< callout type="info" >}} +During beta testing phase, you can add add-ons and external peers to a Network Group, but these features are not yet fully supported. \ +A Network Group member domain name is composed this way: `.m.cc-ng.cloud` +{{< /callout >}} + +When a resource is linked to a Network Group, you can reach it on any port inside this private network with its domain name. An application instance is a peer, you can reach through an IP (from the attributed CIDR). It works the same way for add-ons and external resources. + +- [Network Groups demo application](https://github.com/CleverCloud/network-groups-example) +- [How to use Network Groups from Clever Tools](/developers/doc/cli/network-groups/) +- [Keycloak and Otoroshi native support for Network Groups](/developers/api/v4/#network-groups) +- [Tell us what you think of Network Groups and what features you need from it in](https://github.com/CleverCloud/Community/discussions/categories/network-groups). + +## Architecture + +```mermaid +flowchart TD + User((User)) --> API[API/Clever Tools] + API --> NG[ 10.x.y.z/16] + + subgraph "Network Group" + NG --> CC[addon/app members] + NG --> Ext[external members] + + subgraph "Clever Cloud infrastructure" + CC --> App[application_id.m.ng_id.cc-ng.cloud] + CC --> DB[addon_id.m.ng_id.cc-ng.cloud] + App --- AppP1[Clever Peer + 10.x.y.1] + App --- AppP2[Clever Peer + 10.x.y.2] + DB --- DBP[Clever Peer + 10.x.y.3] + end + + subgraph "External Infrastructure" + Ext --> ExtRes[external_id.m.ngID.cc-ng.cloud] + ExtRes --- ExtP[External Peer + 10.x.y.4] + end + + + %% Mesh network represented by a connecting circle + MeshNet((("All peers can communicate through any port"))) + AppP1 --- MeshNet + AppP2 --- MeshNet + DBP --- MeshNet + ExtP --- MeshNet + end +``` + +## Concepts + +### Network Group +Network Groups operate as an overlay network, on top of the existing physical network infrastructure (underlay). When two peers communicate within a Network Group, packets are encapsulated in WireGuard tunnels that traverse Clever Cloud's underlay network. + +This approach enables the creation of flexible virtual network topologies without modifying the underlying physical infrastructure. Thanks to this overlay architecture, you can establish private and secure communications between your resources, even if they are physically dispersed across different zones of Clever Cloud's infrastructure or outside of it. + +Each Network Group has a unique ID (ngId), a human-readable label, and can include an optional description and tags for organisation. + +### Members +Resources connected to a Network Group can be applications or add-ons running on Clever Cloud (databases, services, etc.), or external resources outside of Clever Cloud (a third-party server, your local machine). Each member is accessible via a domain name. + +### Peers +Individual instances of a member resource. For example, if your application scales to three instances, each instance becomes a peer in the Network Group with its own IP address from the assigned CIDR range. + +## Key Benefits +Network Groups offer secure communication with all traffic between resources encrypted using WireGuard. You gain DNS resolution to access resources by domain name within the Network Group, along with internal port access to reach any port on any resource inside the Network Group. This creates a simplified architecture where you can connect applications and their dependencies in a private network. + +## Use Cases +Network Groups excel in microservices architecture by connecting multiple services securely without exposing them to the public internet. They simplify database access by allowing applications to access database add-ons through a secure channel. For legacy integration, they help connect external systems securely to your cloud applications. They also provide isolated environments for development and testing. + +## Technical Implementation +Network Groups leverage WireGuard, a modern VPN protocol known for its simplicity, speed, and security. When you create a Network Group, a dedicated CIDR range is allocated for your Network Group and WireGuard configurations are generated. When members join, they're assigned DNS names and IPs from the CIDR range, encrypted tunnels are established between peers, and traffic between resources flows through these secure tunnels. + +## Best Practices +Create Network Groups based on functional requirements or environments such as production or staging. Use clear, consistent naming for Network Groups and tag them appropriately. Establish different Network Groups to separate security domains, and keep track of which resources belong to which Network Groups. diff --git a/content/doc/develop/tasks.md b/content/doc/develop/tasks.md new file mode 100644 index 000000000..a8fbb8d16 --- /dev/null +++ b/content/doc/develop/tasks.md @@ -0,0 +1,117 @@ +--- +type: docs +title: Clever Tasks +description: How to setup and run single-job scalers on Clever Cloud +tags: +- deploy +- task +- worker +- jobs +- cron +keywords: +- task +- worker +- jobs +- cron +--- + +## Overview + +This will guide you in the process of creating a Clever Task: an application that will just run scalers for the duration of a given command and shutdown these scalers once the task is done. This type of application is not expected to listen to incoming requests. As such, no HTTP or TCP traffic from outside is routed towards the scalers. + +## Create a "task" application + +### With the Clever Tools CLI + +Make sure you have [Clever Tools installed](/developers/doc/cli/) and in your project folder, run `clever create --type --task `. You can also add options such as ` --region --org ` where: + 1. `app-name` the name you want for your application, + 2. `zone` deployment zone (`par` for Paris or `mtl` for Montreal for example) + 3. `org` the organisation ID the application will be created under + +You can create an application as a task without command to execute and define it later with the `CC_RUN_COMMAND` [environment variable](/developers/doc/reference/reference-environment-variables/). + +### With the console + +To declare an application as a Task, check the corresponding box in the `Information` tab. + +{{< figure src="/developers/images/clever-tasks.webp" caption="Defines a Clever Cloud application as a Task in Console" width="800px">}} + +## Define the command to run (mandatory) + +To run your task, you **have to** define a `CC_RUN_COMMAND` variable with the command that will be executed. + +{{%callout type="warning" %}} +If `CC_RUN_COMMAND` is not set during creation or later, the task deployment **will not** go through. +{{% /callout %}} + +### Examples + +Here are some example commands to run: + +```bash +CC_RUN_COMMAND="php my-special-script.php" +CC_RUN_COMMAND="python manage.py migrate" +CC_RUN_COMMAND="npm run app:test" +CC_RUN_COMMAND="./my-special-script.sh" +CC_RUN_COMMAND="node my-special-script.js" +CC_RUN_COMMAND="cd mytask; ./task1.sh && ./task2.sh" +``` + +Note that you can only set **one** `CC_RUN_COMMAND`. If you need to run multiple commands, separate them with `;`, `&&` or put them in a bash script. Your environment is loaded before running your commands, so you have access to all the environment variables you might have set. + +## What's in tasks apps? What is not? + +Clever Tasks are a quick way to run a script. When deploying, Clever Cloud just starts a VM, run the given command and then stop the VM. + +### Current limitation + +At the time of publishing this documentation, here are some limitations around tasks: + +- You cannot deploy the same app multiple times in parallel, executing different tasks. We will start the latter one after the former one ends. +- Due to this limitation, running a task deployment on an existing app will block "normal" deployments for the duration of the command. Event the ones from the monitoring. +- There is no out-of-the-box CRON trigger at the moment. You'll have set it up on your own. + +### Tips and examples + +#### Running from a CRON + +`Clever Tools` is available on all our VMs. You can trigger the deployment of a task by running a few `clever` commands. For example, setup a CRON on a web application that run such a script/command: + +```bash +#!/bin/bash + +# Make sure to setup CLEVER_TOKEN and CLEVER_SECRET +# These environment variables are required to authenticate with Clever Tools +# We restart the task app, it will start it and execute the CC_RUN_COMMAND +# Use the --quiet flag if you don't care for the logs to show in here +clever restart --app TASK_APP_ID --quiet +``` + +- [Learn more about CRON on Clever Cloud](/developers/doc/administrate/cron/) + +#### Running a script with different parameters + +You can write a script that takes specific environment variables and acts on it. Let's say your application needs to trigger the processing of a specific file after a customer uploaded it. Make your task script use the value from `FILE_TO_PROCESS` as the source: + +```bash +#!/bin/bash + +wget "${FILE_TO_PROCESS}" -O "to-process.csv" +process-my-file "to-process.csv" +``` + +Then in your main app, trigger the task like this: + +```bash +#!/bin/bash + +# We set the FILE_TO_PROCESS environment variable to the URL of the file to process +clever env set --app TASK_APP_ID FILE_TO_PROCESS "https://mybucket.cellar-c2.services.clever-cloud.com/some-file.csv" +clever restart --app TASK_APP_ID --quiet # That's if you don't care for the logs to show in here +``` + +{{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "env-injection" %}} diff --git a/content/doc/develop/workers.md b/content/doc/develop/workers.md new file mode 100644 index 000000000..8b740a019 --- /dev/null +++ b/content/doc/develop/workers.md @@ -0,0 +1,47 @@ +--- +type: docs +title: Workers +description: Workers allow to run background tasks running in parallel of your application +tags: +- develop +keywords: +- apps +- workers +aliases: +- /doc/workers +--- + +## Workers + +{{< callout type="info" >}} +Workers are not available for docker applications. +{{< /callout >}} + +You can run background tasks running in parallel of your application. They will be restarted automatically on error. +Those are especially useful for environments where you can't have long-running processes such as PHP, Ruby or Python. + +The workers run in the same environment as your application. They are launched as services by systemd, in the application's directory. + +All you need to do is add one (or several) environment variables as such: + +```bash +CC_WORKER_COMMAND=my-awesome-worker +``` + +Or + +```bash +CC_WORKER_COMMAND_0=my-awesome-worker +CC_WORKER_COMMAND_1=my-other-worker +``` + +By default, workers will be restarted if they exit with an error code. You can customise this behavior by setting the +environment variable `CC_WORKER_RESTART` to one of `always`, `on-failure` (the default) or `no`. + +You can define a delay to restart your worker with the environement variable `CC_WORKER_RESTART_DELAY`, the value is in seconds with a default value of `1`. It will apply to all registered workers. + +{{< callout type="warning" >}} +If the `CC_WORKER_RESTART_DELAY` value is too low and the restart policy is set to `always`, your worker might hit the restart burst limit, which may prevent your worker from being correctly restarted. +{{< /callout >}} + +If you want to have a restart delay less than 1 second and expect your script to restart multiple times in a very short time, please let us know on our support. diff --git a/content/doc/find-help/_index.md b/content/doc/find-help/_index.md new file mode 100644 index 000000000..93520e91f --- /dev/null +++ b/content/doc/find-help/_index.md @@ -0,0 +1,15 @@ +--- +weight: 13 +type: docs +title: Find Help +description: Find help on Clever Cloud, from support to FAQ and troubleshooting guides +aliases: +- /doc/administrate/find-help +comments: false +--- + +{{< cards >}} + {{< card link="/developers/doc/find-help/support" title="Support" icon="lifebuoy" >}} + {{< card link="/developers/doc/find-help/faq" title="FAQ" icon="question-mark-circle" >}} + {{< card link="/developers/doc/find-help/troubleshooting" title="Troubleshooting" icon="magnifying-glass" >}} +{{< /cards >}} diff --git a/content/doc/find-help/faq.md b/content/doc/find-help/faq.md new file mode 100644 index 000000000..332cfc181 --- /dev/null +++ b/content/doc/find-help/faq.md @@ -0,0 +1,237 @@ +--- +type: docs +title: FAQ +description: Frequently Asked Questions about Clever Cloud +tags: +- help +keywords: +- faq +- scaler +- languages +- kubernetes +- firewall +- scp +- ssh +- on premises +- pdf +- timezone +aliases: +- /doc/get-help/faq +--- + +## What is a Scaler? + +A _scaler_ is an individual instance hosting your app. You can attribute one or more scalers to your apps. scalers come in many sizes based on each language requirements from pico to XL. + +A fixed set of resources supports each scaler. + +When enabling auto-scalability, you have to set a minimum and a maximum of active scalers in your apps settings. This way you can precisely control your monthly fee. + +{{< callout type="warning" >}} + Nano and pico instances operate with **reduced CPU priority** on the host system. As a result, during periods of high load on the hypervisor, these instances may experience performance degradation (since they yield processing power to higher-priority workloads). +{{< /callout >}} + +## What languages and frameworks are supported by Clever Cloud? +Currently Clever Cloud supports: + +* Java (Play Framework 1 & 2, Maven, War files… ) +* Node.js +* PHP ([see frameworks and CMS](/developers/guides)) +* Python (Django) +* Ruby +* Go +* Haskell +* Scala +* Rust +* Docker + +## How many applications can I create? +As many as you want. We've not set a limited number of apps by developer. + +## How to setup domain names I own? + +You can bind custom domain names to your applications. Please have a look at [Custom Domain Names](/developers/doc/administrate/domain-names). + +## How can I disable one of my existing applications? + +Log in with your account to [console.clever-cloud.com](https://console.clever-cloud.com), and select the appropriate organisation and app in the left column. Then click on the application name and select **Overview**. Click on the **Stop** button to stop your app. + +## What type of content can I deploy? + +Please refer to the Acceptable Use Policy, article 2, [_Reasonable use of the Platform_](https://www.clever-cloud.com/acceptable-use-policy/). + +## How do I add or remove members in my organisations? + +Log in with your account to [console.clever-cloud.com](https://console.clever-cloud.com), and select the appropriate organisation in the left panel. Then click on **Members** in the mid pane. You'll see a list of the organisation's members. If your are an admin, you can revoke or grant permissions. + +## How do I report an application that infringes your Terms and Conditions? + +To report an application that infringes Clever Cloud's Terms and Conditions, please contact the legal team at . + +We will investigate and contact the application's owner over the violation if needed. + +## Does Clever Cloud support TLS/SSL (HTTPS)? + +Yes. For testing purposes, `cleverapps.io` domains support TLS out of the box. For custom SSL certificates, you can either generate one automatically with Let's Encrypt while adding a domain, or [use an existing one](/developers/doc/administrate/ssl/#uploading-my-own-certificates). +Have a look at [installing TLS certificates](/developers/doc/administrate/ssl), and feel free to contact the support team in the [Ticket Center](https://console.clever-cloud.com/ticket-center-choice) if you have questions. + +## What are the supported ciphers ? + +As this information can change over time with security updates, here's the nmap command to look up SSL/TLS ciphers on a Clever Cloud configured domain: + +```shell +nmap --script ssl-enum-ciphers -p 443 example.com +``` + +## I'd like to have two applications available on the same domain name + +Refer to [prefix routing](/developers/doc/administrate/domain-names/#prefix-routing) to learn how to have two applications share a domain name. + +## How do I define cron jobs for my application? + +See [Cron Configuration File](/developers/doc/administrate/cron) for more information. + +## How to know if a user comes from a secure connection? + +Load-balancers handles all connections ahead of your applications and forward them in plain HTTP, you can't rely on the server port to know the scheme used by the user. + +Instead, you can use the `X-Forwarded-Proto` HTTP header to get the information, it's set to either '_http_' or '_https_'. + +{{< callout type="info" >}} +In order to use `request.secure` instead of using the header, you must add `XForwardedSupport=all` in your `application.conf`. +{{< /callout >}} + +{{< callout type="warning" >}} +In order to use `request.secure` instead of accessing the header, you must add `trustxforwarded=true` in your `application.conf`. +{{< /callout >}} + +## PHP: `$_SERVER` auth variables are always empty, how do I make this work? + +- [Lean more about the $_SERVER variable on Clever Cloud](/developers/doc/applications/php/#using-http-authentication) + +## How to get the user's IP address? + +Load-balancers ahead of your applications handle all connections and forward them in plain HTTP. +So if you get the `REMOTE_ADDR` or `Client-IP` header, you get only the IP of the load balancer that forwarded the user request. + +To get the original client's IP address, use the `X-Forwarded-For` HTTP header. The load balancer automatically adds this header to each request. + +The `X-Forwarded-For` header contains a comma-separated list of IP addresses. The first address in this list is your end user's original IP address. Any subsequent addresses represent the proxies that the request passed through before reaching your application. +[Read the Wikipedia page for more details](https://en.wikipedia.org/wiki/X-Forwarded-For). + +## How do I identify different instances of my application? + +If your application needs to differentiate all the running nodes internally, you can use the `INSTANCE_NUMBER` environment variable. + +For example, if 3 instances are running for your application, this environment variable will contain `0` on the first, `1` on the second and `2` on the third. + +## I need a private ssh key to fetch my private dependencies. How do I do that? + +If your company manages its own artifacts in a private repository (like, you can only +access them via git+ssh or sFTP), and you need a private key to connect to the server, you +can commit them in your application's Clever Cloud repository and then add a +`clevercloud/ssh.json` file. + +- [Learn more about ssh.json](/developers/doc/reference/common-configuration/#private-ssh-key) + +## I get a `java.lang.UnsupportedClassVersionError: Unsupported major.minor version` error. How can I fix it? + +If you get this error on a Java (or any JVM language) application, it means that your application was compiled with a newer Java version than the one used to run it. + +As an example, if a Spring Boot application was compiled with Java `17` and run with Java `11`, the following error occurs: + +```bash +java.lang.UnsupportedClassVersionError: org/springframework/boot/loader/JarLauncher has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0 +``` + +By default, Java apps on Clever Cloud use Java `11`, but you can change it. Please head [over here](/developers/doc/applications/java/java-jar/#available-java-versions "Java versions") for more information. + +For reference, the table below lists the class file version for each major Java version ([official doc](https://docs.oracle.com/javase/specs/jvms/se21/html/jvms-4.html)) : + +| Java version | Class file version | +| ------------ | ------------------ | +| 7 | 51.0 | +| 8 | 52.0 | +| 11 | 55.0 | +| 17 | 61.0 | +| 21 | 65.0 | + +## I want SSH access to my server + +Clever Cloud does not give you access to a server or a VPS, it makes your application run. Each instance is started and configured automatically, and can be stopped at any moment. + +If however, you still need SSH access for debugging purposes, please have a look at [SSH access](/developers/doc/cli/applications/deployment-lifecycle/#ssh), but keep in mind that changes made on an instance are not persistent across deployments. + +## I want to user Clever Cloud on my own premises, is that possible? + +Yes, since 2016 Clever Cloud is packaged for private data center. This offer called "Clever Cloud On Premises" is available upon request: you can send a mail to [sales@clever-cloud.com](mailto:sales@clever-cloud.com) or visit [https://www.clever-cloud.com/on-premises](https://www.clever-cloud.com/on-premises) for more info. + +## Where are my applications and add-ons located? + +Applications and add-ons are located in either _Paris, France_ or _Montreal, Canada_. You can choose where you want it to be when you create an application +and a Clever Cloud add-on. + +Clever Cloud is based in Nantes, France. + +## I want to run Kubernetes on top of Clever CLoud, is that possible? + +It's currently not possible to use Kubernetes on our platform. It is however on our Roadmap. + +## How to setup a firewall on Clever Cloud? + +Specific firewall rules can be enabled on demand to the support or in case of attack. + +## Can I `scp` something in a VM + +You cannot `scp` something to the VM, you can however easily `scp` something from the VM to the outside. + +## I need to convert something to PDF with `wkhtmltopdf` + +`wkhtmltopdf` is available and fully functional but we deeply recommend to use `chromium headless` instead. + +## What is the timezone used by my application/add-on? + +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. + +## I received an email saying "Add-on [my add-on] disk is nearly full". What do I do? + +A full disk can cause your database to crash or become unresponsive. +Consider upgrading your add-on plan. +You might want to do one of the following: + +### Remove data from your database + +You can take a snapshot of your database and export the obsolete data to a cold storage. +Then you can remove records from your database, re-index your tables and try to perform a VACUUM operation if the database software allows it. + +### Migrate your add-on to a bigger plan + +… or to the same plan. + +You can buy more disk space by migrating your add-on to a higher plan. +If a VACUUM operation needs more disk that there is remaining, migrating to the same plan cleans up the file on disk and regains space. + +## Where are the backups stored? + +Clever Cloud stores all backups on [Cellar](https://www.clever-cloud.com/product/cellar-object-storage/), a replicated object storage service with three copies distributed across datacenters in the PAR region to ensure durability. Even if one datacenter fails, your backups remain safe. + +For custom configurations (for example, multiple retention policies), contact Support. To locate backups not visible in the Console, use [Clever Tools](https://github.com/CleverCloud/clever-tools) with: `clever database backups DATABASE-ID [--format, -F] FORMAT`. Find more [documentation on restoring backups with the CLI](/developers/doc/cli/addons/#database-backups). + + +## I can't create my add-on + +To create add-ons, you need to complete your account information, including your city and ZIP code. +For instance, you cannot create a Matomo add-on until you provide these details. + +## I get unknown regular requests, is there a problem ? + +The platform performs routine health checks to applications every 2 minutes. You may notice these periodic HTTP requests in your logs, with `X-Clevercloud-Monitoring` header. They're part of Clever Cloud's standard monitoring process. + +## What is a DEV plan ? + +DEV plan is a free-tier plan available for some databases, designed to let customers explore and test these products. They operate on shared clusters, which may result in variable performance; they also have no SLA guarantees. + +Some features such as simultaneous connections numbers, functions… might be reduced or unavailable. + +Support is not able to provide help in case of DEV plan. + diff --git a/content/doc/find-help/support.md b/content/doc/find-help/support.md new file mode 100644 index 000000000..ab40a217b --- /dev/null +++ b/content/doc/find-help/support.md @@ -0,0 +1,38 @@ +--- +type: docs +title: Support +weight: 7 +description: We provide basic support free-of-charge to all our users, here's how to reach us +tags: +- help +keywords: +- support +aliases: +- /doc/get-help/support +- /doc/support +- /support +--- + +We provide basic support free-of-charge to all our users, even those who are not paying customers. + +## Email + +Seek help by querying us by email, allowing you to quickly gain answers to your Clever Cloud specific questions and open a ticket directly with our support staff. We will respond to your email within a few hours, or two business days in the worst case. + +* + +## Ticket Center + +You can find in the console a button to [start a conversation](https://console.clever-cloud.com/ticket-center-choice) with our engineers. For each new ticket it will create a new thread, on a specific subject. Therefore, you can create several tickets for each issue. + +If you open a ticket inside an organisation with members, they will be added to the discussion by e-mail. + +Feel free to use it when this service available, from 9 a.m to 6 p.m CEST+2 during open business days. + +## Critical application support + +Clever Cloud offers a premium support option providing 24/7 a direct line to our team of support engineers. Our team’s focus is investigating and solving new problems, getting feedback on the service and working hard to improve the core service. + +Get more information and contact our sales team at: + +* diff --git a/content/doc/find-help/troubleshooting.md b/content/doc/find-help/troubleshooting.md new file mode 100644 index 000000000..6674414f5 --- /dev/null +++ b/content/doc/find-help/troubleshooting.md @@ -0,0 +1,212 @@ +--- +type: docs +title: Troubleshooting +description: Common issues and errors you may have +tags: +- help +keywords: +- support +- git issues +- troubleshoot +aliases: +- /doc/get-help/troubleshooting +--- + +{{< hextra/hero-subtitle style="margin:.3rem 0 2rem 0">}} + If you're having trouble deploying applications or with with git, this section is for you. From git issues to configuration errors, problems can arise at different stages of your deployments. +{{< /hextra/hero-subtitle >}} + +## Git-related issues + +{{% details title="Some files disappear after an application restart" closed="true" %}} + +Clever Cloud use Git to transfer your code and application's assets from your local host to your scaler. If your application writes files on the local file system, those files are not committed: so you can't save these files from a instance to an other. + +For most of Cloud providers, the use of the file system is not a good practice. But we know it could be sometimes pretty useful. That's why we provide an on-demand file system, easily pluggable to your app. In that case, your files will not be stored on the Git file system, but on a clustered file system, dedicated to it, accessible via FTP. This is the FS Bucket add-on. + +Follow the [File System buckets documentation page](/developers/doc/addons/fs-bucket) to set up an FS Bucket for your application. +{{% /details %}} + +{{% details title="Empty repository git error" closed="true" %}} + +In some cases, git may display this type of error message: + +```text +Cloning into 'project'... +warning: You appear to have cloned an empty repository. +Checking connectivity... done. +``` + +This usually means that you created an application and asked to start it in the console without having pushed any source code to it before. + +Under the Clever Cloud console, in your application's information menu you will find a deployment url. Add it to your local repository git remotes with `$ git remote add clever `. +You can now push your commits to the new remote with `$ git push clever master`. + +It may also be because you are working on another branch than master and pushed this specific branch to Clever Cloud and you encountered this error: + +```bash +remote: You tried to push to a custom branch. +remote: This is not allowed. +remote: error: hook declined to update refs/heads/ +… +error: failed to push some refs to '' +``` + +Clever Cloud uses the master branch to deploy your application but this does not mean that you cannot use another one on your computer. +What differs if you use another branch than master on your computer is that you need to explicitly tell Clever to consider the specific branch as the master one. + +```bash +git push :master +``` + +If you called the Clever Cloud remote `clever` and your local branch is `production`, this becomes + +```bash +git push clever production:master +``` + +{{% /details %}} + +{{% details title="'Not a git repository' error" closed="true" %}} + +```text +fatal: Not a git repository (or any of the parent directories) +``` + +This means that the folder in which you are is not a git repository. +In your console, at the root of your project, type `$ git init`. This will create a new git repository for your folder locally. Link it to Clever Cloud by going under the Clever Cloud console. In your application's information menu you will find a deployment url. Add it to your local repository git remotes with `$ git remote add clever `. +You can add all your files with `$ git add .`, then you need to commit the files with `$ git commit -m ""`. +You will finally push your code with `$ git push clever master`. +{{% /details %}} + +{{% details title="'fatal: 'clever' does not appear to be a git repository'" closed="true" %}} + +"clever" is a name used in our examples to represent the Clever Cloud servers. +In order to be able to use the same name for yourself, you will need to create a git remote named clever like this: + +```shell +git remote add clever +``` + +You can find your deployment url under the Clever Cloud console in your application's information menu. +{{% /details %}} + +{{% details title="Fail to push to a repository" closed="true" %}} + +It might be because your SSH agent is not properly configured. Please check [the SSH documentation page](/developers/doc/account/ssh-keys-management#i-maybe-have-ssh-keys-i-want-to-check). +{{% /details %}} + +## Deployments issues + +{{% details title="Activating the troubleshooting mode" closed="true" %}} + +Sometimes, when something goes wrong during the deployment, it can be hard to find out what happens. The troubleshoot mode allows you to keep the instances up while you find out what has happened. +Additionally, the troubleshoot mode increases the overall verbosity of the deployment process. + +To enable this mode, simply add `CC_TROUBLESHOOT=true` to your environment variables. + +{{% /details %}} + +{{% details title="Node application failed to deploy silently" closed="true" %}} + +This kind of silent error may be due to the server port your have setup in your application. Make sure your application is listening on port 8080. +Most of the time, this simple line could do the trick in your main JS file: + +```javascript +// Listen on port 8080 +server.listen(8080); +``` + +{{% /details %}} + +## Moderation + +{{% details title="What is moderation?" closed="true" %}} + +Moderation means your account is not accessible anymore. You might have broken some important rules of Clever Cloud's General Terms of Use. + +You are not allowed to create apps and add-ons, and run your current apps. + +{{% /details %}} + +{{% details title="Possible reasons why your app has been moderated" closed="true" %}} + +The main reasons why your account has been moderated are: +- You run some forbidden apps such as those described on [this page](https://www.clever-cloud.com/acceptable-use-policy/) +- You have not paid your pending invoices older than 30 days +- Clever Cloud system considers the lack of personal information or missing payment information as suspicious +- Our payment platform has spotted you as emitting fraudulent payments. + +{{% /details %}} + +{{% details title="How to recover your application online?" closed="true" %}} + +Contact [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice) to explain what your apps do. + +Ensure all your pending invoices are paid. + +{{% /details %}} + +{{% details title="How to recover your data?" closed="true" %}} + +In case of a pending invoice aged more than 30 days, Clever Cloud might delete your apps and add-ons. However, we keep backups for 30 days after deletion. + +You have to pay all of your pending invoices to recover your data. + +{{% /details %}} + +## Network + +{{% details title="Backend Timeout Limits" closed="true" %}} + +Clever Cloud uses [Sōzu](https://www.sozu.io) as its load balancer and reverse proxy. Sōzu enforces a 180-second timeout for all backend operations to prevent resource exhaustion from hanging requests. + +For operations that may exceed the 180-second limit, implement one of these approaches: + +1. Use long polling to send periodic status checks from the client +2. Create an asynchronous worker system: move long-running tasks to a background [worker](/developers/doc/develop/workers/) +3. [Purchase a custom load balancer from Clever Cloud](https://www.clever-cloud.com/fr/contact/) with different timeouts + +##### Additional considerations: + +- Design your application architecture to handle timeouts gracefully +- Break up long-running operations into smaller tasks + +Use your embedded [Grafana](/developers/doc/metrics/) to monitor resource usage when implementing any of these solutions. + +##### How can I diagnosing Network Issue with `curl` + +To gather detailed timing information for each step of the connection process, run the following `curl` command: +``` bash +curl -o /dev/null -s -w "DNS resolution: %{time_namelookup}s\nTCP connection: %{time_connect}s\nTLS handshake: %{time_appconnect}s\nTime to first byte: %{time_starttransfer}s\nTotal time: %{time_total}s\n" https:// +``` + +{{% /details %}} + +## Others issues + +{{% details title="Missing GitHub organisation on the application creation page" closed="true" %}} + +GitHub does not give us access to organisations created or joined *after* you've linked your GitHub account to Clever Cloud (which is a good thing). So you need to let the Clever Cloud API access it. You can do that on . + +Feel free to reach to [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice) if this page wasn't helpful enough. + +{{% /details %}} + +{{% details title="My application is not accessible for an unknown reason" closed="true" %}} + +Check the status of the services on [clevercloudstatus.com](https://www.clevercloudstatus.com/). The support team is also there to help you identify any potential errors or misconfiguration. +{{% /details %}} + +{{% details title="There are a lot of open ports, according to a port scan." closed="true" %}} + +If you tried to scan your domain, you may not only have scanned your app, but also several public load balancers. +Here is an explanation of the different port you may see. + +- Port 9999 : [Zabbix](https://www.zabbix.com) uses this port to monitor the hypervisor. +- Ports 5000 to 6000 : The TCP redirection feature uses these ports to work. If you notice a port within this range open but haven't enabled the feature, it indicates that another app on the same hypervisor is using it. The load balancer assigns a unique port to each app, ensuring that your app is securely isolated. You can be assured that other users can't access your app through this port. +- Port 3000 : Juggernaut, the daemon torrent for the VM images use this port. +- Ports 1080 and 1081 : Those are necessary for the reverse-proxy Sōzu to be able to redirect traffic to your application. Port 1080 is for HTTP and 1081 for HTTPS +- Port 80 and 443 : Your app use these ports to receive HTTP and HTTPS traffic + +{{% /details %}} diff --git a/content/doc/marketplace.md b/content/doc/marketplace.md new file mode 100644 index 000000000..2b5d26c7c --- /dev/null +++ b/content/doc/marketplace.md @@ -0,0 +1,376 @@ +--- +type: docs +title: Marketplace APIs & Tools +weight: 13 +description: How to integrate your own service as an add-on on Clever Cloud's Marketplace +keywords: +- Add-on +- API +- Marketplace +- Partners +aliases: +- /doc/extend/addon-api/ +- /doc/extend/add-ons-api/ +- /marketplace +comments: false +--- + +Clever Cloud allows its Marketplace partners to provide services as add-ons with revenue sharing. Thus, they can be available to purchase and provision from the [Console](https://console.clever-cloud.com), [Clever Tools](https://github.com/CleverCloud/clever-tools), the [API](/developers/api) or other integrations such as the [Terraform provider](https://registry.terraform.io/providers/CleverCloud/clevercloud/). + +You want to help us to offer more services to our users? [Contact us](https://partners.clever-cloud.com). Then, you will be able to use our dedicated tools and APIs to provide your service as an add-on, whether they're hosted on Clever Cloud or not. + +* [Add-on Manifest](#add-on-manifest): to provide your service as an add-on +* [Add-on provider requests](#add-on-provider-requests): to provision, modify or delete add-ons +* [Add-on infos API](#add-on-infos-api): to list provisioned add-ons and get detailed information about them + +## Add-on Manifest + +First, provide a JSON manifest file that describes your add-on: + +```json +{ + "id": "addon-name", + "name": "Addon Name", + "api": { + "config_vars": [ "ADDON_NAME_MY_VAR" ], + "regions": [ "eu" ], + "password": "", + "sso_salt": "", + "production": { + "base_url": "https://yourservice.com/clevercloud/resources", + "sso_url": "https://yourservice.com/clevercloud/sso/login" + }, + "test": { + "base_url": "http://localhost:9000/clevercloud/resources", + "sso_url": "http://localhost:9000/clevercloud/sso/login" + } + } +} +``` + +### Available fields + +* `id` - An ID for your add-on. All lower case, no spaces or punctuation. Underscores and dashes are allowed. This can’t be changed after the first push. It is also used for HTTP basic auth when making provisioning calls. +* `name` (Optional) - A human-readable name for your add-on. You will be able to change it later in the dashboard, so you don't even have to provide it right now. +* `api/config_vars` - A list of configuration variables that will be returned on provisioning calls. Each `config_var` name must start with the capitalized, add-on id with underscores, as in the example. +* `api/password` - Password that Clever Cloud will send in HTTP basic auth when making provisioning calls. You should generate a long random string for that field. +* `api/sso_salt` - Shared secret used in single sign-on between the Clever Cloud admin panel and your service’s admin panel. You should generate a long random string for that field. +* `api/regions` - The list of geographical zones supported by your add-on. It cannot be empty. As for now, it *MUST* contain the element "eu". More will be supported. +* `api/production/base_url` - The production endpoint on which Clever Cloud sends actions requests (provision and deprovision). +* `api/production/sso_url` - The production endpoint for single sign-on. +* `api/test/base_url` - The test endpoint on which Clever Cloud sends actions requests. Used to test your service when you create an add-on provider. After the add-on creation,`api/production/base_url` is used. +* `api/test/sso_url` - The test endpoint for single sign-on. Used to test your service when you create an add-on provider. After that, the `api/production/sso_url` is used. + +## Add-on Provider requests + +When a Clever Cloud's customer interacts with your add-on, you'll receive requests on your `base_url` API endpoint. The following sections describe the requests you'll receive and the responses you should send. + +### Provisioning + +When a customer installs your add-on, Clever Cloud issues a POST request to your service to provision a resource for his app. + +Clever Cloud will send the following request: + +```json +Request: POST {base_url} +Request Body: { + "addon_id": "addon_xxx", + "owner_id": "orga_xxx", + "owner_name": "My Company", + "user_id": "user_yyy", + "plan": "basic", + "region": "EU", + "callback_url": "https://api.clever-cloud.com/v2/vendor/apps/addon_xxx", + "options": {} +} +Response Body: { + "id": "myaddon_id", + "config": { + "ADDON_NAME_MY_VAR": "some value" + }, + "message": "Some provisioning message" +} +``` + +The request body contains the following fields: + +* `addon_id` - The id we give to your add-on to identify it on our side. +* `owner_id` - The id of the customer this add-on will belong to. +* `owner_name` - The name of the customer. (Actually, the name of the organisation) +* `user_id` - The id of the user that is performing the action of provisioning this + add-on. (The user will do it for the account of `owner_id`). +* `plan` - The slug field for the plan the user chose. You can create +plans in the dashboard once your add-on manifest has been uploaded to +the Clever Cloud platform. We send you the slug of the given plan, +not its name. +* `region` - The region to provision the add-on. As for now, only "EU" will be sent. +* `callback_url` - The URL you can use to get details about the add-on and the user. This URL is available as soon as the provisioning is done. You can't use this URL during the POST call. +* `options` - String -> String map with options. +The response body contains the following fields: +* `id` - The add-on id as seen from your side. It *MUST* be a String. +* `config` (Optional) - A String -> String map with value for each config\_var defined in your manifest. A key that is not in your config\_vars will be ignored. +* `message` (Optional) - A creation message we will display in the dashboard. + +### De-provisioning + +When a customer deletes your add-on, Clever Cloud issues a DELETE request to your service to de-provision a resource for his app. + +The request will be the following: + +```json +Request: DELETE {base_url}/{addon_id} +Request Body: none +Response Status: 200 +``` + +* `addon_id` - This is the same as the `id` field set in the response to the provisioning call. + +### Examples + +You can find templates for add-on providers in various languages on GitHub: + +* [Node.js](https://github.com/Redsmin/passport-clevercloud) +* [Scala with Play! Framework 2](https://github.com/CleverCloud/addon-provider-template) + +## Add-on Infos API + +This is the API Clever Cloud provides to allow you to list provisioned add-ons and get detailed information about them. + +```bash +curl -XGET https://api.clever-cloud.com/v2/vendor/apps -u addon-name:44ca82ddf8d4e74d52494ce2895152ee +``` + +### List all add-ons provided by you + +```json +GET /vendor/apps +Response Body: [ + { + "provider_id": "addon-name", + "addon_id": "addon_xxx", + "callback_url": "https://api.clever-cloud.com/v2/vendor/apps/addon_xxx", + "plan": "test", + "owner_id": "user_foobar" + }, { + "provider_id": "addon-name", + "addon_id": "addon_yyy", + "callback_url": "https://api.clever-cloud.com/v2/vendor/apps/addon_yyy", + "plan": "premium", + "owner_id": "orga_baz" + } +] +``` + +* `provider_id` - Should be the same as the "id" field of your uploaded manifest. + +* `addon_id` - The add-on's id from Clever Cloud's POV. + +* `callback_url` - URL to call to get more details about this add-on. + +* `plan` - The current plan of this add-on. + +* `owner_id` - The id of the owner that provisioned the add-on. This should never change. + +### Get information about a specific add-on + +**Caution**: this endpoint is **not** available during the provisioning call. If you want +information, you need to reply to the provisioning call, **then** you can call this +endpoint. + +```json +GET /vendor/apps/{addonId} +Response Body: { + "id": "addon_xxx", + "name": "My addon-name instance", + "config": {"MYADDON_URL": "http://myaddon.com/52e82f5d73"}, + "callback_url": "https://api.clever-cloud.com/v2/vendor/apps/addon_xxx", + "owner_email": "user@example.com", + "owner_id": "orga_baz", + "owner_emails": ["user@example.com", "foobar@baz.com"], + "region": "eu", + "domains": [] +} +``` + +This endpoint gives you more information about a provisioned add-on. + +* `id` - The add-on id from Clever Cloud's POV. + +* `name` - The name the user gave to this add-on in the Clever Cloud dashboard. + +* `config` - Configuration variables as you defined during the provision call. + +* `callback_url` - The URL you just called. + +* `owner_email` - One of the owner's email address. + +* `owner_emails` - All the owner's email addresses. + +* `owner_id` - The id of the owner that provisioned the add-on. This should never change. + +* `region` - The region this add-on is located in. As for now, only "eu" is supported. + +* `domains` - Originally the domains names for the application owning the add-on. We return an empty list. + +### Update the configuration variables for an add-on + +```json +PUT /vendor/apps/{addonId} +Request Body: { + "config": { + "ADDON_NAME_URL": "http://myaddon.com/ABC123" + } +} +Response Status: 200 OK +``` + +The object should only contain the `config` object your API returned +during the provisioning. + +{{< callout type="info" >}} +This endpoint is **not** available during the provisioning call. You need to reply to the provisioning call, **then** you can call this endpoint. +{{< /callout >}} + +### Sample code + +```python +#!/usr/bin/env/python +# -*- coding:utf-8 -*- + +""" +api.py +""" +from flask import Flask, redirect, Response, jsonify, request +import auth +import provision + +app = Flask(__name__) + +@app.route('/') +def index(): + """ + Render the home template + """ + return redirect("https://google.com/") + +@app.route('/clevercloud/resources', methods=['POST']) +@auth.requires_auth +def clevercloud_create_resource(): + data = request.json + msg = provision.add(**data) + return jsonify(msg) + +@app.route('/clevercloud/resources/', methods=['DELETE','PUT']) +@auth.requires_auth +def clevercloud_action_resource(id): + data = request.json + if request.method == 'POST': + msg = provision.del(id,**data) + + if request.method == 'PUT': + msg = provision.update(id,**data) + + return jsonify(msg) + +@app.route('/clevercloud/sso/login') +def clevercloud_sso_login(): + return Response(status=200) + +if __name__ == "__main__": + app.run(host='0.0.0.0',port=9000,debug=True) +``` + +## Authentication + +To secure the calls to the API, please provide a HTTPS connection and use a Basic authentication. The username must be your provider ID (`addon-name` in our example). The password must be the `password` value set in your manifest. + +Your provider API must check that all calls to it are authenticated with this user/password combination. If the authentication fails, you should return a 401 HTTP status code. + +### Sample with Flask in Python + +```python +from functools import wraps +from flask import request, Response + + +def check_auth(username, password): + """This function is called to check if a username / + password combination is valid. + """ + return password == '' + +def authenticate(): + """Sends a 401 response that enables basic auth""" + return Response( + 'Could not verify your access level for that URL.\n' + 'You have to login with proper credentials', 401, + {'WWW-Authenticate': 'Basic realm="Poney required"'}) + +def requires_auth(f): + @wraps(f) + def decorated(*args, **kwargs): + auth = request.authorization + if not auth or not check_auth(auth.username, auth.password): + return authenticate() + return f(*args, **kwargs) + return decorated +``` + +## SSO + +Your service probably has a web UI admin panel that your users log into to manage and view their resources. +Clever Cloud customers will be able to access the admin panel for their resource if you implement single sign-on (SSO). + +Clever Cloud will generate a single sign-on signature by combining the salt (a shared secret you defined in your manifest) with the rest of the body (see below). +Clever Cloud redirects the user’s browser to your SSO URL with this signature. +Your site can confirm the authenticity of the signature, then set a cookie for the user session and redirect them to the admin panel for their resource. + +When the user opens your add-on dashboard in their add-on menu, they will be directed via HTTP POST to the SSO URL defined in your manifest. + +```http +POST +Content-Type: application/x-www-form-urlencoded + +id=×tamp=&nav-data=&email=&user_id=&signature= +``` + +* The hostname or `sso_url` comes from your add-on manifest +* The `id` is the ID for the previously provisioned resource +* The `timestamp` is a millisecond timestamp. You *SHOULD* verify that it's not older than a few minutes (like 5) +* The `user_id` is a unique string identifying the current user on the Clever Cloud platform +* The `email` is the current primary email of the current user on the Clever Cloud platform +* The `nav-data` contains information like the current app name and installed add-ons for Clever Cloud's Console. At the time of writing this doc, this field is always empty +* The `signature` is computed using the formula below + +### Token + +The `signature` field in the SSO call is created as follows: + +```javascript +sha512sum(id + ':' + user_id + ':' + email + ':' + nav-data + ':' + sso_salt + ':' + timestamp) +``` + +Where `sso_salt` is the shared secret you defined while registering in the marketplace. +The other fields are the url-decoded fields previously enumerated. + +### Sample in Python + +```python +from hashlib import sha512 +import time + +id = "1234" +salt = "" +user_id = "user_cccdddee-efff-4445-5566-6777888999aa" +email = "me@my.self" +nav_data = "" +timestamp = str(time.time()) +sig = sha512((id + ':' + user_id + ':' + email + ':' + nav_data + ':' + sso_salt + ':' + timestamp).encode("utf-8")).hexdigest() +print sig +``` + +This code returns: + +```python +'2a79420ccb4dccb2f18985da60393d1383d4ef4ac02cef3274a543bb3fe82d15e5dee19cbca753e8eac24e6383d332ef258daea6ea3340c3526af175329e7dd8' +``` diff --git a/content/doc/metrics/_index.md b/content/doc/metrics/_index.md new file mode 100644 index 000000000..cd40bf088 --- /dev/null +++ b/content/doc/metrics/_index.md @@ -0,0 +1,471 @@ +--- +weight: 4 +type: docs +title: Metrics +description: Access and manage metrics on Clever Cloud +tags: +- app +- add-on +- metrics +keywords: +- grafana +- warp10 +aliases: +- /administrate/metrics/overview/ +- /doc/administrate/metrics +- /doc/administrate/metrics/overview +- /doc/tools/metrics +- /metrics +comments: false +--- +{{< callout type="warning" >}} +Clever Cloud Metrics is still in beta. +{{< /callout >}} + +In addition to logs, you can have access to metrics to know how your application behaves. +By default, system metrics like CPU and RAM use are available, as well as application-level metrics when available (apache or nginx status for instance). + +## Display metrics + +For each application, there is a `Metrics` tab in the console. + +### Overview pane + +To get a quick overview of the current state of your scalers, the overview pane +displays the current CPU, RAM, Disk and Network activity. On supported platforms, +you can also have access to requests / second, and GC statistics. + +![Overview pane on Grafana](/images/grafana-from-oveview-pane.png "Direct link from Overview pane to app dashboard in Grafana") + +### Advanced pane + +Advanced metrics allow you to access all gathered metrics, +on a specified time range. + +### Custom queries + +All metrics are stored in [Warp 10](/developers/doc/metrics/warp10), so you can explore data directly with the [quantum](/developers/doc/metrics/warp10) interface, with [WarpScript](https://www.warp10.io/doc/reference). + +For instance, you can derive metrics over time, do custom aggregations or combine metrics. + +### Get alerts + +You can set up alerts in Grafana to be notified on your apps and add-ons consumption. This can be useful to monitor databases capacity or latency. + +![Alert option](/images/grafana-alerts.png "Alert option from the general menu in Grafana") + +For example, check [this tutorial on how to create Slack alerts with Grafana](https://www.clever-cloud.com/blog/features/2021/12/03/slack-alerts-for-grafana/). + +## Access Logs metrics + +All your applications access logs are pushed to [Warp 10](/developers/doc/metrics/warp10). You are now able to process them directly in the console in the Metrics tab of your applications. + +### Request rate + +We provide a request rate metric. It is an average of the access logs request count over 1 minute. It is updated every 30 second. + +This can be reached using the Warp 10 class: `request_rate`. + +> There are the same labels than for others metrics ([see monitoring-metrics](/developers/doc/administrate/metrics/overview/#monitoring-metrics)) + +### Access Log data model + +Access logs are defined in the `'accessLogs'` Warp 10 class and there are three Warp 10 labels available: + +- `owner_id`: Organisation ID +- `app_id` : Application ID (ex: `app_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx` ) or Add-on ID (ex: `postgresql_xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx`) +- `adc` or `sdc` + - `adc` (Application Delivery Controller) are used for HTTP connections + - `sdc` (Service Delivery Controller) are used for TCP connections + +> Available add-ons for the field `addon_id` are mysql, redis, mongodb and postgresql add-ons. + +{{< callout type="warning" >}} +Add-ons on shared plans (usually DEV plans) do not provide access logs. There are no recorded access logs in case of a direct access to an add-on +{{< /callout >}} + +To reduce space used to store access logs, we defined the following key-value models. + +#### Key-Value model for applications + +AccessLogs data models for application. Using HTTP protocol. + +```txt +t -> timestamp +a -> appId or addonId +o -> ownerId +i -> instanceId +ipS -> ipSource +pS -> portSource # 0 if undefined +s -> source + lt -> latitude + lg -> longitude + ct -> city + co -> country +ipD -> ipDestination +pD -> portDestination # 0 if undefined +d -> destination + lt -> latitude + lg -> longitude + ct -> city + co -> country +vb -> verb +path -> path +bIn -> bytesInt +bOut -> bytesOut +h -> hostname +rTime -> responseTime +sTime -> serviceTime +scheme -> scheme +sC -> statusCode +sT -> statusText +tS -> Haproxy termination_state +adc -> Reverse proxy hostname +w -> workerId (Sozu) +r -> requestId (Sozu) +tlsV -> tlsVersion (Sozu) +``` + +#### Key-Value model for add-ons + +AccessLogs data models for add-ons. Using TCP protocol. + +```txt +t -> timestamp +a -> appId or addonId +o -> ownerId +i -> instanceId +ipS -> ipSource +pS -> portSource # 0 if undefined +s -> source + lt -> latitude + lg -> longitude + ct -> city + co -> country +ipD -> ipDestination +pD -> portDestination # 0 if undefined +d -> destination + lt -> latitude + lg -> longitude + ct -> city + co -> country +tS -> Haproxy termination_state +sdc -> Reverse proxy hostname +sDuration -> total session duration time in millis +``` + +### Queries examples + +The main ways to use `accessLogs` data is to `FETCH` over it and get interesting values by a JSON processing. + +{{< callout type="info" >}} +Look at *fetch_accessLogs_key_v0* macro to have a convenient way to explore access log data, see [Warp 10 documentation](/developers/doc/metrics/warp10). +{{< /callout >}} + + +```text +// Fetch on the 'accessLogs' class for your application id as labels +[ '' 'accessLogs' { 'app_id' '' } NOW 30 s ] FETCH + +// get the path field +<% + DROP + VALUES + <% DROP + JSON-> + 'path' GET + %> LMAP +%> LMAP +FLATTEN + +// distinct|unique results +UNIQUE +``` + +A convenient way to integrate the intercepted data in a workflow is to use [WarpScript](https://www.warp10.io/content/03_Documentation/04_WarpScript/). It is a good idea to use the GTS format to be able to apply all GTS transformation on the output. + +In the following example, we get the `accessLogs` status codes and create a GTS as an output to be able to use FILTER or any other transformation on it a second time. + + +```text +// Get all application status code for the last hour +[ '' 'accessLogs' { 'app_id' '' } NOW 10 m ] FETCH +<% + DROP + 'gts' STORE + // output new GTS + NEWGTS + $gts + <% + DUP + // store the timestamp + 0 GET 'ts' STORE + // store the status code + -1 GET JSON-> 'sC' GET 'sC' STORE + // Keep the same labels in the output GTS than in the input ones + $gts LABELS RELABEL + // Add timestamp and status code value to the output GTS + [ $ts NaN NaN NaN $sC ] ADDVALUE + %> + FOREACH +%> LMAP +``` + +An example using the provided Clever Cloud macro to straightforward access to the access logs input byte : + +```txt +'' { 'app_id' 'id' } 'bIn' NOW 1 h @clevercloud/fetch_accessLogs_key_v0 +``` + +or to get the latitude of the destination, which is a nested data: + +```txt +'' { 'app_id' 'id' } 'd.lt' NOW 1 h @clevercloud/fetch_accessLogs_key_v0 +``` + +## Monitoring' metrics + +All applications and VMs instances behind are monitored. Data is sent to [Warp 10](/developers/doc/metrics/warp10), a Geotimes series database. +All metrics can be processed directly in the console in the Metrics tab of your applications or by the Clever Cloud Warp 10 endpoint. + +### Monitoring data model + +All metrics data follow the same schema in warp 10. +Each class represents a specific metric. The context is provided by the Warp 10 labels. + +#### Class values and Labels + +##### Overview + +A telegraf daemon supplies most metrics. + +Each metric is recorded as a Warp 10 class. +Labels provide additional information about the VMs like instances id, organisation id, reverse proxy used. + +##### Labels + +In metrics' data, mains labels would be : + +- `owner_id` : A unique ID by organisation +- `app_id` : A unique ID of application +- `host` : HV id hosting the VM instance +- `adc` : Reverse proxy ID for http connexion (ie: applications) +- `sdc` : Reverse proxy ID for tcp connexion (ie: add-ons) +- `vm_type` : `volatile` or `persistent`. Is it a stateless application or a stateful add-on +- `deployment_id` : ID of the deployment + +{{< callout type="warning" >}} +For some specific metrics. Some labels could miss. +{{< /callout >}} + +##### Classes + +Telegraf provide lots of metrics described in their [documentation](https://github.com/influxdata/telegraf/tree/master/plugins/inputs). + +Below, the list of all Warp 10 classes representing Telegraf metrics : + +| Metric | Metric | +| ----------------------------------- | ----------------------------------- | +| conntrack.ip_conntrack_count | mem.swap_free | +| conntrack.ip_conntrack_max | mem.swap_total | +| cpu.usage_guest | mem.total | +| cpu.usage_guest_nice | mem.used | +| cpu.usage_idle | mem.used_percent | +| cpu.usage_iowait | mem.vmalloc_chunk | +| cpu.usage_irq | mem.vmalloc_total | +| cpu.usage_nice | mem.vmalloc_used | +| cpu.usage_softirq | mem.wired | +| cpu.usage_steal | mem.write_back | +| cpu.usage_system | mem.write_back_tmp | +| cpu.usage_user | net.bytes_recv | +| disk.free | net.bytes_sent | +| disk.inodes_free | net.drop_in | +| disk.inodes_total | net.drop_out | +| disk.inodes_used | net.err_in | +| disk.total | net.err_out | +| disk.used | net.packets_recv | +| disk.used_percent | net.packets_sent | +| http_response.http_response_code | net_response.response_time | +| http_response.response_time | net_response.result_code | +| http_response.result_code | net_response.result_type | +| http_response.result_type | netstat.tcp_close | +| kernel.boot_time | netstat.tcp_close_wait | +| kernel.context_switches | netstat.tcp_closing | +| kernel.entropy_avail | netstat.tcp_established | +| kernel.interrupts | netstat.tcp_fin_wait1 | +| kernel.processes_forked | netstat.tcp_fin_wait2 | +| mem.active | netstat.tcp_last_ack | +| mem.available | netstat.tcp_listen | +| mem.available_percent | netstat.tcp_none | +| mem.buffered | netstat.tcp_syn_recv | +| mem.cached | netstat.tcp_syn_sent | +| mem.commit_limit | netstat.tcp_time_wait | +| mem.committed_as | netstat.udp_socket | +| mem.dirty | processes.blocked | +| mem.free | processes.dead | +| mem.high_free | processes.idle | +| mem.high_total | processes.paging | +| mem.huge_page_size | processes.running | +| mem.huge_pages_free | processes.sleeping | +| mem.huge_pages_total | processes.stopped | +| mem.inactive | processes.total | +| mem.low_free | processes.total_threads | +| mem.low_total | processes.unknown | +| mem.mapped | processes.zombies | +| mem.page_tables | procstat_lookup.pid_count | +| mem.shared | system.load1 | +| mem.slab | system.load1_per_cpu | +| mem.swap_cached | jvm.statsd-jvm-profiler_heap_ps-old-gen_max.value | +| jvm.statsd-jvm-profiler_pending-finalization-count.value | jvm.statsd-jvm-profiler_nonheap_total_committed.value | +| jvm.statsd-jvm-profiler_loaded-class-count.value | jvm.metrics_jvm_heapMemoryUsage_used.value | +| jvm.statsd-jvm-profiler_gc_PS_Scavenge_count.value | jvm.metrics_jvm_nonHeapMemoryUsage_used.value | +| jvm.statsd-jvm-profiler_nonheap_metaspace_init.value | jvm.statsd-jvm-profiler_nonheap_total_used.value | +| jvm.statsd-jvm-profiler_heap_ps-survivor-space_used.value | jvm.statsd-jvm-profiler_heap_ps-eden-space_init.value | +| jvm.statsd-jvm-profiler_gc_PS_MarkSweep_time.value | jvm.statsd-jvm-profiler_nonheap_total_max.value | +| jvm.statsd-jvm-profiler_heap_ps-eden-space_max.value | jvm.statsd-jvm-profiler_nonheap_compressed-class-space_max.value | +| jvm.statsd-jvm-profiler_heap_total_init.value | jvm.statsd-jvm-profiler_nonheap_code-cache_used.value | +| jvm.statsd-jvm-profiler_nonheap_metaspace_used.value | jvm.statsd-jvm-profiler_nonheap_compressed-class-space_init.value | +| jvm.statsd-jvm-profiler_nonheap_metaspace_max.value | jvm.statsd-jvm-profiler_gc_PS_MarkSweep_count.value | +| jvm.statsd-jvm-profiler_heap_ps-eden-space_used.value | | + +### Examples and usages + +From the `metrics` tab on the console. You can either open a Quantum console, an online WarpScript editor, or either send your WarpScript by your own way on the Warp 10 endpoint (provided by Quantum). + +More information about [Quantum and Warp 10](/developers/doc/metrics/warp10) in our documentation. + +For example, you could fetch the memory usage of an application for the last hour. Smoothed by a data average by +minute. + +{{< callout type="warning" >}} +Computation can be time intensive. +{{< /callout >}} + +```txt +// Fix the NOW timestamp to have the same on over the script +NOW 'NOW' STORE +// fetch data over 1 hour +[ 'mem.available' { 'app_id' '' } $NOW 1 h ] FETCH +// Average the data by bucket of 1 min from the last point timestamped at NOW +[ SWAP bucketizer.mean $NOW 1 m 0 ] BUCKETIZE +// From the instance granularity to application granularity. Timestamps to timestamps merge +[ SWAP [ 'app_id' ] reducer.mean ] REDUCE +``` + +## Consumption metric + +Consumption can also be inferred by our metrics. We provide some helper macros in the [Warp 10 documentation](/developers/doc/metrics/warp10). + +Consumption unit is in **second**. + +The following script provides the whole consumption from between start and end timestamps for all applications +under an organisation. + +```txt +'' '' @clevercloud/app_consumption +``` + +## Publish your own metrics + +We currently support two ways to push / collect your metrics: the `statsd` protocol and `prometheus`. + +The statsd server listens on port `8125`. You can send metrics using regular statsd protocol or using an advanced one [as described here](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/statsd#influx-statsd). + +We also support Prometheus metrics collection, by default our agent collects exposed metrics on `localhost:9100/metrics`. + +If needed, you can override those settings with the two following environment variables: + +- `CC_METRICS_PROMETHEUS_PORT`: Define the port on which the Prometheus endpoint is available +- `CC_METRICS_PROMETHEUS_PATH`: Define the path on which the Prometheus endpoint is available + +As with Prometheus the exposed host can be the same as the application deployed, you can use a basic authentication to collect the metrics with the two following environment variables: + +- `CC_METRICS_PROMETHEUS_USER`: Define the user for the basic auth of the Prometheus endpoint +- `CC_METRICS_PROMETHEUS_PASSWORD`: Define the password for the basic auth of the Prometheus endpoint + +For large custom set of metrics to collect, the default response timeout of the `/metrics` query is 3 seconds. You can update it with the following environment variable: + +- `CC_METRICS_PROMETHEUS_RESPONSE_TIMEOUT`: Define the timeout in seconds to collect the application metrics. This value **must** be below 60 seconds as data are collected every minutes. + +To access your metrics from Warp10 you need to use the prefix `prometheus.` or `statsd.` based on what you used to publish your metrics. + +You can use this query to show all collected metrics: + +```txt +[ + 'TOKEN' + '~prometheus.*' + { 'app_id' 'app_xxxxxxxx' } + NOW 5 m +] +FETCH +``` + +### Node.js example + +You can use `node-statsd` to publish metrics: + +```javascript +// npm install node-statsd + +const StatsD = require("node-statsd"), + client = new StatsD(); + +// Increment: Increments a stat by a value (default is 1) +client.increment("my_counter"); + +// Gauge: Gauge a stat by a specified amount +client.gauge("my_gauge", 123.45); +``` + +### Haskell example + + + +In Haskell, metrics are usually gathered with [EKG](https://hackage.haskell.org/package/ekg). +The package `ekg-statsd` allows to push EKG metrics over `statsd`. + +If you're using [warp](https://hackage.haskell.org/package/warp), you can use +`wai-middleware-metrics` to report request distributions (request count, +responses count aggregated by status code, +responses latency distribution). + +EKG allows you to have access to GC metrics, make sure you compile your application +with `"-with-rtsopts=-T -N"` to enable profiling. + +```haskell +{-# LANGUAGE OverloadedStrings #-} + +-- you need the following packages +-- ekg-core +-- ekg-statsd +-- scotty +-- wai-middleware-metrics + +import Control.Monad (when) +import Network.Wai.Metrics (WaiMetrics, metrics, + registerWaiMetrics) +import System.Metrics (newStore, registerGcMetrics) +import System.Remote.Monitoring.Statsd (defaultStatsdOptions, + forkStatsd) +import Web.Scotty + +handleMetrics :: IO WaiMetrics +handleMetrics = do + store <- newStore + registerGcMetrics store + waiMetrics <- registerWaiMetrics store + sendMetrics <- maybe False (== "true") <$> lookupEnv "ENABLE_METRICS" + when sendMetrics $ do + putStrLn "statsd reporting enabled" + forkStatsd defaultStatsdOptions store + return () + return waiMetrics + +main = do + waiMetrics <- handleMetrics + scotty 8080 $ do + middleware $ metrics waiMetrics + get "/" $ + html $ "Hello world" +``` diff --git a/content/doc/metrics/blackfire.md b/content/doc/metrics/blackfire.md new file mode 100644 index 000000000..48f8e82e6 --- /dev/null +++ b/content/doc/metrics/blackfire.md @@ -0,0 +1,48 @@ +--- +type: docs +title: Blackfire +description: Configuring Blackfire on Clever Cloud +tags: +- apps +keywords: +- blackfire +- metrics +- monitoring +aliases: +- /doc/administrate/metrics/blackfire/ +--- + +## Overview + +Blackfire can be used on Clever Cloud with **PHP** applications. + +[Blackfire](https://www.blackfire.io/) helps to improve web applications, performance at each step of its lifecycle: from development to test, staging and production. + +## Blackfire configuration + +### Necessary information + +Your PHP version must be 7.4 or higher. +Before setting up your app, be sure to have a [Blackfire Account](https://www.blackfire.io/). + +### Configuration + +- Add ENABLE_BLACKFIRE=true environment variable to load Blackfire extension. +- Add at least the CC_BLACKFIRE_SERVER_TOKEN and CC_BLACKFIRE_SERVER_ID environment variables.`CC_BLACKFIRE_SERVER_ID`. + +### Optional configuration + +If you need to fine-tune agent settings, you can use the following environment variables: + +```bash +CC_BLACKFIRE_LOG_LEVEL +CC_BLACKFIRE_MEMORY_LIMIT +CC_BLACKFIRE_COLLECTOR +CC_BLACKFIRE_TIMEOUT +CC_BLACKFIRE_STATSD +CC_BLACKFIRE_STATSD_PREFIX +``` + +### Usage + +Just redeploy your application on Clever Cloud for the changes to take effect. A few minutes later, your application will begin sending data to Blackfire. Once Blackfire receives the data, your application will be listed in the dashboard. diff --git a/content/doc/metrics/new-relic.md b/content/doc/metrics/new-relic.md new file mode 100644 index 000000000..8b0d85a82 --- /dev/null +++ b/content/doc/metrics/new-relic.md @@ -0,0 +1,79 @@ +--- +type: docs +title: New Relic +description: Configuring Newrelic on Clever Cloud +tags: +- apps +keywords: +- new relic +- newrelic +- metrics +- monitoring +aliases: +- /administrate/metrics/new-relic +- /doc/administrate/metrics/new-relic +- /doc/tools/new-relic +--- + +## Overview + +New Relic can be used on Clever Cloud with **Java, Node.js, PHP, Ruby and Scala** applications. + +[New Relic](https://www.newrelic.com/) is a software analytics company based in the United States. +New Relic's technology monitors Web and mobile applications in real-time that run in cloud, on-premise, or hybrid environments. You can easily setup a New Relic based monitoring on your application to monitor it and find performances problems. + +## New Relic for Node.js and Ruby + +New Relic is very simple to install in a Node.js or Ruby application as it is a simple dependency. +Install instructions for [Node.js](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/install-nodejs-agent/) and [Ruby](https://docs.newrelic.com/docs/apm/agents/ruby-agent/installation/install-new-relic-ruby-agent/) are available in [the New Relic documentation](https://docs.newrelic.com/). + +## New Relic for Python + +To use New Relic in Python, you have to add the [newrelic](https://pypi.python.org/pypi/newrelic) dependency into your `requirements.txt` file. + +## New Relic for Java, Scala and PHP + +To use New Relic in Java, Scala or PHP instances, you need to configure it as it is provided directly inside the instances. + +{{< callout type="info" >}} +New Relic trigger auto-insertion of JavaScript fragments on PHP applications, for browser monitoring. You can disable it with `newrelic.browser_monitoring.auto_instrument` in `.user.ini`. +[Learn more on New Relic's documentation](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-autorum). + +{{< /callout >}} + +## New Relic configuration + +### Necessary information + +Before setting up your app, be sure to have a [New Relic Account](https://www.newrelic.com/). + +### Configuration + +To configure your New Relic, you need to set the environment variables `NEW_RELIC_LICENSE_KEY` and `NEW_RELIC_APP_NAME` (optional). + +Alternatively you can create and add a `./clevercloud/newrelic.json` file in your project, with the following fields: + +```json +{ + "license": "licenceID", + "appname": "NameOfYourApp(optional)" +} +``` + +If the `appname` or `NEW_RELIC_APP_NAME` is not specified, we use your application id for the name. + +### Optional configuration (PHP only) + +If you need to fine-tune agent settings, you can use the following environment variables: + +| Variable | +|-------------------- +|[`CC_NEWRELIC_BROWSER_MONITORING_AUTO_INSTRUMENT`](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-autorum) | +|[`CC_NEWRELIC_DISTRIBUTED_TRACING_ENABLED`](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-distributed-enabled) | +|[`CC_NEWRELIC_ERROR_COLLECTOR_ENABLED`](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-err-enabled) | +|[`CC_NEWRELIC_TRANSACTION_TRACER_ENABLED`](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-tt-enable) | +|[`CC_NEWRELIC_TRANSACTION_TRACER_RECORD_SQL`](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-tt-sql) | + +### Usage + +Redeploy your application on Clever Cloud for the changes to take effect. A few minutes later, your application will begin sending data to New Relic. Once New Relic receives the data, your application will be listed in the dashboard. diff --git a/content/doc/metrics/warp10.md b/content/doc/metrics/warp10.md new file mode 100644 index 000000000..48c1f3ec6 --- /dev/null +++ b/content/doc/metrics/warp10.md @@ -0,0 +1,180 @@ +--- +type: docs +title: Warp 10 +description: Warp 10. Geo Time series database. Presentations, concepts and examples +tags: + - metrics +keywords: + - GTS + - warp 10 + - Quantum + - visualization + - time series + - database +aliases: +- /doc/administrate/metrics/warp10/ +--- + +## Main concepts + +Warp 10 is a time series database. The notion of `class`, `labels`, `longitude`, `latitude`, `altitude` and `value` are used. + +A GTS is a GeoTime Serie defined by a `class` and some `labels`. They're indexed and used to quickly retrieved the data. + +`labels` is a kind of dictionary. That's called a **map** under the warp10 terminology. + +A GTS may contain some values which have the following models : `[ timestamp longitude latitude altitude value ]` + +Warp 10 uses [Warp Script](https://www.warp10.io/content/03_Documentation/04_WarpScript). It's a **stack** based **language using reverse polish notation**. + +> The metrics OVHcloud team built an other way to request Warp 10: +> Warp 1O documentation [is available on their website](https://www.warp10.io/doc/reference) + +### Time and duration in Warp 10 + +> More information about [date functions here](https://www.warp10.io/tags/date), and [time functions here](https://www.warp10.io/tags/time). + +{{< callout type="info" >}} +The platform's time unit is in **microsecond**. +{{< /callout >}} + +#### Duration is set by the followings symbols + +- `d` : day +- `h` : Hour +- `ms` : millisecond +- `ns` : nanosecond +- `ps` : picosecond +- `s` : second +- `us` : microsecond +- `w` : week + +#### Date + +Allowed format : + +- ISO8601 +- Timestamp in microsecond + +Builtin function : + +- `NOW` : get the current timestamp +- `ISO8601` : Convert a string or a timestamp to a ISO8601 date format + +## Endpoint + +The Clever Cloud Warp 10 endpoint is: + +```html +https://c2-warp10-clevercloud-customers.services.clever-cloud.com/api/v0 +``` + +- Learn more about [endpoint gateway on warp10.io](https://www.warp10.io/content/03_Documentation/03_Interacting_with_Warp_10/01_Introduction) + +You can find the endpoint and an available token under the `metric` tab of your application. You can query our Warp 10 platform with your own script. Here's an example with `curl`: + +```bash + curl -T https://c2-warp10-clevercloud-customers.services.clever-cloud.com/api/v0/exec +``` + +{{< callout type="warning" >}} +Do not forget the endpoint. `exec` in the previous example. +{{< /callout >}} + +## Token + +Tokens are based on your application with the notion of producer and owner. Hence, only the data owner can see it. + +You can find a 5 days available token in the `metric` tab of your application. + +## Technical constraints + +The followings limits are defined in Warp 10. The **soft** one can be passed over by an [`AUTHENTICATE`](https://www.warp10.io/doc/AUTHENTICATE) operation. The **hard** one is unsurpassable. + +| WarpScript Operator | Warp 10 limit description | soft limit | hard limit | +| ------------------- | ------------------------------------------------------------- | ---------- | ---------- | +| MAXGTS | Maximum number of GTS which can be fetched | 10e5 | 5e7 | +| LIMIT | Maximum number of datapoints which can be fetched during a script execution | 10e6 | 10e7 | +| MAXBUCKETS | Maximum number of buckets which can be created by a call to BUCKETIZE | 10e5 | 50e5 | +| MAXDEPTH | Maximum depth (number of levels) of the execution stack | 5e3 | 5e3 | +| MAXLOOP | Maximum number of milliseconds which can be spent in a loop | 5e3 | 10e3 | +| MAXOPS | Maximum number of operations which can be performed during a single WarpScript execution | 5e6 | 5e7 | +| MAXSYMBOLS | Maximum number of simultaneous symbols which can be defined on the stack during a single WarpScript execution | 64 | 256 | +| MAXGEOCELLS | Maximum number of cells a GEOSHAPE | 10e3 | 10e4 | +| MAXPIXELS | Maximum size (in pixels) of images which can be created by PGraphics | 10e5 | 10e5 | +| MAXRECURSION | Maximum nesting depth of macro calls | 16 | 32 | + +{{< callout type="warning" >}} +Operation over **soft limits** may be intensives. +{{< /callout >}} + +### Usage + +An example where it is needed to increase the fetch limit by the `LIMIT` function + +```warpscript +'' AUTHENTICATE +50e6 TOLONG LIMIT +// Fetch on the 'accessLogs' class for your application id as labels +[ '' 'accessLogs' { 'app_id' '' } NOW 1 w ] FETCH +``` + +## Visualization and exploration + +### Quantum + +Quantum is a web tool used to run some WarpScript. You can access to it from your metrics interface. + +It provides the path to the Clever Cloud Warp 10 gateway and let you explore your data. + +## Macro + +Warp 10 provide a server side macro manager. It is a way to release some ready to use WarpScript. Hence, Clever Cloud provides some macros as helpers to avoid redundant and often need code. + +{{< callout type="info" >}} +More information on the [Warp 10' macros documentations](https://www.warp10.io/content/03_Documentation/07_Extending_Warp_10/01_Server_side_macros). +{{< /callout >}} + +### Consumption + +The following macros are helpers to compute consumption in seconds + +- `app_consumption` + +Return the consumption in **second** by **applications** for a specific **organisation**. +`Start` and `End` parameters can be either a timestamp in microseconds or an iso8601 date format. + +```bash +'' '' '' '' @clevercloud/app_consumption +``` + +- `orga_consumption` + +Return **all** the consumption in **second** for a specific **organisation**. `Start` and `End` parameters +can be either a timestamp in microseconds or an iso8601 date format. + +```bash +'' '' '' '' @clevercloud/app_consumption +``` + +### Access Logs + +- `fetch_accessLogs_key_v0` + +We provide the following macro to easily and quickly deep dive into access logs data. As we store access log as a JSON value in a geotime series ([metrics documentation here](/developers/doc/metrics#access-logs-metrics)), this macro can be useful for straightforward access to a specific key. It allows you to fetch the `accessLogs` class and get only wanted value instead of the whole JSON. + +```bash + '' { 'app_id' 'id' } '<1stLevelKey>' NOW 1 h @clevercloud/fetch_accessLogs_key_v0 +``` + +```bash + '' { 'app_id' 'id' } '<1stLevelKey>.<2ndLevelKey>' NOW 10 m @clevercloud/fetch_accessLogs_key_v0 +``` + +> More example in the [metrics part of this documentation](/developers/doc/metrics#access-logs-metrics). + +**Nested keys** can be reached using a dot (`.`) to represent the depth. + +```bash +'' '' '' '' '' @clevercloud/fetch_accessLogs_key_v0 +``` diff --git a/content/doc/quickstart.md b/content/doc/quickstart.md new file mode 100644 index 000000000..9fcd5109c --- /dev/null +++ b/content/doc/quickstart.md @@ -0,0 +1,381 @@ +--- +type: "docs" +weight: 1 +title: Quickstart +description: Follow this guide to get ready to deploy quickly as you learn the basics of Clever Cloud +tags: +- getting-started +keywords: +- quickstart +aliases: +- /deploy +- /doc/addons/add-an-addon +- /doc/clever-cloud-overview/add-application +- /doc/getting-started +- /doc/getting-started/quickstart +- /getting-started/authentication +- /getting-started/quickstart +- /quickstart +--- +{{< hextra/hero-subtitle >}} + Clever Cloud provides an automated hosting platform for developers. Deploy your app easily and launch dependencies without having to worry about the infrastructure set up. Follow this guide to get ready to deploy quickly as you learn the basics of Clever Cloud. +{{< /hextra/hero-subtitle >}} + +## Create a Clever Cloud Account + +The API of Clever Cloud uses OAuth 1 to perform authentication actions. +There are two ways to sign up for Clever Cloud: **email** or **GitHub login**. + +{{< tabs items="Email Auth, GitHub Auth" >}} + + {{< tab >}} + This kind of auth requires a valid and non-temporary disposable email, and a password having at least 6 characters. + Do not forget to validate your email by clicking the link you will receive. + {{< /tab >}} + + {{< tab >}} + + The GitHub sign up allows you to create an account or link your existing one to GitHub, in one click. + This process asks the following permissions: + +* Read your Public Key +* Read User Repositories + + The "repository permission" is used to deploy your GitHub apps directly to Clever Cloud, with a simple step. + If you need to give access to Clever Cloud's API to a specific GitHub organisation, you can [do it here](https://github.com/settings/connections/applications/d96bd8fd996d2ca783cc). +{{< /tab >}} + +{{< /tabs >}} + +Go to the [Clever Cloud Console](https://console.clever-cloud.com/) and select the method you prefer. + +### Two Factor Authentication (2FA) + +Clever Cloud supports 2FA. You can enable it here: + +Please, backup your recovery codes, we won't be able to restore access to your account if you lose access to your regular codes. + +## Deploy your code + +### What's an Application on Clever Cloud + +An application is defined on Clever Cloud by the following elements: + +* a dedicated language/framework; +* a deployment method (FTP and/or Git); +* resources consumption (CPU, RAM, Disk…), depending on the language or framework used; +* an optional configuration file you may add to your project. + +If one of these elements is missing, Clever Cloud can't deploy your application properly (except the configuration file, optional in some cases). + +> [!NOTE] +> Clever Cloud runtimes are immutable infrastructure and always start with a fresh, up-to-date, system. If you need persistent storage, use a file storage ([FS Bucket](/developers/doc/addons/fs-bucket/)), object storage ([Cellar](/developers/doc/addons/cellar)) or one of the many Clever Cloud's [database-as-a-service](/developers/doc/addons/). + +### How it Works + +When you push an application's code to git or via FTP, the platform receives it and checks the resource's requirements. If they are complete, the deployment is launched. When finished and successful, the application is up and running. + +The log system retrieves all output from the application and displays it in the logs tab of your application in the Clever Cloud console. + +### Supported Platforms + +{{< cards >}} + {{< card link="/developers/doc/applications/dotnet" title=".Net" icon="dotnet" >}} + {{< card link="/developers/doc/applications/docker" title="Docker" icon="docker" >}} + {{< card link="/developers/doc/applications/elixir" title="Elixir" icon="elixir" >}} + {{< card link="/developers/doc/applications/frankenphp" title="Franken PHP" icon="frankenphp" >}} + {{< card link="/developers/doc/applications/golang" title="Go" icon="go" >}} + {{< card link="/developers/doc/applications/haskell" title="Haskell" icon="haskell">}} + {{< card link="/developers/doc/applications/java" title="Java (Gradle, Jar, Maven, War/Ear)" icon="java" >}} + {{< card link="/developers/doc/applications/linux" title="Linux" icon="linux" >}} + {{< card link="/developers/doc/applications/meteor" title="Meteor.js" icon="meteor" >}} + {{< card link="/developers/doc/applications/nodejs" title="Node.js & Bun" icon="node" >}} + {{< card link="/developers/doc/applications/php" title="PHP with Apache" icon="php" >}} + {{< card link="/developers/doc/applications/python" title="Python with uv support" icon="python" >}} + {{< card link="/developers/doc/applications/ruby" title="Ruby" icon="ruby" >}} + {{< card link="/developers/doc/applications/rust" title="Rust" icon="rust" >}} + {{< card link="/developers/doc/applications/scala" title="Scala" icon="scala" >}} + {{< card link="/developers/doc/applications/static" title="Static" icon="static" >}} + {{< card link="/developers/doc/applications/static-apache" title="Static with Apache" icon="feather" >}} + {{< card link="/developers/doc/applications/v" title="V (Vlang)" icon="v" >}} +{{< /cards >}} + +### Create an Application Step by Step + +{{< youtube 9ww_t0o-GmA >}} + +In the [Clever Cloud Console](https://console.clever-cloud.com/): + +{{% steps %}} + +#### Select the organisation + +Choose the organisation you want to deploy in from the left menu. At this point you must only have the Personal Space but you can create one. + +#### Click on "Create an application" + +Find it in the **organisation Manager** panel, at the top left of the left menu. + +This starts the application creation wizard. If your account has been linked to GitHub, you can select a repository from your GitHub account. +If you want to deploy an application within a GitHub organisation, first [grant the Clever Cloud API access to it](https://github.com/settings/connections/applications/d96bd8fd996d2ca783cc). + +#### Select the language + +Choose the language or the framework you want to deploy. + + {{< callout emoji="💡" >}} + **Optional:** for PHP applications, you can choose between FTP and Git deployment. + {{< /callout >}} + +#### Fine-tune your scaling configuration + +Horizontal scaling is the number of instances that can run at the same time. Vertical scaling sets the minimum and maximum size the instance can be. + +- [Learn more about scaling & instances size](/developers/doc/administrate/scalability) + +#### Name your application + +Enter the name and the description of your application. + +#### Optional steps + +* The wizard will offer you to [add an add-on](/developers/doc/addons) to your application +* The wizard will offer you to [add environment variables](/developers/doc/develop/env-variables) to your application + +{{% /steps %}} + +#### Choose How to Deploy + +{{< tabs items="Git,GitHub, FTP" >}} + {{< tab >}} + *To deploy via Git, you need it installed on your machine. You can find more information on Git website: [git-scm.com](https://git-scm.com)* + + *Note:* during the deployment, the .git folder is automatically deleted to avoid security problems. If you need to know which version is used on the server please use the `COMMIT_ID` [environment variable](/developers/doc/reference/reference-environment-variables/). + + Follow these steps to deploy your application: + +1. Get the git deployment URL in the application information page, which looks like: `git+ssh://git@push..clever-cloud.com/.git`. + +2. In your terminal, go to your application repository. If you do not already track your app with git, start by typing: + + ```bash + git init + git add . + git commit -m "first commit" +``` + +3. Then, link your local repository to Clever Cloud by providing the Git remote URL: + +```bash +git remote add +``` + +4. Push your application to Clever Cloud: + +```bash +git push :master +``` + + You can see your application **logs** in the dashboard to **monitor the deployment**. + + {{< /tab >}} + + {{< tab >}} + Once you have created your application with GitHub, each push on the `master` branch trigger a deployment. To deploy an other branch than `master`, go to the `information` panel of your application and select the default branch to use. + + ![GitHub deployment branch select](/images/github-deployment-branch.png "Github deployment branch select") + + If you don't find your repository in the list fetched from GitHub, a workaround is to unlink your account in your profile here : , remove **Clever Cloud API** from your GitHub [Authorized OAuth Apps](https://github.com/settings/applications) and link again your GitHub account to your Clever Cloud account. + + **Private GitHub repositories are also supported.** + + Caution: in GitHub, private repositories in an ordinary user account are an all-or-nothing deal: that is, either someone has full read write access (because they're a collaborator) or they have no access. + + However, if you set up an organisation, create the repository under the aegis of the organisation, and then add the collaborator, you have much more fine-grained control (including giving read-only access to a private repository). + {{< /tab >}} + + {{< tab >}} + You can deploy via FTP with PHP applications. + + To deploy via FTP, you need an FTP software installed on your machine. [Filezilla](https://filezilla-project.org/) is one of them. + + Deploy your application via FTP, create a [FS Bucket](/developers/doc/addons/fs-bucket) with an ID matching your application's ID. You will find the FTP credentials in the configuration tab of this particular FS Bucket. + + [More documentation about Filezilla](https://wiki.filezilla-project.org/FileZilla_Client_Tutorial_%28en%29). + + {{< icon "exclamation-circle" >}} An FTP application is automatically started once the application is created, even if no code has been sent. + + {{< callout type="warning" >}} + FTP deployment is ok for small websites but not for large ones. We strongly recommend you to use **Git** deployment for **large PHP websites**. + {{< /callout >}} + {{< /tab >}} +{{< /tabs >}} + +### Troubleshooting + +{{% details title="Git ⋅ Remote is asking for a password" closed="true" %}} + +If the remote asks you for a password right after a git push attempt, this may be due to a SSH Key configuration error. + +**Add your SSH key to your profile here:** + + +The full tutorial about adding SSH key is here: [adding SSH keys](/developers/doc/account/ssh-keys-management/) + +{{% /details %}} +{{% details title= "Git ⋅ Unable to resolve the reference master" closed="true" %}} +You are probably trying to push from another branch. Keep in mind that: + +* You can only push to the **master** branch for deployment. Trying to push to another branch will trigger an error. +* You cannot push a tag (which refers to a commit) to the remote repository. If you do so, **no deployment** will be triggered. +* In order to push to **master** from a non-master local branch, use this syntax: + +```bash +git push :master +``` + +{{% /details %}} + +{{% details title= "GitHub ⋅ Does not appear to be a git repository" closed="true" %}} +You can't directly push to an application created on Clever Cloud as a GitHub app: in this case, only the automatic deployment from GitHub is henceforth allowed. + +If you try to push to Clever Cloud, as you would do for a non-GitHub app, you will get the following error : + +```bash +fatal: '/data/repositories/.git' does not +appear to be a git repository +``` + +Indeed, no git repository is created on Clever Cloud because the application is directly cloned from GitHub. + +If you have to push directly to a repository to deploy an application (eg if you deploy from a CI), then create a non-GitHub app. + +{{% /details %}} + +## Manage your Application + +There are many tabs available in the application's menu on Clever Console: + +* **Information:** General information about your application +* **Scalability:** Set-up scalability options +* **Domain names:** Manage custom domain names +* **Environment variables:** Manage environment variables +* **Service dependencies:** Link add-ons and applications +* **Exposed configuration:** Manage exposed environment variables +* **Activity:** Track last deployments +* **Logs:** Visualize application's logs +* **Metrics:** Visualize application's metrics +* **Consumption:** Visualize your application's consumption. + +### Create your first add-on + +Applications often requires one or more services in addition to the runtime itself. Add-ons are services you can use independently, or you can link them with your application(s). For instance, you may want to add a database or a caching system to your application or just have a database with no linked application. + +An add-on can be shared by different applications to share data between them. It can be a database shared by two or three applications of your infrastructure for example, or they can be independent. + +Most of the add-ons catalog is provided by Clever Cloud, but vendors are also allowed to provide services external to Clever Cloud ([See how to integrate your SaaS with Clever Cloud](/developers/api)) + +#### Available add-ons + +Clever Cloud provides multiple add-ons to work with your applications: + +##### Databases + +{{< cards >}} + {{< card link="/developers/doc/addons/materia-kv" title="Materia KV" subtitle="Serverless & distributed key-value database" icon="materia" tag="Alpha" >}} + {{< card link="/developers/doc/addons/mongodb" title="MongoDB" subtitle="The NoSQL document-oriented database" icon= "mongo">}} + {{< card link="/developers/doc/addons/mysql" title="MySQL" icon="mysql" subtitle="Your managed relational database" >}} + {{< card link="/developers/doc/addons/postgresql" title="PostgreSQL" icon="pg" subtitle="The not-only-SQL managed database" >}} + {{< card link="/developers/doc/addons/elastic" title="Elastic Stack" subtitle="Deploy your Elastic Stack in one click" icon="elastic" >}} + + {{< card link="/developers/doc/addons/redis" title="Redis" subtitle="Managed key-value database" icon="redis" >}} +{{< /cards >}} + +##### Storage & Messaging + +{{< cards >}} + {{< card link="/developers/doc/addons/cellar" title="Cellar" subtitle="Object storage, compatible with S3 API" icon="cellar" >}} + {{< card link="/developers/doc/addons/fs-bucket" title="FS Bucket" subtitle="Persistent external file system for your apps" icon="fsbucket" >}} + {{< card link="/developers/doc/addons/pulsar" title="Pulsar" subtitle="Open source, distributed messaging and streaming platform built for the cloud" icon="pulsar" tag="Beta" >}} +{{< /cards >}} + +##### Services & Tools + +{{< cards >}} + {{< card link="/developers/doc/addons/config-provider" title="Config Provider" subtitle="More freedom to manage, import and inject your configurations and credentials" icon="creds" >}} + {{< card link="/developers/doc/addons/heptapod" title="Heptapod" subtitle="The friendly fork of GitLab Community Edition that adds support for Mercurial" icon="git" >}} + {{< card link="/developers/doc/addons/jenkins" title="Jenkins" subtitle="The leading open source automation server" icon="jenkins" >}} + {{< card link="/developers/doc/addons/keycloak" title="Keycloak" subtitle="Single sign-on with Identity and Access Management solution" icon="keycloak" >}} + {{< card link="/developers/doc/addons/mailpace" title="Mailpace" subtitle="Fast and reliable transactional email" icon="mail" >}} + {{< card link="/developers/doc/addons/matomo" title="Matomo" subtitle="A web analytics application as a service, the best Google Analytics alternative" icon="matomo" >}} + {{< card link="/developers/doc/addons/metabase" title="Metabase" subtitle="An easy business intelligence tool to query and visualize data" icon="metabase" >}} + {{< card link="/developers/doc/addons/otoroshi" title="Otoroshi with LLM" subtitle="Simple API management based on a modern reverse proxy with preconigured plugins" icon="endpoints" >}} +{{< /cards >}} + +**If your add-on:** + +{{< tabs items="Doesn't exist yet,Already exists" >}} + {{< tab >}} + Here we will assume you want to create a new add-on and link it to your application. + + 1. Go to the [Clever Cloud Console](https://console.clever-cloud.com/). + 2. Go to the organisation in which you want to create the add-on, for example your [personal space](https://console.clever-cloud.com/users/me). + 3. Click on **Add an add-on**. This space let you create and configure the add-on according to your needs. + 4. Choose which *type* of add-on you want to create. See preceding the list of available add-ons and their corresponding documentation pages for further information on how they work. + 5. Select the plan you need for you add-on. You can find details about the pricing, the capacity of the add-on and other specifications on this page or in the corresponding documentation page. + 6. Choose with which application you want to link you add-on. Linking an add-on to an application will provide configuration to the application through [environment variables](/developers/doc/reference/reference-environment-variables/). The environment variables provided by the add-on are available for use in the linked application. If you want to use your add-on alone, just don't link it to any application. + 7. Choose the name of the add-on and the region where the add-on will be hosted. + 8. Click on the **Create** button. + + The add-on will now be available in your organisation, and corresponding environment variables will be available for the applications linked to the add-on you just created. + {{< /tab >}} + + {{< tab >}} + To link an already existing add-on with your application, just follow these steps: + + 1. Go in the organisation of your application. + 2. Click on the name of the application you want to link with your add-on. + 3. Go in the **Service dependencies** section. + 4. Select the add-on you want to link under the "Link add-ons" dropdown menu. + 5. Click on the **Link** button of the add-on you want to link to your application. + {{< /tab >}} +{{< /tabs >}} + +##### Add-on Billing + +There are two kinds of billing: + +* Per-month billing: Add-ons with fixed resources (storage, CPU and RAM) +* Per-usage billing: Add-ons based on consumption, like [FS Bucket](/developers/doc/addons/fs-bucket) and [Cellar](/developers/doc/addons/cellar) + +{{< callout type="warning" >}} +**Free Plan:** add-ons having a free plan are meant for testing purposes, not production usage. These add-ons usually rely on shared resources, resulting in variable, non-guaranteed performances and stability. Shared clusters may not be running the same version as dedicated instances. +{{< /callout >}} + +{{< callout emoji="📊" >}} +**Your invoice:** per usage billing will be taken on runtime credits each day, while per-month add-ons will create a new line in the monthly invoice. +{{< /callout >}} + +### Manage your Add-on + +Once an add-on is created, at least two tabs are available in the Clever Cloud console: + +* **Add-on dashboard:** This screen provides and overview of your add-on and its options, depending on the type of add-on it is. + +!["Add-on dashboard"](/images/addon-dashboard.png "Example of an add-on dashboard") + +* **Information tab:** This screen sums-up the characteristics of the selected add-on. +The system shows features and environment variables (if applicable). + +Other tabs may be available, depending on the add-on type. + +### Delete an add-on + +To delete an add-on: + +1. Go to the **Information** tab of the add-on. +2. Click on *Remove add-on*. + +{{< callout type="warning" >}} +The system removes all associated data after you delete the add-on. +{{< /callout >}} diff --git a/content/doc/reference/_index.md b/content/doc/reference/_index.md new file mode 100644 index 000000000..764dfaba2 --- /dev/null +++ b/content/doc/reference/_index.md @@ -0,0 +1,22 @@ +--- +weight: 10 +type: docs +title: Configuration List +description: All Clever Cloud advanced features and tools +tags: +- cli +- add-ons +- api +- environment variables +keywords: +- list +- authentication +aliases: +- /reference +comments: false +--- + +{{< cards >}} + {{< card link="/developers/doc/reference/common-configuration" title="Common configuration for all instances" icon="cog-6-tooth" >}} + {{< card link="/developers/doc/reference/reference-environment-variables" title="All environment variables" icon="creds" >}} +{{< /cards >}} diff --git a/content/doc/reference/cli.md b/content/doc/reference/cli.md new file mode 100644 index 000000000..bdcf6bf5e --- /dev/null +++ b/content/doc/reference/cli.md @@ -0,0 +1,2210 @@ +--- +type: docs +linkTitle: CLI reference +title: Clever Tools - CLI commands reference +description: Clever Tools commands reference to create and manage Clever Cloud applications, add-ons and services. Ideal to provide to LLMS and AI assisted IDEs. +comments: false +aliases: +- /doc/reference/clever-tools/configure +- /doc/reference/clever-tools/manage +- /reference/clever-tools +- /reference/clever-tools/getting_started +--- + +This document is automatically generated from Clever Tools `3.14.0` and Clever Cloud API. It covers all Clever Tools commands and options. Use it to better understand this CLI and its capabilities or to train/use LLMs, AI-assisted IDEs. + +To use Clever Tools, you need: +- A Clever Cloud account, create one at https://console.clever-cloud.com/ +- The Clever Tools CLI installed, see installation instructions below + +In CI/CD pipelines or for one-off usage, you can use it through `npx` or `npm exec`: + +```bash +# Set/Export CLEVER_TOKEN and CLEVER_SECRET to login with a given account +# --yes is used to skip the interactive prompts +npx --yes clever-tools@latest version +``` + +You'll also need: + +- To be logged in with `clever login` command (you'll get a `$HOME/.config/clever-cloud/clever-tools.json` file) +- git installed on your system and properly configured +- A local git repository with at least one commit to deploy your application + +To control an application with Clever Tools, it must be linked to a local directory (a `.clever.json` file is present, containing its `app_id`, `name`, `local alias`, `org_id`, `deploy_url`, `git_ssh_url`). You can target an application on most commands with `--app app_id_or_name` option. + +## How to install Clever Tools + +Clever Cloud CLI is based on Node.js. We thought it to be easily available on any platform. Thus, you can download Clever Tools as [a npm package](https://www.npmjs.com/package/clever-tools), but also through package managers or as a binary on many systems: + +### GNU/Linux + +#### Arch Linux (AUR) + +If you use Arch Linux, install packages [from AUR](https://aur.archlinux.org/packages/clever-tools-bin/). If you don't know how to use this, run: + +``` +git clone https://aur.archlinux.org/clever-tools-bin.git clever-tools +cd clever-tools +makepkg -si +``` + +#### CentOS/Fedora (.rpm) + +If you use a GNU/Linux distribution that uses `.rpm` packages like CentOS or Fedora, run: + +``` +curl -s https://clever-tools.clever-cloud.com/repos/cc-nexus-rpm.repo > /etc/yum.repos.d/cc-nexus-rpm.repo +yum update +yum install clever-tools +``` + +> [!TIP] +> The `.rpm` packages are hosted on Clever Cloud's public Nexus instance available at [https://nexus.clever-cloud.com](https://nexus.clever-cloud.com) + +#### Debian/Ubuntu (.deb) + +If you use a GNU/Linux distribution that uses `.deb` packages like Debian or Ubuntu, run: + +``` +curl -fsSL https://clever-tools.clever-cloud.com/gpg/cc-nexus-deb.public.gpg.key | gpg --dearmor -o /usr/share/keyrings/cc-nexus-deb.gpg +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/cc-nexus-deb.gpg] https://nexus.clever-cloud.com/repository/deb stable main" | tee -a /etc/apt/sources.list +apt update +apt install clever-tools +``` + +> [!TIP] +> The `.deb` packages are hosted on Clever Cloud's public Nexus instance available at [https://nexus.clever-cloud.com](https://nexus.clever-cloud.com). \ +> Our PGP key is required to trust the repository + +#### Exherbo + +If you are using Exherbo, run: + +``` +cave resolve repository/CleverCloud -zx1 +cave resolve clever-tools-bin -zx +``` + +#### Other distributions (.tar.gz) + +If you use another GNU/Linux distribution, download the `.tar.gz` archive and extract the binary in your `PATH`: + +``` +curl -O https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_linux.tar.gz +tar xvzf clever-tools-latest_linux.tar.gz +cp clever-tools-latest_linux/clever ~/.local/bin/ +``` + +> [!TIP] +> The packages are available on Clever Cloud's Cellar bucket: [clever-tools-latest_linux.tar.gz](https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_linux.tar.gz). \ +> Retrieve any release by replacing `latest` (path and filename) with the version number you need. + +### macOS + +#### Homebrew + +If you use macOS and you have [Homebrew](https://brew.sh) installed, run: + +``` +brew install CleverCloud/homebrew-tap/clever-tools +``` + +#### Binary (.tar.gz) + +If you use macOS, but you don't have [Homebrew](https://brew.sh) installed, download the `.tar.gz` archive and extract the binary in your `PATH`: + +``` +curl -O https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_macos.tar.gz +tar xvzf clever-tools-latest_macos.tar.gz +cp clever-tools-latest_macos/clever ~/.local/bin/ +``` + +> [!TIP] +> The packages are available on Clever Cloud's Cellar bucket: [clever-tools-latest_macos.tar.gz](https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_macos.tar.gz). \ +> Retrieve any release by replacing `latest` (path and filename) with the version number you need. + +### Windows + +#### Winget + +If you use Windows run in a terminal: + +``` +winget install CleverTools +``` + +#### Chocolatey + +If you prefer to use [Chocolatey](https://chocolatey.org), run: + +``` +choco sources add -n=clevercloud -s='https://nexus.clever-cloud.com/repository/nupkg/' +choco feature disable --name='usePackageRepositoryOptimizations' +choco install clever-tools +``` + +We need to disable `usePackageRepositoryOptimizations` feature because of [an incompatibility](https://github.com/chocolatey/choco/issues/3506) between Chocolatey and Nexus. + +#### Binary (.zip) + +You can also download the `.zip` archive and extract the binary in your `PATH`: + +```PowerShell +Invoke-WebRequest https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_win.zip -OutFile clever-tools-latest_win.zip +Expand-Archive .\clever-tools-latest_win.zip -DestinationPath . +$env:PATH += ";$(Resolve-Path .\clever-tools-latest_win\)" +``` + +> [!TIP] +> The packages are available on Clever Cloud's Cellar bucket: [clever-tools-latest_win.zip](https://clever-tools.clever-cloud.com/releases/latest/clever-tools-latest_win.zip). \ +> Retrieve any release by replacing `latest` (path and filename) with the version number you need. + +### Docker + +If you are using docker, use the image provided [here](https://hub.docker.com/r/clevercloud/clever-tools/). + +``` +docker pull clevercloud/clever-tools +docker run --rm clever-tools +``` + +#### Dockerfile + +In your `Dockerfile` copy `clever-tools` from the image itself with a simple one liner: + +```Dockerfile +COPY --from=clevercloud/clever-tools /bin/clever /usr/local/bin/clever +``` + +### Nix package manager + +If you are using Nix on NixOS or any other compatible system, the package is available in both `stable` and `unstable` channels. Follow [these instructions](https://search.nixos.org/packages?channel=unstable&show=clever-tools&from=0&size=50&sort=relevance&type=packages&query=clever-tools). + +## Application types and zones + +You can deploy applications on Clever Cloud with the following runtimes type: `docker`, `dotnet`, `elixir`, `frankenphp`, `go`, `gradle`, `haskell`, `jar`, `linux`, `maven`, `meteor`, `node`, `php`, `play1`, `play2`, `python`, `ruby`, `rust`, `sbt`, `static`, `static-apache`, `v`, `war` + +Available flavors: `pico`, `nano`, `XS`, `S`, `M`, `L`, `XL`, `2XL`, `3XL` + +Flavor `pico` is not available for the following instances: `docker`, `frankenphp`, `php`, `static-apache` + +Applications deployment zones (region): `par`, `parhds`, `fr-north-hds`, `grahds`, `ldn`, `mtl`, `rbx`, `rbxhds`, `scw`, `sgp`, `syd`, `wsw` + +## Add-on providers, plans and zones (region) + +- `mysql-addon`: + - plans: `m_med`, `m_big`, `xxs_big`, `l_big`, `xl_big`, `xxl_sml`, `xxl_hug`, `l_sml`, `xs_tny`, `s_med`, `xs_sml`, `dev`, `l_med`, `xl_med`, `xxl_med`, `xxl_big`, `m_sml`, `xs_big`, `xl_sml`, `s_sml`, `xxs_sml`, `xxs_med`, `xs_med`, `s_big` + - zones: `par`, `parhds`, `rbx`, `rbxhds`, `scw`, `ldn`, `sgp`, `grahds`, `wsw`, `mtl`, `syd` + +- `mongodb-addon`: + - plans: `xl_big`, `xs_med`, `m_big`, `xl_sml`, `xxl_sml`, `s_sml`, `m_sml`, `xxl_med`, `dev`, `m_med`, `xs_sml`, `s_med`, `xl_med`, `l_sml`, `m_hug`, `xs_big`, `s_hug`, `xxl_big`, `l_big`, `l_med`, `s_big` + - zones: `par`, `rbx`, `scw`, `ldn`, `sgp`, `wsw`, `mtl`, `syd` + +- `config-provider`: + - plans: `std` + - zones: `par`, `parhds` + +- `otoroshi`: + - plans: `base` + - zones: `par`, `rbx`, `rbxhds`, `scw`, `sgp`, `fr-north-hds`, `grahds`, `wsw`, `mtl`, `syd` + +- `kv`: + - plans: `alpha` + - zones: `par` + +- `addon-matomo`: + - plans: `beta` + - zones: `par`, `rbx`, `scw`, `sgp`, `wsw`, `mtl`, `syd` + +- `postgresql-addon`: + - plans: `xs_sml`, `xl_hug`, `xxs_sml`, `xl_sml`, `xs_big`, `xs_tny`, `xxl_sml`, `xxs_med`, `l_big`, `m_sml`, `l_sml`, `xxxl_sml`, `m_big`, `s_hug`, `xxxl_med`, `xxxl_big`, `s_sml`, `l_gnt`, `xxl_hug`, `xxl_med`, `s_med`, `m_med`, `xxl_big`, `xxs_big`, `l_med`, `xl_med`, `s_big`, `xl_gnt`, `dev`, `xl_big`, `xs_med` + - zones: `par`, `parhds`, `rbx`, `rbxhds`, `scw`, `ldn`, `sgp`, `grahds`, `wsw`, `mtl`, `syd` + +- `azimutt`: + - plans: `team-3`, `solo`, `team-5`, `team-4`, `team`, `free`, `team-2`, `enterprise` + - zones: `par` + +- `mailpace`: + - plans: `clever_solo`, `clever_scaling_10`, `clever_scaling_70`, `clever_scaling_50`, `clever_scaling_20`, `clever_scaling_30`, `clever_scaling_100`, `clever_scaling_40` + - zones: `par` + +- `jenkins`: + - plans: `M`, `XS`, `L`, `XL`, `S` + - zones: `par`, `rbxhds`, `scw`, `ldn`, `grahds` + +- `metabase`: + - plans: `base` + - zones: `par`, `rbx`, `rbxhds`, `scw`, `sgp`, `fr-north-hds`, `grahds`, `wsw`, `mtl`, `syd` + +- `cellar-addon`: + - plans: `S` + - zones: `par`, `parhds`, `rbxhds`, `fr-north-hds` + +- `fs-bucket`: + - plans: `s` + - zones: `par`, `rbx`, `scw`, `ldn`, `sgp`, `wsw`, `mtl`, `syd` + +- `keycloak`: + - plans: `base` + - zones: `par`, `rbx`, `scw`, `sgp`, `wsw`, `mtl`, `syd` + +- `addon-pulsar`: + - plans: `beta` + - zones: `par`, `parhds` + +- `es-addon`: + - plans: `xs`, `xl`, `l`, `4xl`, `xxxl`, `xxl`, `s`, `m`, `5xl` + - zones: `par`, `parhds`, `rbx`, `rbxhds`, `scw`, `ldn`, `sgp`, `grahds`, `wsw`, `mtl`, `syd` + +- `redis-addon`: + - plans: `m_mono`, `xxxxl_mono`, `s_mono`, `l_mono`, `xxxl_mono`, `xl_mono`, `xxl_mono` + - zones: `par`, `parhds`, `rbx`, `rbxhds`, `scw`, `ldn`, `sgp`, `grahds`, `wsw`, `mtl`, `syd` + +Default deployment zone is `par`, default plan is the lowest available. + +# How to use Clever Tools, CLI reference + +``` +Usage: clever +``` + +**Description:** CLI tool to manage Clever Cloud's data and products + +**Options:** +``` +[--help, -?] Display help about this program (default: false) +[--version, -V] Display the version of this program (default: false) +[--color] Choose whether to print colors or not. You can also use --no-color (default: true) +[--update-notifier] Choose whether to use update notifier or not. You can also use --no-update-notifier (default: true) +[--verbose, -v] Verbose output (default: false) +``` + +**Note:** The options listed above (`--help`, `--version`, `--color`, `--update-notifier`, `--verbose`) are available for all Clever Tools commands and sub-commands +## accesslogs + +``` +Usage: accesslogs +``` + +**Description:** Fetch access logs + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json, json-stream) (default: human) +[--before, --until] BEFORE Fetch logs before this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h) +[--after, --since] AFTER Fetch logs after this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h) +[--addon] ADDON_ID Add-on ID +``` + +## activity + +``` +Usage: activity +``` + +**Description:** Show last deployments of an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--follow, -f] Track new deployments in activity list (default: false) +[--show-all] Show all activity (default: false) +[--format, -F] FORMAT Output format (human, json, json-stream) (default: human) +``` + +## addon + +``` +Usage: addon +``` + +**Description:** Manage add-ons + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### addon create + +``` +Usage: create ADDON-PROVIDER ADDON-NAME +``` + +**Description:** Create an add-on + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--link, -l] ALIAS Link the created add-on to the app with the specified alias +[--yes, -y] Skip confirmation even if the add-on is not free (default: false) +[--plan, -p] PLAN Add-on plan, depends on the provider (default: ) +[--region, -r] REGION Region to provision the add-on in, depends on the provider (default: par) +[--addon-version] ADDON-VERSION The version to use for the add-on +[--option] OPTION Option to enable for the add-on. Multiple --option argument can be passed to enable multiple options +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### addon delete + +``` +Usage: delete ADDON-ID +``` + +**Description:** Delete an add-on + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--yes, -y] Skip confirmation and delete the add-on directly (default: false) +``` + +### addon rename + +``` +Usage: rename ADDON-ID ADDON-NAME +``` + +**Description:** Rename an add-on + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +``` + +### addon list + +``` +Usage: list +``` + +**Description:** List available add-ons + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### addon providers + +``` +Usage: providers +``` + +**Description:** List available add-on providers + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +#### addon providers show + +``` +Usage: show ADDON-PROVIDER +``` + +**Description:** Show information about an add-on provider + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### addon env + +``` +Usage: env ADDON +``` + +**Description:** List environment variables for an add-on + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json, shell) (default: human) +``` + +## applications + +``` +Usage: applications +``` + +**Description:** List linked applications + +**Options:** +``` +[--only-aliases] List only application aliases (default: false) +[--json, -j] Show result in JSON format (default: false) +``` + +### applications list + +``` +Usage: list +``` + +**Description:** List all applications + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +## cancel-deploy + +``` +Usage: cancel-deploy +``` + +**Description:** Cancel an ongoing deployment + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +## config + +``` +Usage: config +``` + +**Description:** Display or edit the configuration of your application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +### config get + +``` +Usage: get CONFIGURATION-NAME +``` + +**Description:** Display the current configuration + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +### config set + +``` +Usage: set CONFIGURATION-NAME CONFIGURATION-VALUE +``` + +**Description:** Edit one configuration setting + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +### config update + +``` +Usage: update +``` + +**Description:** Edit multiple configuration settings at once + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--name] Set name +[--description] Set description +[--enable-zero-downtime] Enable zero-downtime (default: false) +[--disable-zero-downtime] Disable zero-downtime (default: false) +[--enable-sticky-sessions] Enable sticky-sessions (default: false) +[--disable-sticky-sessions] Disable sticky-sessions (default: false) +[--enable-cancel-on-push] Enable cancel-on-push (default: false) +[--disable-cancel-on-push] Disable cancel-on-push (default: false) +[--enable-force-https] Enable force-https (default: false) +[--disable-force-https] Disable force-https (default: false) +[--enable-task] Enable task (default: false) +[--disable-task] Disable task (default: false) +``` + +## console + +``` +Usage: console +``` + +**Description:** Open an application in the Console + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +## create + +``` +Usage: create --type TYPE [APP-NAME] +``` + +**Description:** Create an application + +**Options:** +``` +--type, -t TYPE Instance type +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--alias, -a] ALIAS Short name for the application +[--region, -r] ZONE Region, can be 'par', 'parhds', 'grahds', 'rbx', 'rbxhds', 'scw', 'ldn', 'mtl', 'sgp', 'syd', 'wsw' (default: par) +[--github] OWNER/REPO GitHub application to use for deployments +[--task, -T] COMMAND The application launch as a task executing the given command, then stopped +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +## curl + +``` +Usage: clever curl +``` + +**Description:** Query Clever Cloud's API using Clever Tools credentials. For example: + +## database + +``` +Usage: database +``` + +**Description:** List available databases + +### database backups + +``` +Usage: backups DATABASE-ID +``` + +**Description:** List available database backups + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +#### database backups download + +``` +Usage: download DATABASE-ID BACKUP-ID +``` + +**Description:** Download a database backup + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +[--output, --out] Redirect the output of the command in a file +``` + +## delete + +``` +Usage: delete +``` + +**Description:** Delete an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--yes, -y] Skip confirmation and delete the application directly (default: false) +``` + +## deploy + +``` +Usage: deploy +``` + +**Description:** Deploy an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--branch, -b] BRANCH Branch to push (current branch by default) (default: ) +[--tag, -t] TAG Tag to push (none by default) (default: ) +[--quiet, -q] Don't show logs during deployment (default: false) +[--force, -f] Force deploy even if it's not fast-forwardable (default: false) +[--follow] Continue to follow logs after deployment has ended (default: false) +[--same-commit-policy, -p] POLICY What to do when local and remote commit are identical (error, ignore, restart, rebuild) (default: error) +[--exit-on, -e] STEP Step at which the logs streaming is ended, steps are: deploy-start, deploy-end, never (default: deploy-end) +``` + +## diag + +``` +Usage: diag +``` + +**Description:** Diagnose the current installation (prints various informations for support) + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +## domain + +``` +Usage: domain +``` + +**Description:** Manage domain names for an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +### domain add + +``` +Usage: add FQDN +``` + +**Description:** Add a domain name to an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +### domain favourite + +``` +Usage: favourite +``` + +**Description:** Manage the favourite domain name for an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +#### domain favourite set + +``` +Usage: set FQDN +``` + +**Description:** Set the favourite domain for an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +#### domain favourite unset + +``` +Usage: unset +``` + +**Description:** Unset the favourite domain for an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +### domain rm + +``` +Usage: rm FQDN +``` + +**Description:** Remove a domain name from an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +### domain diag + +``` +Usage: diag +``` + +**Description:** Check if domains associated to a specific app are properly configured + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +[--filter] TEXT Check only domains containing the provided text (default: ) +``` + +### domain overview + +``` +Usage: overview +``` + +**Description:** Get an overview of all your domains (all orgas, all apps) + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +[--filter] TEXT Get only domains containing the provided text (default: ) +``` + +## drain + +``` +Usage: drain +``` + +**Description:** Manage drains + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--addon] ADDON_ID Add-on ID +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### drain create + +``` +Usage: create DRAIN-TYPE DRAIN-URL +``` + +**Description:** Create a drain + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--addon] ADDON_ID Add-on ID +[--username, -u] USERNAME (HTTP drains) basic auth username +[--password, -p] PASSWORD (HTTP drains) basic auth password +[--api-key, -k] API_KEY (NewRelic drains) API key +[--index-prefix, -i] INDEX_PREFIX (ElasticSearch drains) optional index prefix. `logstash` value is used if not set +[--sd-params, -s] SD_PARAMS (TCP and UDP drains) sd-params string (e.g.: `X-OVH-TOKEN=\"REDACTED\"`) +``` + +### drain remove + +``` +Usage: remove DRAIN-ID +``` + +**Description:** Remove a drain + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--addon] ADDON_ID Add-on ID +``` + +### drain enable + +``` +Usage: enable DRAIN-ID +``` + +**Description:** Enable a drain + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--addon] ADDON_ID Add-on ID +``` + +### drain disable + +``` +Usage: disable DRAIN-ID +``` + +**Description:** Disable a drain + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--addon] ADDON_ID Add-on ID +``` + +## emails + +``` +Usage: emails +``` + +**Description:** Manage email addresses of the current user + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### emails add + +``` +Usage: add EMAIL +``` + +**Description:** Add a new secondary email address to the current user + +### emails primary + +``` +Usage: primary EMAIL +``` + +**Description:** Set the primary email address of the current user + +### emails remove + +``` +Usage: remove EMAIL +``` + +**Description:** Remove a secondary email address from the current user + +### emails remove-all + +``` +Usage: remove-all +``` + +**Description:** Remove all secondary email addresses from the current user + +**Options:** +``` +[--yes, -y] Skip confirmation (default: false) +``` + +### emails open + +``` +Usage: open +``` + +**Description:** Open the email addresses management page in the Console + +## env + +``` +Usage: env +``` + +**Description:** Manage environment variables of an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--add-export] Display sourceable env variables setting (default: false) +[--format, -F] FORMAT Output format (human, json, shell) (default: human) +``` + +### env set + +``` +Usage: set VARIABLE-NAME VARIABLE-VALUE +``` + +**Description:** Add or update an environment variable named with the value + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--add-export] Display sourceable env variables setting (default: false) +``` + +### env rm + +``` +Usage: rm VARIABLE-NAME +``` + +**Description:** Remove an environment variable from an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--add-export] Display sourceable env variables setting (default: false) +``` + +### env import + +``` +Usage: import +``` + +**Description:** Load environment variables from STDIN + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--add-export] Display sourceable env variables setting (default: false) +[--json] Import variables as JSON (an array of { "name": "THE_NAME", "value": "THE_VALUE" } objects) (default: false) +``` + +### env import-vars + +``` +Usage: import-vars VARIABLE-NAMES +``` + +**Description:** Add or update environment variables named (comma-separated), taking their values from the current environment + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--add-export] Display sourceable env variables setting (default: false) +``` + +## features + +``` +Usage: features +``` + +**Description:** Manage Clever Tools experimental features + +### features enable + +``` +Usage: enable FEATURES +``` + +**Description:** Enable experimental features + +### features disable + +``` +Usage: disable FEATURES +``` + +**Description:** Disable experimental features + +### features list + +``` +Usage: list +``` + +**Description:** List available experimental features + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### features info + +``` +Usage: info FEATURE +``` + +**Description:** Display info about an experimental feature + +## help + +``` +Usage: help +``` + +**Description:** Display help about the Clever Cloud CLI + +## keycloak + +``` +Usage: keycloak +``` + +**Description:** Manage Clever Cloud Keycloak services [BETA] + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### keycloak get + +``` +Usage: get ADDON-ID +``` + +**Description:** Get information about a deployed Keycloak + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### keycloak enable-ng + +``` +Usage: enable-ng ADDON-ID +``` + +**Description:** Link Keycloak to a Network Group, used for multi-instances secure communication + +### keycloak disable-ng + +``` +Usage: disable-ng ADDON-ID +``` + +**Description:** Unlink Keycloak from its Network Group + +### keycloak open + +``` +Usage: open ADDON-ID +``` + +**Description:** Open the Keycloak dashboard in Clever Cloud Console + +#### keycloak open logs + +``` +Usage: logs ADDON-ID +``` + +**Description:** Open the Keycloak application logs in Clever Cloud Console + +#### keycloak open webui + +``` +Usage: webui ADDON-ID +``` + +**Description:** Open the Keycloak admin console in your browser + +### keycloak restart + +``` +Usage: restart ADDON-ID +``` + +**Description:** Restart Keycloak + +### keycloak rebuild + +``` +Usage: rebuild ADDON-ID +``` + +**Description:** Rebuild Keycloak + +### keycloak version + +``` +Usage: version ADDON-ID +``` + +**Description:** Check Keycloak deployed version + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +#### keycloak version check + +``` +Usage: check ADDON-ID +``` + +**Description:** Check Keycloak deployed version + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +#### keycloak version update + +``` +Usage: update ADDON-ID +``` + +**Description:** Update Keycloak deployed version + +**Options:** +``` +[--target] VERSION Target version to upgrade to (e.g.: 24, 2.4, 2.4.1) +``` + +## kv + +``` +Usage: kv KV-ID COMMAND +``` + +**Description:** Send a raw command to a Materia KV or Redis® add-on [ALPHA] + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +## link + +``` +Usage: link APP-ID +``` + +**Description:** Link this repo to an existing application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +``` + +## login + +``` +Usage: login +``` + +**Description:** Login to Clever Cloud + +**Options:** +``` +[--token] TOKEN Directly give an existing token +[--secret] SECRET Directly give an existing secret +``` + +## logout + +``` +Usage: logout +``` + +**Description:** Logout from Clever Cloud + +## logs + +``` +Usage: logs +``` + +**Description:** Fetch application logs, continuously + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--before, --until] BEFORE Fetch logs before this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h) +[--after, --since] AFTER Fetch logs after this date/time (ISO8601 date, positive number in seconds or duration, e.g.: 1h) +[--search] SEARCH Fetch logs matching this pattern +[--deployment-id] DEPLOYMENT_ID Fetch logs for a given deployment +[--addon] ADDON_ID Add-on ID +[--format, -F] FORMAT Output format (human, json, json-stream) (default: human) +``` + +## make-default + +``` +Usage: make-default APP-ALIAS +``` + +**Description:** Make a linked application the default one + +## matomo + +``` +Usage: matomo +``` + +**Description:** Manage Clever Cloud Matomo services [BETA] + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### matomo get + +``` +Usage: get ADDON-ID +``` + +**Description:** Get information about a deployed Matomo + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### matomo open + +``` +Usage: open ADDON-ID +``` + +**Description:** Open the Matomo dashboard in Clever Cloud Console + +#### matomo open logs + +``` +Usage: logs ADDON-ID +``` + +**Description:** Open the Matomo application logs in Clever Cloud Console + +#### matomo open webui + +``` +Usage: webui ADDON-ID +``` + +**Description:** Open the Matomo admin console in your browser + +### matomo restart + +``` +Usage: restart ADDON-ID +``` + +**Description:** Restart Matomo + +### matomo rebuild + +``` +Usage: rebuild ADDON-ID +``` + +**Description:** Rebuild Matomo + +## metabase + +``` +Usage: metabase +``` + +**Description:** Manage Clever Cloud Metabase services [BETA] + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### metabase get + +``` +Usage: get ADDON-ID +``` + +**Description:** Get information about a deployed Metabase + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### metabase open + +``` +Usage: open ADDON-ID +``` + +**Description:** Open the Metabase dashboard in Clever Cloud Console + +#### metabase open logs + +``` +Usage: logs ADDON-ID +``` + +**Description:** Open the Metabase application logs in Clever Cloud Console + +#### metabase open webui + +``` +Usage: webui ADDON-ID +``` + +**Description:** Open the Metabase admin console in your browser + +### metabase restart + +``` +Usage: restart ADDON-ID +``` + +**Description:** Restart Metabase + +### metabase rebuild + +``` +Usage: rebuild ADDON-ID +``` + +**Description:** Rebuild Metabase + +### metabase version + +``` +Usage: version ADDON-ID +``` + +**Description:** Manage Metabase deployed version + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +#### metabase version check + +``` +Usage: check ADDON-ID +``` + +**Description:** Check Metabase deployed version + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +#### metabase version update + +``` +Usage: update ADDON-ID +``` + +**Description:** Update Metabase deployed version + +**Options:** +``` +[--target] VERSION Target version to upgrade to (e.g.: 24, 2.4, 2.4.1) +``` + +## ng + +``` +Usage: ng +``` + +**Description:** List Network Groups [BETA] + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### ng create + +``` +Usage: create NG-LABEL +``` + +**Description:** Create a Network Group + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--link] MEMBERS_IDS Comma separated list of members IDs to link to a Network Group ('app_xxx', 'addon_xxx', 'external_xxx') +[--description] DESCRIPTION Network Group description +[--tags] TAGS List of tags, separated by a comma +``` + +#### ng create external + +``` +Usage: external EXTERNAL-PEER-LABEL NG-ID-OR-LABEL PUBLIC-KEY +``` + +**Description:** Create an external peer in a Network Group + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +``` + +### ng delete + +``` +Usage: delete NG-ID-OR-LABEL +``` + +**Description:** Delete a Network Group + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +``` + +#### ng delete external + +``` +Usage: external EXTERNAL-PEER-ID-OR-LABEL NG-ID-OR-LABEL +``` + +**Description:** Delete an external peer from a Network Group + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +``` + +### ng link + +``` +Usage: link ID-OR-LABEL NG-ID-OR-LABEL +``` + +**Description:** Link an application or a database add-on by its ID to a Network Group + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +``` + +### ng unlink + +``` +Usage: unlink ID-OR-LABEL NG-ID-OR-LABEL +``` + +**Description:** Unlink an application or a database add-on by its ID from a Network Group + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +``` + +### ng get + +``` +Usage: get ID-OR-LABEL +``` + +**Description:** Get details about a Network Group, a member or a peer + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--type] TYPE Type of resource to look for (NetworkGroup, Member, CleverPeer, ExternalPeer) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### ng get-config + +``` +Usage: get-config EXTERNAL-PEER-ID-OR-LABEL NG-ID-OR-LABEL +``` + +**Description:** Get the Wireguard configuration of a peer in a Network Group + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### ng search + +``` +Usage: search ID-OR-LABEL +``` + +**Description:** Search Network Groups, members or peers and get their details + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--type] TYPE Type of resource to look for (NetworkGroup, Member, CleverPeer, ExternalPeer) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +## notify-email + +``` +Usage: notify-email +``` + +**Description:** Manage email notifications + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--list-all] List all notifications for your user or for an organisation with the '--org' option (default: false) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### notify-email add + +``` +Usage: add --notify ||"ORGANISATION" NAME +``` + +**Description:** Add a new email notification + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--list-all] List all notifications for your user or for an organisation with the '--org' option (default: false) +[--event] TYPE Restrict notifications to specific event types +[--service] SERVICE_ID Restrict notifications to specific applications and add-ons +--notify ||"ORGANISATION" Notify a user, a specific email address or the whole organisation (multiple values allowed, comma separated) +``` + +### notify-email remove + +``` +Usage: remove NOTIFICATION-ID +``` + +**Description:** Remove an existing email notification + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--list-all] List all notifications for your user or for an organisation with the '--org' option (default: false) +``` + +## open + +``` +Usage: open +``` + +**Description:** Open an application in the Console + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +## otoroshi + +``` +Usage: otoroshi +``` + +**Description:** Manage Clever Cloud Otoroshi services [BETA] + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### otoroshi get + +``` +Usage: get ADDON-ID +``` + +**Description:** Get information about a deployed Otoroshi + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### otoroshi enable-ng + +``` +Usage: enable-ng ADDON-ID +``` + +**Description:** Link Otoroshi to a Network Group + +### otoroshi disable-ng + +``` +Usage: disable-ng ADDON-ID +``` + +**Description:** Unlink Otoroshi from its Network Group + +### otoroshi open + +``` +Usage: open ADDON-ID +``` + +**Description:** Open the Otoroshi dashboard in Clever Cloud Console + +#### otoroshi open logs + +``` +Usage: logs ADDON-ID +``` + +**Description:** Open the Otoroshi application logs in Clever Cloud Console + +#### otoroshi open webui + +``` +Usage: webui ADDON-ID +``` + +**Description:** Open the Otoroshi admin console in your browser + +### otoroshi restart + +``` +Usage: restart ADDON-ID +``` + +**Description:** Restart Otoroshi + +### otoroshi rebuild + +``` +Usage: rebuild ADDON-ID +``` + +**Description:** Rebuild Otoroshi + +### otoroshi version + +``` +Usage: version ADDON-ID +``` + +**Description:** Manage Otoroshi deployed version + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +#### otoroshi version check + +``` +Usage: check ADDON-ID +``` + +**Description:** Check Otoroshi deployed version + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +#### otoroshi version update + +``` +Usage: update ADDON-ID +``` + +**Description:** Update Otoroshi deployed version + +**Options:** +``` +[--target] VERSION Target version to upgrade to (e.g.: 24, 2.4, 2.4.1) +``` + +## profile + +``` +Usage: profile +``` + +**Description:** Display the profile of the current user + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### profile open + +``` +Usage: open +``` + +**Description:** Open your profile in the Console + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +## published-config + +``` +Usage: published-config +``` + +**Description:** Manage the configuration made available to other applications by this application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json, shell) (default: human) +``` + +### published-config set + +``` +Usage: set VARIABLE-NAME VARIABLE-VALUE +``` + +**Description:** Add or update a published configuration item named with the value + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +### published-config rm + +``` +Usage: rm VARIABLE-NAME +``` + +**Description:** Remove a published configuration variable from an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +### published-config import + +``` +Usage: import +``` + +**Description:** Load published configuration from STDIN + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--json] Import variables as JSON (an array of { "name": "THE_NAME", "value": "THE_VALUE" } objects) (default: false) +``` + +## restart + +``` +Usage: restart +``` + +**Description:** Start or restart an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--commit] COMMIT ID Restart the application with a specific commit ID +[--without-cache] Restart the application without using cache (default: false) +[--quiet, -q] Don't show logs during deployment (default: false) +[--follow] Continue to follow logs after deployment has ended (default: false) +[--exit-on, -e] STEP Step at which the logs streaming is ended, steps are: deploy-start, deploy-end, never (default: deploy-end) +``` + +## scale + +``` +Usage: scale +``` + +**Description:** Change scalability of an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--flavor] FLAVOR The instance size of your application +[--min-flavor] MINFLAVOR The minimum scale size of your application +[--max-flavor] MAXFLAVOR The maximum instance size of your application +[--instances] INSTANCES The number of parallel instances +[--min-instances] MININSTANCES The minimum number of parallel instances +[--max-instances] MAXINSTANCES The maximum number of parallel instances +[--build-flavor] BUILDFLAVOR The size of the build instance, or 'disabled' if you want to disable dedicated build instances +``` + +## service + +``` +Usage: service +``` + +**Description:** Manage service dependencies + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--only-apps] Only show app dependencies (default: false) +[--only-addons] Only show add-on dependencies (default: false) +[--show-all] Show all available add-ons and applications (default: false) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### service link-app + +``` +Usage: link-app APP-ID +``` + +**Description:** Add an existing app as a dependency + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--only-apps] Only show app dependencies (default: false) +[--only-addons] Only show add-on dependencies (default: false) +[--show-all] Show all available add-ons and applications (default: false) +``` + +### service unlink-app + +``` +Usage: unlink-app APP-ID +``` + +**Description:** Remove an app from the dependencies + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--only-apps] Only show app dependencies (default: false) +[--only-addons] Only show add-on dependencies (default: false) +[--show-all] Show all available add-ons and applications (default: false) +``` + +### service link-addon + +``` +Usage: link-addon ADDON-ID +``` + +**Description:** Link an existing add-on to this application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--only-apps] Only show app dependencies (default: false) +[--only-addons] Only show add-on dependencies (default: false) +[--show-all] Show all available add-ons and applications (default: false) +``` + +### service unlink-addon + +``` +Usage: unlink-addon ADDON-ID +``` + +**Description:** Unlink an add-on from this application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--only-apps] Only show app dependencies (default: false) +[--only-addons] Only show add-on dependencies (default: false) +[--show-all] Show all available add-ons and applications (default: false) +``` + +## ssh + +``` +Usage: ssh +``` + +**Description:** Connect to running instances through SSH + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--identity-file, -i] IDENTITY-FILE SSH identity file +``` + +## ssh-keys + +``` +Usage: ssh-keys +``` + +**Description:** Manage SSH keys of the current user + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### ssh-keys add + +``` +Usage: add SSH-KEY-NAME SSH-KEY-PATH +``` + +**Description:** Add a new SSH key to the current user + +### ssh-keys remove + +``` +Usage: remove SSH-KEY-NAME +``` + +**Description:** Remove a SSH key from the current user + +### ssh-keys remove-all + +``` +Usage: remove-all +``` + +**Description:** Remove all SSH keys from the current user + +**Options:** +``` +[--yes, -y] Skip confirmation and remove all SSH keys directly (default: false) +``` + +### ssh-keys open + +``` +Usage: open +``` + +**Description:** Open the SSH keys management page in the Console + +## status + +``` +Usage: status +``` + +**Description:** See the status of an application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +## stop + +``` +Usage: stop +``` + +**Description:** Stop a running application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +``` + +## tcp-redirs + +``` +Usage: tcp-redirs +``` + +**Description:** Control the TCP redirections from reverse proxies to your application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### tcp-redirs list-namespaces + +``` +Usage: list-namespaces +``` + +**Description:** List the namespaces in which you can create new TCP redirections + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### tcp-redirs add + +``` +Usage: add --namespace NAMESPACE +``` + +**Description:** Add a new TCP redirection to the application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +--namespace NAMESPACE Namespace in which the TCP redirection should be +[--yes, -y] Skip confirmation even if the TCP redirection is not free (default: false) +``` + +### tcp-redirs remove + +``` +Usage: remove --namespace NAMESPACE PORT +``` + +**Description:** Remove a TCP redirection from the application + +**Options:** +``` +[--alias, -a] ALIAS Short name for the application +[--app] ID_OR_NAME Application to manage by its ID (or name, if unambiguous) +--namespace NAMESPACE Namespace in which the TCP redirection should be +``` + +## tokens + +``` +Usage: tokens +``` + +**Description:** Manage API tokens to query Clever Cloud API from https://api-bridge.clever-cloud.com + +**Options:** +``` +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### tokens create + +``` +Usage: create API-TOKEN-NAME +``` + +**Description:** Create an API token + +**Options:** +``` +[--expiration, -e] EXPIRATION Duration until API token expiration (e.g.: 1h, 4d, 2w, 6M), default 1y +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### tokens revoke + +``` +Usage: revoke API-TOKEN-ID +``` + +**Description:** Revoke an API token + +## unlink + +``` +Usage: unlink APP-ALIAS +``` + +**Description:** Unlink this repo from an existing application + +## version + +``` +Usage: version +``` + +**Description:** Display the clever-tools version + +## webhooks + +``` +Usage: webhooks +``` + +**Description:** Manage webhooks + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--list-all] List all notifications for your user or for an organisation with the '--org' option (default: false) +[--format, -F] FORMAT Output format (human, json) (default: human) +``` + +### webhooks add + +``` +Usage: add NAME URL +``` + +**Description:** Register webhook to be called when events happen + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--list-all] List all notifications for your user or for an organisation with the '--org' option (default: false) +[--format] FORMAT Format of the body sent to the webhook ('raw', 'slack', 'gitter', or 'flowdock') (default: raw) +[--event] TYPE Restrict notifications to specific event types +[--service] SERVICE_ID Restrict notifications to specific applications and add-ons +``` + +### webhooks remove + +``` +Usage: remove NOTIFICATION-ID +``` + +**Description:** Remove an existing webhook + +**Options:** +``` +[--org, -o, --owner] ID_OR_NAME Organisation to target by its ID (or name, if unambiguous) +[--list-all] List all notifications for your user or for an organisation with the '--org' option (default: false) +``` + +## Clever Cloud complete documentation + +For more comprehensive information about Clever Cloud, read the complete documentation: https://www.clever.cloud/developers/doc/ +Clever Cloud complete documentation is available in a LLM-optimized format: https://www.clever.cloud/developers/llms.txt diff --git a/content/doc/reference/common-configuration.md b/content/doc/reference/common-configuration.md new file mode 100644 index 000000000..fe356a225 --- /dev/null +++ b/content/doc/reference/common-configuration.md @@ -0,0 +1,63 @@ +--- +type: docs +title: Configuration on all instances +description: Learn how to do some basic setup configuration to get started +tags: +- reference +- dashboard-setup +keywords: +- common +- configuration +- hooks +aliases: +- /doc/develop/common-configuration +--- + +Each instance type (php,java,python,go,ruby…) has its own configuration. However, some of +these configuration items can be applied to any instance. + +## Private SSH Key + +If your company manages its own artifacts in a private repository (like, you +can only access them via git+ssh or sftp), and you need a private key to +connect to the server, you can either set it in an environment variable or +commit it in your application's Clever Cloud repository. + +That key will be installed in `~/.ssh/` before the start of the build. So the +dependency manager will use it to fetch libs only accessible by ssh. + +{{< callout type="info" >}} + Please provide a key without pass phrase, or the system will be unable to unlock it +{{< /callout >}} + +### Environment variable + +Set your key as the value of the `CC_SSH_PRIVATE_KEY` variable. If you want it +to be saved to a specific file, you can set the `CC_SSH_PRIVATE_KEY_FILE` +variable. + +### Committed file + +First, you need to add the file `clevercloud/ssh.json`, its content is pretty straight-forward: + +```json +{ + "privateKeyFile": "path/to/file" +} +``` + +The `privateKeyFile` field must be a path to an SSH private key. The path must be relative to the root of your repository. + +For example, if your private key file is in the `clevercloud` folder and is named `my_key`, the `privateKeyFile` field will be `"clevercloud/my_key"`. + +## Hooks + +You can run specific tasks during the deployment of your application. + +Please refer to the [hooks documentation](/developers/doc/develop/build-hooks) to learn more about them. + +## Workers + +You can run background tasks running in parallel of your application. + +Please refer to the [workers documentation](/developers/doc/develop/workers) to learn more about them. diff --git a/content/doc/reference/products-support.md b/content/doc/reference/products-support.md new file mode 100644 index 000000000..22845eec1 --- /dev/null +++ b/content/doc/reference/products-support.md @@ -0,0 +1,38 @@ +--- +type: docs +title: Product support on tools +description: Get product support on each official tools +--- +This is a product matrix showing the services that are available with our Terraform provider and K8S-Operator. + +## Add-ons available on Terraform and K8S-Operator + +| Product | Terraform | K8S operator | +|----------------|-----------|--------------| +| Materia KV | ✅ | ✅ | +| Cellar | ✅ | | +| Keycloak | ✅ | | +| Metabase | ✅ | | +| MongoDB | ✅ | ✅ | +| PostgreSQL | ✅ | ✅ | +| Redis | ✅ | ✅ | +| MySql | | ✅ | +| Pulsar | | ✅ | +| ConfigProvider | | ✅ | +| ElasticSearch | | ✅ | +| FS Bucket | ✅ | | +| Jenkins | | | +| Matomo | | | +| Otoroshi | | | + +## Runtimes available on Terraform and K8S-Operator + +| Product| Terraform | K8S operator | +|--------|-----------|--------------| +| Docker | ✅ | | +| Java | ✅ | | +| PHP | ✅ | | +| Scala | ✅ | | +| Static | ✅ | | +| NodeJS | ✅ | | +| Python | ✅ | | diff --git a/content/doc/reference/reference-environment-variables.md b/content/doc/reference/reference-environment-variables.md new file mode 100644 index 000000000..e596dd626 --- /dev/null +++ b/content/doc/reference/reference-environment-variables.md @@ -0,0 +1,621 @@ +--- +type: docs +linktitle: EnvVar Reference +title: Environment Variable Reference +description: List of all the environment variable references +tags: +- reference +keywords: +- env +- env variables +aliases: +- /doc/admin-console/environment-variables +- /doc/env-variables +- /doc/get-help/reference-environment-variables +- /get-help/reference-environment-variables +- /reference/reference-environment-variables +--- + +## Commons to all applications + +### Set by the deployment process + +These are read-only variables that are generated for each scaler before they build and start your application. + +| Name | Description | Example value | +|-----------------------|------------------------------|--------------------------------| +|[`INSTANCE_NUMBER`](/developers/doc/develop/env-variables/#what-is-the-instance_number-variable-used-for "What is the INSTANCE_NUMBER variable used for?") | Allows your application to differentiate each running node on the application level. | 0, 1… | +|`INSTANCE_TYPE` | Whether this instance is a "build" instance or a "production" instance. | build, production | +|`INSTANCE_ID` | The ID of the current instance (scaler) of your application. It's unique for each instance of your application and changes every time you deploy it. | 518c8d8f-e304-4310-81e0-9c4237d55645 | +|`CC_PRETTY_INSTANCE_NAME` | The random generated string as instance pretty name using pokemon names. | Tiny rhyhorn | +|`APP_ID` | The ID of your Clever Cloud application | app_649a93d1-6677-44bc-aca7-6f46107d6e02 | +|`APP_HOME` | The absolute path to your application folder | /home/bas/app_649a93d1-6677-44bc-aca7-6f46107d6e02 | +|`CC_DEPLOYMENT_ID` | Internal id of current deployment | f7efaf04-1a63-45a1-8503-0de7c750ee48 | +|`CC_COMMIT_ID` | The id of the commit that's currently running | d88cd2ae1aaa91923ed2bd689d95d713b6f3f45f | +|`CC_REVERSE_PROXY_IPS` | A comma separated list of trusted IP addresses. You should only accept requests coming from these IP addresses. | x.y.z.z,x.y.z.z | +|`ELASTIC_APM_SERVICE_NAME` | Sets the name of your service/application in Elastic APM. Automatically defined when you have linked an Elastic APM service to your application. You can override it by defining it yourself | Your application's name conforming to Elastic APM naming convention | +|`CC_APP_NAME` | The customer defined application name | cloud-api-production | +|`PORT` | The mandatory port value is 8080 | 8080 | + +### Variables you can define + +So you can alter the build&start process for your application. + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|`APP_FOLDER` | Folder in which the application is located (inside the git repository) | | +|`CC_DISABLE_JVM_AGENT` | Disable JVM agent activation | | +|`CC_GIT_FULL_CLONE` | If set to `false`, the git repository is cloned with `--depth 1` to speed up the deployment | true | +|`CC_DISABLE_GIT_SUBMODULES` | Disable Git submodules initialization & synchronization | | +|`CC_PREVENT_LOGSCOLLECTION` | Disable Vector service used to collect and send logs | `false`| +|[`CC_HEALTH_CHECK_PATH`](/developers/doc/develop/healthcheck) | Custom path to validate your application deployment | | +|`CC_SSH_PRIVATE_KEY` | A ssh private key to setup for the user running your application | | +|`CC_SSH_PRIVATE_KEY_FILE` | The name to use for the file containing the private ssh key | id_ed25519 | +|`CC_WORKER_RESTART` | One of `always`, `on-failure` or `no`. Control whether workers need to be restarted when they exit. This setting controls all workers. | on-failure | +|`CC_WORKER_RESTART_DELAY` | Define a delay in seconds to restart the worker when they exit. | 1 | +|[`CC_WORKER_COMMAND`](/developers/doc/develop/workers) | Command to run in background as a worker process. You can run multiple workers. | | + +You can set some tools' version in any runtime (except Docker): + +| Name | Description | +|------|-------------| +| `CC_HUGO_VERSION` | Set the Hugo version, for example `0.147` | | +| `CC_NODE_VERSION` | Set Node.js version, for example `24`, `23.11` or `22.15.1` | | + +#### Control build and dependencies cache + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|`CC_CACHE_DEPENDENCIES` | Enable caching of your build dependencies to speed up following builds. | false | +|[`CC_DISABLE_BUILD_CACHE_UPLOAD`](/developers/doc/develop/env-variables/#settings-you-can-define-using-environment-variables "Settings you can define using environment variables") | Disable creation and upload of cache archive. Restarts won't be speeded up. | `false` | +|[`CC_IGNORE_FROM_BUILDCACHE`](/developers/doc/develop/env-variables/#settings-you-can-define-using-environment-variables "Settings you can define using environment variables") | Allows to specify paths to ignore when the build cache archive is created. | | +|[`IGNORE_FROM_BUILDCACHE`](/developers/doc/develop/env-variables/#settings-you-can-define-using-environment-variables "Settings you can define using environment variables") | (Deprecated) Allows to specify paths to ignore when the build cache archive is created. | | +|[`CC_OVERRIDE_BUILDCACHE`](/developers/doc/develop/env-variables/#settings-you-can-define-using-environment-variables "Settings you can define using environment variables") | Allows to specify paths that will be in the build cache. Only those files / directories will be cached | | + +#### Control the deployment's behavior + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|`CC_RUN_COMMAND` | Custom command to run your application. | | +|`CC_TASK` | If set to true, the deployer runs `CC_RUN_COMMAND` and terminates the instance after running the task. Trigger an execution using `git push` or starting your instance | false | +|[`CC_TROUBLESHOOT`](/developers/doc/find-help/troubleshooting "Troubleshooting") | Enable debug log level, will also keep the VM up after failure for 15 minutes so you can SSH and debug. Don't forget to cancel deployment if you push a new commit. | false | + +{{< callout emoji="🐳" >}} + `CC_RUN_COMMAND` has no effect on Docker. To run Docker, use `CMD` in your [Dockerfile](/developers/doc/applications/docker/#dockerized-rust-application-deployment). +{{< /callout >}} + +#### Deployment hooks + +Use these to define [commands to run](/developers/doc/develop/build-hooks) between various steps of the deployment. + +| Name | Description | +|-----------------------|------------------------------| +|[`CC_PRE_BUILD_HOOK`](/developers/doc/develop/build-hooks/#pre-build "Pre build hook") | Ran before the dependencies are fetched. If it fails, the deployment fails. | +|[`CC_POST_BUILD_HOOK`](/developers/doc/develop/build-hooks/#post-build "Post build hook") | Ran after the project is built, and before the cache archive is generated. If it fails, the deployment fails. | +|[`CC_PRE_RUN_HOOK`](/developers/doc/develop/build-hooks/#pre-run "Pre run hook") | Ran before the application is started, but after the cache archive has been generated. If it fails, the deployment fails. | +|[`CC_RUN_FAILED_HOOK`](/developers/doc/develop/build-hooks/#run-successfail "Run succeeded/failed hook") | Ran once the application has failed to start. | +|[`CC_RUN_SUCCEEDED_HOOK`](/developers/doc/develop/build-hooks/#run-successfail "Run succeeded/failed hook" )| Ran once the application has started successfuly. | + +#### Configure extra software + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|[`CC_CLAMAV`](/developers/doc/administrate/clamav "Clamav") | Start the clamav and clamav-freshclam services (the database is updated every 2 hours). WARNING: Clamscan consumes a lot of resources (~ 1GB of memory), make sure you have a scaler with enough memory to avoid OOM. | false | +|[`CC_CLAMAV_MAXQUEUE`](/developers/doc/administrate/clamav "Clamav") | Maximum number of queued items. | 100 | +|[`CC_CLAMAV_MAXTHREADS`](/developers/doc/administrate/clamav "Clamav") | Maximum number of threads running at the same time. | 10 | +|[`CC_METRICS_PROMETHEUS_PASSWORD`](/developers/doc/metrics/#publish-your-own-metrics "Publish your own metrics") | Define the password for the basic auth of the Prometheus endpoint | | +|[`CC_METRICS_PROMETHEUS_PATH`](/developers/doc/metrics/#publish-your-own-metrics "Publish your own metrics") | Define the path on which the Prometheus endpoint is available | /metrics | +|[`CC_METRICS_PROMETHEUS_PORT`](/developers/doc/metrics/#publish-your-own-metrics "Publish your own metrics") | Define the port on which the Prometheus endpoint is available | 9100 | +|[`CC_METRICS_PROMETHEUS_RESPONSE_TIMEOUT`](/developers/doc/metrics/#publish-your-own-metrics "Publish your own metrics") | Define the timeout in seconds to collect the application metrics. This value **must** be below 60 seconds as data are collected every minutes | 3 | +|[`CC_METRICS_PROMETHEUS_USER`](/developers/doc/metrics/#publish-your-own-metrics "Publish your own metrics") | Define the user for the basic auth of the Prometheus endpoint | | +|[`CC_VARNISH_FILE`](/developers/doc/administrate/cache "Cache") | The path to the Varnish configuration file, relative to your application root | `/clevercloud/varnish.vcl` | +|[`CC_VARNISH_STORAGE_SIZE`](/developers/doc/administrate/cache "Cache") | Configure the size of the Varnish cache. | 1G | +|[`CC_WORKER_COMMAND`](/developers/doc/develop/workers "Workers") | Command to run in background as a worker process. You can run multiple workers. | | + +{{% content "mise" %}} + +| Name | Description | +|-----------------|--------------------------| +|`CC_RUN_MISE_INSTALL`| Set to `true` to run `mise install` before the build phase | + +{{% content "redirectionio" %}} +> [!NOTE] Redirection.io is not available in Docker and PHP applications + +### Tailscale support + +[Tailscale](https://tailscale.com/) is a managed VPN service based on Wireguard that enable private networking between users, devices or machines. Clever Cloud provides a native integration of Tailscale, by mounting a VPN endpoint for each of your application's instances. + +Note that `Reusable keys` are required to use multiple instances. You can [generate one here](https://login.tailscale.com/admin/settings/keys "Generate tailscale key"). + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +| [`TAILSCALE_ACCEPT_DNS`](https://tailscale.com/kb/1072/client-preferences#use-tailscale-dns-settings) | Tailscale use its default DNS settings | `true` | +| [`TAILSCALE_ACCEPT_ROUTES`](https://tailscale.com/kb/1072/client-preferences#use-tailscale-subnets) | Tailscale uses its subnets settings | `false` | +| [`TAILSCALE_AUTH_KEY`](https://tailscale.com/ "tailscale.com") | Contains your Tailscale Auth key | | +| `TAILSCALE_LOGIN_SERVER`| Contains the login server | | + +#### How it works? + +For a given application with `TAILSCALE_AUTH_KEY` configured, each instance will be configured to join a Tailscale network. Instances will be named after your configured name, suffixed with the [INSTANCE_NUMBER](/developers/doc/develop/env-variables "Environment variables") : `CC--`. If you have multiple instances and use one of them for being an admin instance (using [INSTANCE_NUMBER](/developers/doc/develop/env-variables "Environment variables")), you can match the instance from your deployment to reach it over VPN. + +If `TAILSCALE_LOGIN_SERVER` is provided, the agent will be configured to reach an alternative control server. Note that using your own control server is at your own risks, and Tailscale can't be responsible. An alternative control server can still be useful to use for constraints environements. [Headscale](https://github.com/juanfont/headscale/) is an example of self-hosted implementation of the Tailscale control server that can run on Clever Cloud. + +## Docker + +[Docker Documentation](/developers/doc/applications/docker) + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|`CC_DOCKERFILE` | The name of the Dockerfile to build. | Dockerfile | +|`CC_DOCKER_BUILDX` | Set to `true` to use`buildx` for building your image | false | +|`CC_DOCKER_EXPOSED_HTTP_PORT` | Set to custom HTTP port if your Docker container runs on custom port. | 8080 | +|`CC_DOCKER_EXPOSED_TCP_PORT` | Set to custom TCP port if your Docker container runs on custom port. | 4040 | +|`CC_DOCKER_FIXED_CIDR_V6` | Activate the support of IPv6 with an IPv6 subnet int the docker daemon. | | +|`CC_DOCKER_LOGIN_PASSWORD` | The password of your username. | | +|`CC_DOCKER_LOGIN_SERVER` | The server of your private registry (optional). | Docker’s public registry | +|`CC_DOCKER_LOGIN_USERNAME` | The username to login to a private registry. | | +|`CC_MOUNT_DOCKER_SOCKET` | Set to true to access the host Docker socket from inside your container. | false | + +## .NET + +[.NET Documentation](/developers/doc/applications/dotnet) + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|`CC_DOTNET_PROFILE` | Override the build configuration settings in your project. | Release | +|`CC_DOTNET_PROJ` | The name of your project file to use for the build, without the .csproj / .fsproj / .vbproj extension. | | +|`CC_DOTNET_TFM` | Compiles for a specific framework. The framework must be defined in the project file. Example : `net5.0` | | +|`CC_DOTNET_VERSION` | Choose the .NET Core version between `6.0`,`8.0`, `9.0`. | 8.0 | +|`CC_RUN_COMMAND` | Custom command to run your application. | | + +## Elixir + +[Elixir Documentation](/developers/doc/applications/elixir) + + | Name | Description | Default value | + |-----------------------|------------------------------|--------------------------------| + |`CC_ELIXIR_VERSION` | Choose the Elixir version among [those supported](/developers/doc/applications/elixir/#mandatory-configuration) | | + |`CC_MIX_BUILD_GOAL` | The mix goal to build the application (default compile) | | + |`CC_PHOENIX_ASSETS_DIR` | Folder in which your Phoenix assets are located. | | + |`CC_PHOENIX_DIGEST_GOAL` | Phoenix digest goal. | phx.digest | + |`CC_PHOENIX_RUN_ECTO_MIGRATE` | Whether to run 'mix ecto.migrate' or not. | true | + |`CC_PHOENIX_SERVER_GOAL` | Phoenix server goal. | phx.server | + |`CC_RUN_COMMAND` | Custom command to run your application. Replaces the default behaviour. | | + +## FrankenPHP + +[FrankenPHP Documentation](/developers/doc/applications/frankenphp) + +| Name | Description | Default value | +|---------------|-------------| ---------------| +| `CC_FRANKENPHP_PORT` | The port on which FrankenPHP listens for HTTP requests | `8080` | +| `CC_FRANKENPHP_WORKER` | Path to the worker script, relative to the root of your project (e.g. `/worker/scrip.php`) | | +| `CC_PHP_COMPOSER_FLAGS` | Flags to pass to Composer | `-n --no-dev --no-progress --no-scripts` | +| `CC_PHP_DEV_DEPENDENCIES` | Set to `install` to install PHP development dependencies during build | | +| `CC_WEBROOT` | Path to the web content to serve, relative to the root of your application | `/` | + +## Go + +[Go Documentation](/developers/doc/applications/golang) + +| Name | Description | +| :------- | :---- | +| `CC_GO_BUILD_TOOL` | Available values: `gomod`, `gobuild`. Build and install your application. `goget` still exists but is deprecated. | +| `CC_GO_RUNDIR` | Run the application from the specified path, relative to `$GOPATH/src/`, now deprecated. | +| `CC_GO_PKG` | Tell the `CC_GO_BUILD_TOOL` which file contains the `main()` function, default `main.go`. | + +## Haskell + +[Haskell Documentation](/developers/doc/applications/haskell) + +| Name | Description | +|-----------------------|------------------------------| +|[`CC_HASKELL_STACK_TARGET`](/developers/doc/applications/haskell/#specify-stack-package-target "Specify Stack package target") | Specify Stack package target. | +|`CC_HASKELL_STACK_SETUP_COMMAND` | Only use this variable to override the default `setup` Stack step command | +|`CC_HASKELL_STACK_INSTALL_COMMAND` | Only use this variable to override the default `install` Stack step command | +|`CC_HASKELL_STACK_INSTALL_DEPENDENCIES_COMMAND` | Only use this variable to override the default `install --only-dependencies` Stack step command | +|`CC_RUN_COMMAND` | Custom command to run your application. | + +## Java + +[Java Documentation](/developers/doc/applications/java/java-jar) + +| Name | Description | Default value | Read Only | +|-----------------------|------------------------------|--------------------------------|--------------------------------| +|`CC_DISABLE_MAX_METASPACE` | Allows to disable the Java option -XX:MaxMetaspaceSize | | | +|`CC_EXTRA_JAVA_ARGS` | Define extra arguments to pass to 'java' for jars. | | | +|`CC_JAR_ARGS` | Define arguments to pass to the jar we launch. | | | +|`CC_JAR_PATH` | Define the path to your jar. | | | +|`CC_JAVA_VERSION` | Choose the JVM version between 7 to 17 for OpenJDK or graalvm-ce for GraalVM 21.0.0.2 (based on OpenJDK 11.0). | 21 | | +|`CC_MAVEN_PROFILES` | Define which maven profile to use during default build. | | | +|`CC_RUN_COMMAND` | Custom command to run your application. Replaces the default behaviour. | | | +|`CC_SBT_TARGET_BIN` | Define the bin to pick in the `CC_SBT_TARGET_DIR`. | The first bin found in the `CC_SBT_TARGET_DIR`. | | +|`CC_SBT_TARGET_DIR` | Define where pick the bin to run. | `.` | Then `/target/universal/stage/bin` is concatenated. | +|`GRADLE_DEPLOY_GOAL` | Define which gradle goals to run during build. | | | +|`MAVEN_DEPLOY_GOAL` | Define which maven goals to run during build. | | | +|`NUDGE_APPID` | | | | +|`PLAY1_VERSION` | Define which play1 version to use between 1.2, 1.3, 1.4 and 1.5 | | | +|`SBT_DEPLOY_GOAL` | Define which sbt goals to run during build. | stage | | + +## Linux + +[Linux Documentation](/developers/doc/applications/linux) + +| Name | Description | Default value | +|------|-------------|---------------| +| `CC_BUILD_COMMAND` | The command to run during the build phase | `` | +| `CC_RUN_COMMAND` | The command to run during the run phase | `` | + +Use Linux runtime with [Mise package manager](#install-tools-with-mise-package-manager) to install your dependencies easily + +## Node.js + +[Node.js Documentation](/developers/doc/applications/nodejs) + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|[`CC_NODE_VERSION`](/developers/doc/applications/nodejs#set-nodejs-version)| Set Node.js version, for example `24`, `23.11` or `22.15.1` | | +|`CC_NODE_DEV_DEPENDENCIES` | Control if development dependencies are installed or not. Values are either `install` or `ignore` | `ignore` | +|`CC_RUN_COMMAND` | Define a custom command. Example for Meteor: `node .build/bundle/main.js ` | | +|`CC_NODE_BUILD_TOOL` | Choose your build tool between npm, npm-ci, yarn, yarn2 and custom | npm | +|`CC_CUSTOM_BUILD_TOOL`| A custom command to run (with `CC_NODE_BUILD_TOOL` set to `custom`) | | +|`CC_NPM_REGISTRY` | The host of your private repository, available values: `github` or the registry host. | registry.npmjs.org | +|`CC_NPM_BASIC_AUTH`| Private repository credentials, in the form `user:password`. You can't use this if `CC_NPM_TOKEN` is set | | +|`NPM_TOKEN` | Private repository token | | + +## PHP + +[PHP Documentation](/developers/doc/applications/php) + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|`ALWAYS_POPULATE_RAW_POST_DATA` | | | +|`CC_COMPOSER_VERSION` | Choose your composer version between 1 and 2 | 2 | +|[`CC_CGI_IMPLEMENTATION`](/developers/doc/applications/php/#change-the-fastcgi-module) | Choose the Apache FastCGI module between `fastcgi` and `proxy_fcgi` | proxy_fcgi | +|`CC_HTTP_BASIC_AUTH` | Restrict HTTP access to your application. Example: `login:password`. You can define multiple credentials using additional `CC_HTTP_BASIC_AUTH_n` (where `n` is a number) environment variables. | | +| `CC_APACHE_HEADERS_SIZE` | Set the maximum size of the headers in Apache, 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 | 8 | +|`CC_LDAP_CA_CERT` | | | +|`CC_MTA_AUTH_PASSWORD` | Password to authenticate to the SMTP server | | +|`CC_MTA_AUTH_USER` | User to authenticate to the SMTP server | | +|`CC_MTA_SERVER_AUTH_METHOD` | Enable or disable authentication to the SMTP server | on | +|`CC_MTA_SERVER_HOST` | Host of the SMTP server | | +|`CC_MTA_SERVER_PORT` | Port of the SMTP server | 465 | +|`CC_MTA_SERVER_USE_TLS` | Enable or disable TLS when connecting to the SMTP server | true | +|`CC_OPCACHE_INTERNED_STRINGS_BUFFER` | The amount of memory used to store interned strings, in megabytes. | Default 4 (PHP5), 8 (PHP7) | +|`CC_OPCACHE_MAX_ACCELERATED_FILES` | Maximum number of files handled by opcache. | Default depends on the scaler size | +|`CC_OPCACHE_MEMORY` | Set the shared opcache memory size | Default is about 1/8 of the RAM | +|`CC_OPCACHE_PRELOAD` | The path of the PHP preload file (PHP version 7.4 or higher). | | +|[`CC_PHP_ASYNC_APP_BUCKET`](/developers/doc/applications/php/#speed-up-or-disable-the-session-fs-bucket "Speed up or disable the session on FS Bucket") | Mount the default app FS bucket asynchronously. If set, should have value `async` | | +|[`CC_PHP_DEV_DEPENDENCIES`](/developers/doc/applications/php/#development-dependencies "Development dependencies") | Control if development dependencies are installed or not. Values are either `install` or `ignore` | | +|[`CC_PHP_DISABLE_APP_BUCKET`](/developers/doc/applications/php/#speed-up-or-disable-the-session-fs-bucket "Speed up or disable the session on FS Bucket") | Disable entirely the app FS Bucket. Values are either `true`, `yes` or `disable` | | +|`CC_PHP_VERSION` | Choose your PHP version among [those supported](/developers/doc/applications/php/#choose-your-php-version) | 8.3 | +|`CC_REALPATH_CACHE_TTL` | The size of the realpath cache to be used by PHP | 120 | +|`CC_WEBROOT` | Define the `DocumentRoot` of your project | `.` | +|`ENABLE_ELASTIC_APM_AGENT` | Elastic APM Agent for PHP | `true` if `ELASTIC_APM_SERVER_URL` is defined, `false` otherwise | +|`ENABLE_GRPC` | Enable the use of gRPC module | false | +|`ENABLE_PDFLIB` | Enable the use of PDFlib module | false | +|`ENABLE_REDIS` | | false | +|`HTTP_TIMEOUT` | Define a custom HTTP timeout | 180 | +|`LDAPTLS_CACERT` | | | +|`MAX_INPUT_VARS` | | | +|`MEMORY_LIMIT` | Change the default memory limit | | +|[`SESSION_TYPE`](/developers/doc/applications/php/#use-redis-to-store-php-sessions "Use Redis to store PHP sessions") | Choose `redis` to use it as session store | | +|`SOCKSIFY_EVERYTHING` | | | +|`SQREEN_API_APP_NAME` | The name of your sqreen application. | | +|`SQREEN_API_TOKEN` | organisation token. | | + +## Python + +[Python Documentation](/developers/doc/applications/python) + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|`CC_HTTP_BASIC_AUTH` | Restrict HTTP access to your application. Example: `login:password`. You can define multiple credentials using additional `CC_HTTP_BASIC_AUTH_n` (where `n` is a number) environment variables. | | +|[`CC_NGINX_PROXY_BUFFERS`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers "Nginx documentation") | Sets the number and size of the buffers used for reading a response from the proxied server, for a single connection. | | +|[`CC_NGINX_PROXY_BUFFER_SIZE`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size "Nginx documentation") | Sets the size of the buffer used for reading the first part of the response received from the proxied server.| | +|`CC_PIP_REQUIREMENTS_FILE` | Allows you to define a custom requirements.txt file | requirements.txt | +|`CC_PYTHON_BACKEND` | Choose the Python backend to use between daphne, gunicorn, uvicorn and uwsgi | uwsgi | +|`CC_PYTHON_CELERY_LOGFILE` | Relative path to your Celery logfile: /path/to/logdir | | +|`CC_PYTHON_CELERY_MODULE` | Specify the Celery module you want to start | | +|`CC_PYTHON_CELERY_USE_BEAT` | Set to "true" to activate Beat support | | +|[`CC_PYTHON_MANAGE_TASKS`](/developers/guides/python-django-sample/#manage-py-tasks) | Comma-separated list of Django manage tasks | | +|`CC_PYTHON_MODULE` | Select which module you want to start with the path to the folder containing the app object. For example, a module called **server.py** in a folder called **/app** would be used here as **app.server:app** | | +|`CC_PYTHON_USE_GEVENT` | Set to true to enable Gevent | | +|`CC_PYTHON_VERSION` | Choose the Python version among [those supported](/developers/doc/applications/python/#supported-versions) | 3 | +|`ENABLE_GZIP_COMPRESSION` | Set to `true` to gzip-compress through Nginx | | +|`GZIP_TYPES` | Set the mime types to compress. | text/* application/json application/xml application/javascript image/svg+xml | +|`HARAKIRI` | Timeout (in seconds) after which an unresponding process is killed | 180 | +|`NGINX_READ_TIMEOUT` | Read timeout in seconds | 300 | +|`PYTHON_SETUP_PY_GOAL` | Custom setup goal to be launch after requirements.txt have been installed | | +|`STATIC_FILES_PATH` | Relative path to where your static files are stored: path/to/static | | +|[`STATIC_URL_PREFIX`](/developers/doc/applications/python/#configure-your-python-application "Configure your Python application") | The URL path under which you want to serve static file, usually /public | | +|`STATIC_WEBROOT` | | | +|[`UWSGI_ASYNC`](/developers/doc/applications/python/#configure-your-python-application "Configure your Python application" ) | Number of cores to use for uWSGI asynchronous/non-blocking modes | | +|`UWSGI_ASYNC_ENGINE` | Select the asynchronous engine for uWSGI (optional) | | +|`UWSGI_INTERCEPT_ERRORS` | | +|`WSGI_BUFFER_SIZE` | Buffer size (in bytes) for uploads. | 4096 | +|`WSGI_POST_BUFFERING` | Maximal size (in bytes) for the headers of a request. | 4096 | +|`WSGI_THREADS` | Number of threads per worker. (Default: automatically setup with the scaler size) | | +|`WSGI_WORKERS` | Number of workers. (Default: automatically setup with the scaler size) | | + +When your Python application doesn't use one of the supported backends, with `CC_RUN_COMMAND` for example, it must listen on port `9000`, not `8080`. + +## Ruby + +- [Ruby Guide](/developers/guides/ruby-rack-app-tutorial) +- [Ruby Documentation](/developers/doc/applications/ruby) + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|[`CC_ENABLE_SIDEKIQ`](/developers/doc/applications/ruby/#configure-sidekiq) | Enable Sidekiq background process | false | +|`CC_HTTP_BASIC_AUTH` | Restrict HTTP access to your application. Example: `login:password`. You can define multiple credentials using additional `CC_HTTP_BASIC_AUTH_n` (where `n` is a number) environment variables. | | +|`CC_NGINX_PROXY_BUFFERS` | Sets the number and size of the buffers used for reading a response from the proxied server, for a single connection. [Nginx documentation](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers "Nginx documentation") | | +|`CC_NGINX_PROXY_BUFFER_SIZE` | Sets the size of the buffer used for reading the first part of the response received from the proxied server. [Nginx documentation](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size "Nginx documentation") | | +|`CC_RACKUP_SERVER` | The server to use for serving the ruby application | puma | | +|[`CC_RAKEGOALS`](/developers/doc/applications/ruby/#configure-rake-goals) | A list of comma-separated rake goals to execute e.g. db:migrate, assets:precompile | | +|`CC_RUBY_VERSION` | Choose the Ruby version to use but we strongly advise to set Ruby version in your Gemfile | | | +|`CC_SIDEKIQ_FILES` | Specify a list of Sidekiq configuration files e.g. "./config/sidekiq_1.yml,./config/sidekiq_2.yml" | | +|`ENABLE_GZIP_COMPRESSION` | Set to `true` to gzip-compress through Nginx | | +|`GZIP_TYPES` | Set the mime types to compress. | text/* application/json application/xml application/javascript image/svg+xml | +|`NGINX_READ_TIMEOUT` | Read timeout in seconds | 300 | +|`RACK_ENV` | | | +|`RAILS_ENV` | | | | +|`STATIC_FILES_PATH` | Relative path to where your static files are stored: path/to/static | | +|[`STATIC_URL_PREFIX`](/developers/doc/applications/ruby/#manage-your-static-files-and-assets) | The URL path under which you want to serve static file, usually /public | | +|`STATIC_WEBROOT` | | | + +## Rust + +[Rust Documentation](/developers/doc/applications/rust) + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|`CC_RUSTUP_CHANNEL` | The rust channel to use. Use a specific channel version with stable, beta, nightly or a specific version like 1.13.0 | stable | +|`CC_RUST_BIN` | The name of the binary to launch once built | | +|`CC_RUST_FEATURES` | The list of features to enable | | +|`CC_RUN_COMMAND` | Custom command to run your application. | | + +## Static + +[Static Documentation](/developers/doc/applications/static) + +| Name | Description | Default value | +|------|-------------|---------------| +| `CC_HUGO_VERSION` | Set the Hugo version, for example `0.147` | | +| `CC_BUILD_COMMAND` | The command to run during the build phase | | +| `CC_OVERRIDE_BUILDCACHE` | Files and path to put in the build cache, separated by a `:` | | +| `CC_STATIC_AUTOBUILD_OUTDIR` | The output directory of the static site generator (SSG) auto-build, relative to the root of your application | `/cc_static_autobuilt` | +| `CC_STATIC_CADDYFILE` | Path to the Caddyfile, as expected by `caddy run --config` command | `./Caddyfile` | +| `CC_STATIC_FLAGS` | Command line flags to pass to the static web server | | +| `CC_STATIC_PORT` | The port on which the static web server listens for HTTP requests | `8080` | +| `CC_STATIC_SERVER` | The server to use to serve your static website, can be `caddy` | `static-web-server` | +| `CC_WEBROOT` | Path to the web content to serve, relative to the root of your application, used as default build cache | `/` | + +> [!NOTE] Static Site Generators (SSG) Auto-build +> If no `CC_BUILD_COMMAND` is provided, Clever Cloud tries to detect and configure Static Site Generator (SSG), any provided `CC_WEBROOT` is ignored. See [Static Site Generators (SSG) Auto-build](/developers/doc/applications/static/#static-site-generators-ssg-auto-build) for more information. + +## V (Vlang) + +[V (Vlang)](/developers/doc/applications/v) + +| Name | Description | Default value | +|------|-------------|---------------| +| `CC_V_BINARY` | The name of the output binary file. | `${APP_HOME}/v_bin_${APP_ID}` | +| `ENVIRONMENT` | Set to `development` to compile without the `-prod` flag | | + +## Add-ons environment variables + +### FS Bucket + +[FS Bucket Documentation](/developers/doc/addons/fs-bucket) + +| Name | Description | Read Only | +|-----------------------|------------------------------|--------------------------------| +|`BUCKET_HOST` | Hostname of the bucket | ✓ | +|`CC_FS_BUCKET` | Defines which bucket to mount on which path | | + +### MongoDB + +[MongoDB Documentation](/developers/doc/addons/mongodb) + +| Name | Description | Default value | Read Only | +|-----------------------|------------------------------|--------------------------------|--------------------------------| +|`MONGODB_ADDON_HOST` | | Generated upon creation | ✓ | +|`MONGODB_ADDON_PORT` | | Generated upon creation | ✓ | +|`MONGODB_ADDON_DIRECT_HOST` | Points directly to the VM, bypassing reverse proxies | Generated on demand via the dashboard | ✓ | +|`MONGODB_ADDON_DIRECT_PORT` | Points to ectly to the VM, bypassing reverse proxies | Generated on demand via the dashboard | ✓ | +|`MONGODB_ADDON_DB` | | Generated upon creation | ✓ | +|`MONGODB_ADDON_PASSWORD` | | Generated upon creation | ✓ | +|`MONGODB_ADDON_USER` | | Generated upon creation | ✓ | + +### MySQL + +[MySQL Documentation](/developers/doc/addons/mysql) + +| Name | Description | Default value | Read Only | +|-----------------------|------------------------------|--------------------------------|--------------------------------| +|`MYSQL_ADDON_HOST` | | Generated upon creation | ✓ | +|`MYSQL_ADDON_PORT` | | Generated upon creation | ✓ | +|`MYSQL_ADDON_DIRECT_HOST` | Points directly to the VM, bypassing reverse proxies | Generated on demand via the dashboard | ✓ | +|`MYSQL_ADDON_DIRECT_PORT` | Points to ectly to the VM, bypassing reverse proxies | Generated on demand via the dashboard | ✓ | +|`MYSQL_ADDON_DB` | | Generated upon creation | ✓ | +|`MYSQL_ADDON_PASSWORD` | | Generated upon creation | ✓ | +|`MYSQL_ADDON_ROLE` | | Generated upon creation | ✓ | +|`MYSQL_ADDON_USER` | | Generated upon creation | ✓ | + +### ProxySQL + +[ProxySQL Documentation](/developers/guides/proxysql) + +| Name | Description | Default value | Read Only | +|-----------------------|------------------------------|--------------------------------|--------------------------------| +|`CC_ENABLE_MYSQL_PROXYSQL` | Enable the ProxySQL feature | false | | +|`CC_MYSQL_PROXYSQL_MAX_CONNECTIONS` | Defines the maximum number of connections the local ProxySQL will open to your MySQL add-on | 10 | | +|`CC_MYSQL_PROXYSQL_USE_TLS` | Enable or disable secured connection using TLS to your MySQL add-on | true | | +|`CC_MYSQL_PROXYSQL_SOCKET_PATH` | Contains the path to the Unix Datagram Socket to connect to ProxySQL | | ✓ | + +### PostgreSQL + +[PostgreSQL Documentation](/developers/doc/addons/postgresql) + +| Name | Description | Default value | Read Only | +|-----------------------|------------------------------|--------------------------------|--------------------------------| +|`POSTGRESQL_ADDON_HOST` | | Generated upon creation | ✓ | +|`POSTGRESQL_ADDON_PORT` | | Generated upon creation | ✓ | +|`POSTGRESQL_ADDON_DIRECT_HOST` | Points directly to the VM, bypassing reverse proxies | Generated on demand via the dashboard | ✓ | +|`POSTGRESQL_ADDON_DIRECT_PORT` | Points to ectly to the VM, bypassing reverse proxies | Generated on demand via the dashboard | ✓ | +|`POSTGRESQL_ADDON_DB` | | Generated upon creation | ✓ | +|`POSTGRESQL_ADDON_PASSWORD` | | Generated upon creation | ✓ | +|`POSTGRESQL_ADDON_ROLE` | | Generated upon creation | ✓ | +|`POSTGRESQL_ADDON_USER` | | Generated upon creation | ✓ | + +### Pgpool-II + +[Pgpool-II Documentation](/developers/guides/pgpool) + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +|`CC_ENABLE_PGPOOL` | Enables the Pgpool-II feature | false | +|`CC_PGPOOL_SOCKET_PATH` | Contains the path to the Unix Datagram Socket to connect to Pgpool-II | true | +|`CC_PGPOOL_PCP_SOCKET_PATH` | Contains the path to the Unix Datagram Socket to connect to PCP | true | +|`CC_PGPOOL_EXTRA_USERS` | Add new user/password pairs to the pool_passwd file, separated by commas (user1:password,user2:password…) | ' ' | +|`CC_PGPOOL_RESERVED_CONNECTIONS` | Number of reserved connections | 0 | +|`CC_PGPOOL_LISTEN_BACKLOG_MULTIPLIER` | Specifies the length of connection queue from frontend to Pgpool-II | 2 | +|`CC_PGPOOL_LEADER_WEIGHT` | Weight for backend 0 (Leader) | 1 | +|`CC_PGPOOL_NUM_INIT_CHILDREN` | Number of concurrent sessions allowed | 16 | +|`CC_PGPOOL_MAX_POOL` | Number of connection pool caches per connection | 1 | +|`CC_PGPOOL_CHILD_LIFE_TIME` | Pool exits after being idle for this many seconds | 300 | +|`CC_PGPOOL_CHILD_MAX_CONNECTIONS` | Pool exits after receiving that many connections | 0 (no exit) | +|`CC_PGPOOL_CONNECTION_LIFE_TIME` | Connection to backend closes after being idle for this many seconds | 0 (no close) | +|`CC_PGPOOL_CLIENT_IDLE_LIMIT` | Client is disconnected after being idle for that many seconds (even inside an explicit transactions!) | 0 (no disconnection) | | +|`CC_PGPOOL_LOG_CONNECTIONS` | Log connections | off | +|`CC_PGPOOL_LOG_DISCONNECTIONS` | Log disconnections | off | +|`CC_PGPOOL_LOG_HOSTNAME` | Hostname will be shown in ps status and in logs if connections are logged | off | +|`CC_PGPOOL_LOG_STATEMENT` | Log all statements | off | +|`CC_PGPOOL_LOG_PER_NODE_STATEMENT` | Log all statements with node and backend informations | off | +|`CC_PGPOOL_LOG_CLIENT_MESSAGES` | Log any client messages | off | +|`CC_PGPOOL_LOG_STANDBY_DELAY` | Log standby delay. Valid values are combinations of always, if_over_threshold and none | if_over_threshold | +|`CC_PGPOOL_CONNECTION_CACHE` | Activate connection pools | on | +|`CC_PGPOOL_REPLICATE_SELECT` | Replicate SELECT statements in replication mode | off | +|`CC_PGPOOL_INSERT_LOCK` | Automatically locks a dummy row or a table with INSERT statements to keep SERIAL data consistency | on | +|`CC_PGPOOL_LOBJ_LOCK_TABLE` | When rewriting lo_creat command in replication mode, specify table name to lock | ' ' | +|`CC_PGPOOL_REPLICATION_STOP_ON_MISMATCH` | On disagreement with the packet kind sent from backend, degenerate the node which is most likely "minority" If off, just force to exit this session | off | +|`CC_PGPOOL_FAILOVER_IF_AFFECTED_TUPLES_MISMATCH` | On disagreement with the number of affected tuples in UPDATE/DELETE queries, then degenerate the node which is most likely "minority". If off, just abort the transaction to keep the consistency | off | +|`CC_PGPOOL_LOAD_BALANCE_MODE` | Activate load balancing mode | on | +|`CC_PGPOOL_IGNORE_LEADING_WHITE_SPACE` | Ignore leading white spaces of each query | on | +|`CC_PGPOOL_READ_ONLY_FUNCTION_LIST` | Comma separated list of function names that don't write to database (regexp are accepted) | ' ' | +|`CC_PGPOOL_WRITE_FUNCTION_LIST` | Comma separated list of function names that write to database (regexp are accepted) | ' ' | +|`CC_PGPOOL_PRIMARY_ROUTING_QUERY_PATTERN_LIST` | Semicolon separated list of query patterns that should be sent to primary node (regexp are accepted) | ' ' | +|`CC_PGPOOL_DATABASE_REDIRECT_PREFERENCE_LIST` | Comma separated list of pairs of database and node id | ' ' | +|`CC_PGPOOL_APP_NAME_REDIRECT_PREFERENCE_LIST` | Comma separated list of pairs of app name and node id | ' ' | +|`CC_PGPOOL_ALLOW_SQL_COMMENTS` | If on, ignore SQL comments when judging if load balance or query cache is possible | off | +|`CC_PGPOOL_DISABLE_LOAD_BALANCE_ON_WRITE` | Load balance behavior when write query is issued in an explicit transaction. Valid values are "transaction", "trans_transaction", "dml_adaptive" or "always" | transaction | +|`CC_PGPOOL_DML_ADAPTIVE_OBJECT_RELATIONSHIP_LIST` | Comma separated list of object pairs | ' ' | +|`CC_PGPOOL_STATEMENT_LEVEL_LOAD_BALANCE` | Enables statement level load balancing | off | +|`CC_PGPOOL_SR_CHECK_PERIOD` | Streaming replication check period | 10 | +|`CC_PGPOOL_DELAY_THRESHOLD` | Threshold before not dispatching query to standby node Unit is in bytes | 10000000 | +|`CC_PGPOOL_HEALTH_CHECK_PERIOD` | Health check period | 20 | +|`CC_PGPOOL_HEALTH_CHECK_TIMEOUT` | Health check timeout | 20 | +|`CC_PGPOOL_HEALTH_CHECK_MAX_RETRIES` | Maximum number of times to retry a failed health check before giving up | 0 | +|`CC_PGPOOL_HEALTH_CHECK_RETRY_DELAY` | Amount of time to wait (in seconds) between retries | 1 | +|`CC_PGPOOL_CONNECT_TIMEOUT` | Timeout value in milliseconds before giving up to connect to backend | 10000 | +|`CC_PGPOOL_MEMORY_CACHE_ENABLED` | Use the memory cache functionality | off | +|`CC_PGPOOL_MEMQCACHE_TOTAL_SIZE` | Total memory size in megabytes for storing memory cache | 64 | +|`CC_PGPOOL_MEMQCACHE_MAX_NUM_CACHE` | Total number of cache entries | 1000000 | +|`CC_PGPOOL_MEMQCACHE_EXPIRE` | Memory cache entry life time specified in seconds | 0 | +|`CC_PGPOOL_MEMQCACHE_AUTO_CACHE_INVALIDATION` | Invalidation of query cache is triggered by corresponding DDL/DML/DCL | on | +|`CC_PGPOOL_MEMQCACHE_MAXCACHE` | Maximum SELECT result size in kilobytes (must be smaller than MEMQCACHE_CACHE_BLOCK_SIZE) | 400 | +|`CC_PGPOOL_MEMQCACHE_CACHE_BLOCK_SIZE` | Cache block size in megabytes | 1 | +|`CC_PGPOOL_CACHE_SAFE_MEMQCACHE_TABLE_LIST` | Comma separated list of table names to memcache that don't write to database (regexp are accepted) | ' ' | +|`CC_PGPOOL_CACHE_UNSAFE_MEMQCACHE_TABLE_LIST` | Comma separated list of table names not to memcache that don't write to database (regexp are accepted) | ' ' | + +### Elastic Stack + +[Elastic Stack Documentation](/developers/doc/addons/elastic) + +| Name | Description | Default value | Read Only | +|-----------------------|------------------------------|--------------------------------|--------------------------------| +|`ELASTIC_APM_SERVER_URL` | URI to connect APM Server | Generated upon creation | ✓ | +|`ES_ADDON_APM_HOST` | APM Server hostname | Generated upon creation | ✓ | +|`ES_ADDON_APM_AUTH_TOKEN` | Authentication token to send metrics to APM Server | Generated upon creation | ✓ | +|`ELASTIC_APM_SECRET_TOKEN` | Authentication token to send metrics to APM Server | Generated upon creation | ✓ | +|`ES_ADDON_APM_USER` | Username credential used by APM Server to send metrics to Elasticsearch | Generated upon creation | ✓ | +|`ES_ADDON_APM_PASSWORD` | Password credential used by APM Server to send metrics to Elasticsearch | Generated upon creation | ✓ | +|`ES_ADDON_KIBANA_HOST` | Kibana hostname | Generated upon creation | ✓ | +|`ES_ADDON_KIBANA_USER` | Username credential used by Kibana to query Elasticsearch | Generated upon creation | ✓ | +|`ES_ADDON_KIBANA_PASSWORD` | Password credential used by Kibana to query Elasticsearch | Generated upon creation | ✓ | +|`ES_ADDON_URI` | URI to query Elasticsearch | Generated upon creation | ✓ | +|`ES_ADDON_HOST` | Elasticsearch hostname | Generated upon creation | ✓ | +|`ES_ADDON_USER` | Username credential to authenticate to Elasticsearch | Generated upon creation | ✓ | +|`ES_ADDON_PASSWORD` | Password credential to authenticate to Elasticsearch | Generated upon creation | ✓ | +|`ES_ADDON_VERSION` | ElasticSearch Version | 7 | ✓ | + +### Blackfire + +| Name | Description | Default value | Read Only | +|-----------------------|------------------------------|--------------------------------|--------------------------------| +|`ENABLE_BLACKFIRE` | Enable the Blackfire extension | false | | +|`CC_BLACKFIRE_SERVER_TOKEN` | The server token used to authenticate with Blackfire | ' ' | ✓ | +|`CC_BLACKFIRE_SERVER_ID` | The server id used to authenticate with Blackfire | ' ' | ✓ | +|`CC_BLACKFIRE_LOG_LEVEL` | Sets the verbosity of Agent’s log output | 1 | ✓ | +|`CC_BLACKFIRE_MEMORY_LIMIT` | Sets the maximum allowed RAM usage (megabytes) when ingesting traces | 500 | ✓ | +|`CC_BLACKFIRE_COLLECTOR` | Sets the URL of Blackfire’s data collector | | ✓ | +|`CC_BLACKFIRE_TIMEOUT` | Sets the Blackfire API connection timeout | 15 | ✓ | +|`CC_BLACKFIRE_STATSD` | Sets the statsd server to send agent’s statistics | ' ' | ✓ | +|`CC_BLACKFIRE_STATSD_PREFIX` | Sets the statsd prefix to use when sending data | blackfire | ✓ | + +### New Relic + +| Name | Description | Default value | Read Only | +|-----------------------|------------------------------|--------------------------------|--------------------------------| +|[`NEW_RELIC_APP_NAME`](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/#ev-NEW_RELIC_APP_NAME "New Relic documentation") | Contains the application name | | +|[`NEW_RELIC_LICENSE_KEY`](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file/#ev-NEW_RELIC_LICENSE_KEY "New Relic documentation" ) | Contains your New Relic account license | | +|[`CC_NEWRELIC_BROWSER_MONITORING_AUTO_INSTRUMENT`](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-autorum "New Relic documentation" ) | | | +|[`CC_NEWRELIC_DISTRIBUTED_TRACING_ENABLED`](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-distributed-enabled "New Relic documentation" ) | | | +|[`CC_NEWRELIC_ERROR_COLLECTOR_ENABLED`](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-err-enabled "New Relic documentation" ) | | | +|[`CC_NEWRELIC_TRANSACTION_TRACER_ENABLED`](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-tt-enable "New Relic documentation" ) | | | +|[`CC_NEWRELIC_TRANSACTION_TRACER_RECORD_SQL`](https://docs.newrelic.com/docs/apm/agents/php-agent/configuration/php-agent-configuration/#inivar-tt-sql "New Relic documentation" ) | obfuscated | | + +### Pulsar + +| Name | Description | Default value | Read Only | +| ------------------------ | ----------------------------------------- | ------------------------------ | -------------------------- | +|`ADDON_PULSAR_BINARY_URL` | The complete URL to use in your application | Generated upon creation | ✓ | +|`ADDON_PULSAR_BINARY_PORT` | The port to connect to the Pulsar Cluster | Generated upon creation | ✓ | +|`ADDON_PULSAR_HOSTNAME` | The host to connect to the Pulsar Cluster | Generated upon creation | ✓ | +|`ADDON_PULSAR_HTTP_URL` | The complete URL to connect with WebSocket | Generated upon creation | ✓ | +|`ADDON_PULSAR_HTTP_PORT` | The port to connect with WebSocket | Generated upon creation | ✓ | +|`ADDON_PULSAR_NAMESPACE` | Your add-on Pulsar ID | Generated upon creation | ✓ | +|`ADDON_PULSAR_TENANT` | Your Clever Cloud tenant ID | Generated upon creation | ✓ | +|`ADDON_PULSAR_TOKEN` | Your Biscuit authentication token | Generated upon creation | ✓ | + +### Redis + +[Redis Documentation](/developers/doc/addons/redis) + +| Name | Description | Default value | Read Only | +|-----------------------|------------------------------|--------------------------------|--------------------------------| +|`REDIS_HOST` | | Generated upon creation | ✓ | +|`REDIS_PORT` | | Generated upon creation | ✓ | +|`REDIS_PASSWORD` | | Generated upon creation | ✓ | + +### VPN + +The VPN add-on provides a fixed-ip outgoing node. This can be used to work +with services protected by ip address filtering. `VPN_ADDON_*` variables will +be provided by Clever Cloud upon setup, the only configuration you have to +provide is a list of CIDRs (eg. 1.2.3.0/24) for which you want the traffic +to be routed through the exit node. + +| Name | Description | Default value | Read Only | +| --------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------ | -------------------------- | +| `CC_VPN_DNS_OVERRIDES` | Comma-separated list of DNS IP | | | +| `VPN_ADDON_CACRT` | Server CA certificate | | | +| `VPN_ADDON_CIPHER`| Cipher to use CIPHER, can be either {cipher_suite}:{hmac_alg} or only {cipher_suite} | DES-EDE3-CBC:SHA1 | | +| `VPN_ADDON_CRT` | Client certificate | | | +| `VPN_ADDON_DEVTYPE` | Kernel virtual interface kind to use ("tap" or "tun") | tap | | +| `VPN_ADDON_HOST` | Server host or IP address | | | +| `VPN_ADDON_KEY` | Client certificate private key | | | +| `VPN_ADDON_PORT` | Server port | | | +| `VPN_ADDON_TAKEY` | Pre-shared secret | | | +| `VPN_TARGETS` | Comma-separated list of CIDRs for which you want the traffic to be routed through the exit node | | | diff --git a/content/guides/_index.md b/content/guides/_index.md new file mode 100644 index 000000000..c1ba00235 --- /dev/null +++ b/content/guides/_index.md @@ -0,0 +1,56 @@ +--- +type: docs +title: Guides +description: Step by step guides to deploy specific apps and frameworks on Clever Cloud +tags: +- guides +aliases: +- /doc/deploy/application/docker/tutorials +- /doc/deploy/application/haskell/tutorials +- /doc/deploy/application/javascript/tutorials +- /doc/deploy/application/php/tutorials +- /doc/deploy/application/python/tutorials +- /doc/deploy/application/ruby/tutorials +- /doc/deploy/application/scala/tutorials +- /doc/tutorials/ +llmsTxtOptional: true +comments: false +--- + +{{< hextra/hero-subtitle style="margin:.3rem 0 2rem 0">}} + Step by steps guides to deploy and use your favorite stack on Clever Cloud +{{< /hextra/hero-subtitle >}} +{{< cards >}} + {{< card link="/developers/guides/astro" title="Astro" subtitle= "Build and deploy a Astro application on Clever Cloud" icon="astro" >}} + {{< card link="/developers/guides/python-django-sample" title="Django" subtitle= "Configure your Django application to run on Clever Cloud" icon="django" >}} + {{< card link="/developers/guides/docs" title="Docs" subtitle= "Deploy the open source document and live collaboration editor on Clever Cloud" icon="docs-suite" >}} + {{< card link="/developers/guides/docusaurus" title="Docusaurus" subtitle= "Build and deploy a static Docusaurus based website on Clever Cloud" icon="docusaurus" >}} + {{< card link="/developers/guides/tutorial-drupal" title="Drupal" subtitle= "Deploy a Drupal-based website on Clever Cloud" icon="drupal" >}} + {{< card link="/developers/guides/ekg-statsd-haskell-metrics/" title="ekg-statsd" subtitle= "How to configure ekg-statsd package in your Haskell application" icon="haskell" >}} + {{< card link="/developers/guides/eleventy" title="Eleventy (11ty)" subtitle= "Build and deploy a static Eleventy (11ty) based website on Clever Cloud" icon="11ty" >}} + {{< card link="/developers/guides/fluentd/" title="Fluentd" subtitle= "How to deploy Fluentd using Docker on Clever Cloud" icon="fluentd" >}} + {{< card link="/developers/guides/go-echoip" title="Echo IP" subtitle= "How to deploy EchoIP based on a Go application on Clever Cloud" icon="go" >}} + {{< card link="/developers/guides/hexo" title="Hexo" subtitle= "Build and deploy a static Hexo based website on Clever Cloud" icon="hexo" >}} + {{< card link="/developers/guides/hugo" title="Hugo" subtitle= "Build and deploy a static Hugo based website on Clever Cloud" icon="hugo" >}} + {{< card link="/developers/guides/hugo-static-s3" title="Hugo + Cellar" subtitle= "Build and deploy a static Hugo based website and host it using Cellar" icon="hugo" >}} + {{< card link="/developers/guides/kibana" title="Kibana" subtitle= "Deploy and customize a Kibana server on Clever Cloud" icon="kibana" >}} + {{< card link="/developers/guides/kubernetes-operator" title="Kubernetes Operator" subtitle= "Manage your Clever Cloud databases and addons seamlessly from Kubernetes" icon="kubernetes" >}} + {{< card link="/developers/guides/tutorial-laravel" title="Laravel" subtitle= "Deploy a Laravel app on Clever Cloud" icon="laravel" >}} + {{< card link="/developers/guides/lume-deno" title="Lume (Deno)" subtitle= "Build and deploy a static Lume (Deno) based website on Clever Cloud" icon="deno" >}} + {{< card link="/developers/guides/mdbook" title="mdBook" subtitle= "Build and deploy a static mbBook based website on Clever Cloud" icon="mdbook" >}} + {{< card link="/developers/guides/mkdocs" title="MkDocs" subtitle= "Build and deploy a static MkDocs based website on Clever Cloud" icon="docs" >}} + {{< card link="/developers/guides/moodle" title="Moodle" subtitle="Full Moodle installation and configuration guide" icon="moodle" >}} + {{< card link="/developers/guides/node-js-mongo-db" title="Node.js + MongoDB starter" subtitle= "Starter tutorial to deploy a Node.js + MongoDB application on Clever Cloud" icon="node" >}} + {{< card link="/developers/guides/node-statsd-nodejs-metrics" title="node-statsd" subtitle= "Configure node-statsd package on your Node.js application to push custom metrics" icon="node" >}} + {{< card link="/developers/guides/nuxt" title="Nuxt" subtitle= "Build and deploy a Nuxt application on Clever Cloud" icon="nuxt" >}} + {{< card link="/developers/guides/pgpool" title="Pgpool-II" subtitle= "How to configure and use Pgpool-II for PostgreSQL add-ons" icon="pg" >}} + {{< card link="/developers/guides/play-framework-1" title="Play 1 x Scala" subtitle= "Set up your Play 1 + Scala application to run on Clever Cloud" icon="play" >}} + {{< card link="/developers/guides/play-framework-2" title="Play 2 x Scala" subtitle= "Set up your Play 2 + Scala application to run on Clever Cloud" icon="play" >}} + {{< card link="/developers/guides/proxysql" title="ProxySQL" subtitle= "Configure and use ProxySQL for MySQL add-ons" icon="mysql" >}} + {{< card link="/developers/guides/ruby-on-rails" title="Ruby On Rails" subtitle= "How to deploy Ruby on Rails framework" icon="ruby" >}} + {{< card link="/developers/guides/ruby-rack" title="Ruby Rack" subtitle= "Set up a Ruby Rack application and deploy on Clever Cloud" icon="ruby" >}} + {{< card link="/developers/guides/ruby-rack-app-tutorial" title="Ruby Rack (full tutorial)" subtitle= "Write a hello world web application using Rack and deploy it on Clever Cloud" icon="ruby" >}} + {{< 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" >}} +{{< /cards >}} + diff --git a/content/guides/astro.md b/content/guides/astro.md new file mode 100644 index 000000000..276eb6504 --- /dev/null +++ b/content/guides/astro.md @@ -0,0 +1,161 @@ +--- +type: docs +title: Astro +description: Build your website with the Astro Static Site Generator (SSG) and host it on Clever Cloud. No dedicated runner needed. +tags: +- guides +keywords: +- astro +- nodejs +- static +- ssg +- html +- js +- css +- website +aliases: +- /doc/astro +- /astro +comments: false +--- + +{{< hextra/hero-subtitle >}} + Astro is an all-in-one web framework for building content-driven websites, that pioneers a new frontend architecture to reduce JavaScript overhead and complexity. Learn in this guide how to deploy an Astro site on Clever Cloud. +{{< /hextra/hero-subtitle >}} + +## Overview + +Clever Cloud supports deploying both [fully static and on-demand rendered](https://docs.astro.build/en/basics/rendering-modes/) Astro projects: +- The `static` output mode is ideal for most content-oriented website, for which you have no need for per-visitor server-side customization. Consider using a [Static runtime](/developers/doc/applications/static/) when using this output mode, with the automatic site generation. +- The `server` or `hybrid` output modes: consider using a [Node.js runtime](/developers/doc/applications/nodejs) with [Astro’s Node adapter](https://docs.astro.build/en/guides/integrations-guide/node/) + +If you need an example source code, get [Astrowind](https://github.com/onwidget/astrowind) (you'll need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs)): +```bash +git clone https://github.com/onwidget/astrowind myStaticApp +``` +To deploy your Astro project to Clever Cloud, you need to **create a new application**. + +{{% steps %}} + +### Deployment + +- Source: Git or GitHub + +### Application + +- Type: Static +- Instance size: you can usually deploy an Astro site using the `pico` instance +- Scalability options: if you need a bigger build instance, multiple instances, etc. + +### Options + +- Region +- Dependencies, if needed + +{{% /steps %}} + +If you're deploying from **GitHub**, your deployment should start automatically. If you're using **Git**, copy the remote and push on the **master** branch. + +{{< callout emoji="💡" >}} + To deploy from branches other than `master`, use `git push clever :master`. For example, if you want to deploy your local `main` branch without renaming it, use `git push clever main:master`. +{{< /callout >}} + +{{% content "static-create" %}} + +### Automatic build + +Astro is one of the many Static Site Generator (SSG) that [Clever Cloud automatic build](/developers/doc/applications/static/#static-site-generators-ssg-auto-build) supports in the `static` runtime, you don't have anything special to manage. To use a pico instance with a dedicated build instance change it in the [Console](https://console.clever-cloud.com) or with Clever Tools: + +```bash +clever scale --flavor pico + +# To select a bigger build instance, use: +clever scale --build-flavor M +``` + +{{% content "static-deploy" %}} + +## Deploying a Node.js application with Server-Side Rendering + +To deploy an Astro project with Server-Side Rendering (SSR), use a **Node.js** application on Clever Cloud and the [Node.js adapter](https://docs.astro.build/en/guides/integrations-guide/node/). + +### Inject environment variables + +Depending on your package manager, use the following environment variables: + +{{< tabs items="npm,pnpm,yarn" >}} + {{< tab >}} + ```shell + CC_POST_BUILD_HOOK="npm run build" + ``` + {{< /tab >}} + {{< tab >}} + ```shell + CC_NODE_BUILD_TOOL="custom" + CC_PRE_BUILD_HOOK="npm install -g pnpm && pnpm install" + CC_CUSTOM_BUILD_TOOL="pnpm run astro telemetry disable && pnpm build" + CC_RUN_COMMAND="pnpm run preview" + ``` + {{< /tab >}} + {{< tab >}} + ```shell + CC_NODE_BUILD_TOOL="yarn" + CC_PRE_BUILD_HOOK="yarn && yarn run astro telemetry disable && yarn build" + CC_RUN_COMMAND="yarn run preview" + ``` + {{< /tab >}} +{{< /tabs >}} + +> [!TIP] +> You can also use `package.json` scripts [to define commands to run](/developers/doc/applications/nodejs/#about-packagejson ) during the build and start phases. + +### Port and host + +As you manage the server, ensure to configure your application to listen on port **8080** as required by Clever Cloud. Set your port and host in your `astro dev` script for development mode, and/or configure it directly for production: + +{{< tabs items="development,production" >}} + {{< tab >}} + To quickly deploy on development mode: + + ```json {filename="package.json"} + "scripts": { + "dev": "astro dev", + "start": "astro dev", + "build": "astro check && astro build", + "preview": "astro preview --host 0.0.0.0 --port 8080", + "astro": "astro" + } + ``` + {{< /tab >}} + {{< tab >}} + When deploying for production: + + ```javascript {filename="astro.config.mjs"} + import { defineConfig } from 'astro/config'; + + export default defineConfig({ + server: { + port: 8080, + host: true + } + }); + ``` + ```json {filename="package.json"} + "scripts": { + "dev": "astro dev", + "start": "astro build && node ./dist/server/entry.mjs", + "build": "astro check && astro build", + "preview": "astro preview --host 0.0.0.0 --port 8080", + "astro": "astro" + } + ``` + {{< /tab >}} +{{< /tabs >}} + +## Learn more + +{{< cards >}} + {{< card link="/developers/doc/applications/nodejs" title="Deploy a Node.js application" subtitle="Learn more on deploying a Node.js application" icon="node" >}} + {{< card link="/developers/doc/applications/static" title="Deploy a Static application" subtitle="Learn more on deploying a Static application" icon="static" >}} + {{< card link="https://docs.astro.build/" title="Learn Astro" subtitle="How to write and organize your content" icon="astro" >}} +{{< /cards >}} diff --git a/content/guides/docs.md b/content/guides/docs.md new file mode 100644 index 000000000..fe67d894b --- /dev/null +++ b/content/guides/docs.md @@ -0,0 +1,294 @@ +--- +title: 'Docs' +description: +tags: +- guides +keywords: +- + +draft: false +type: docs +--- + +{{< hextra/hero-subtitle >}} + The open source document editor where your notes can become knowledge through live collaboration. +{{< /hextra/hero-subtitle >}} + +## Docs architecture overview + +[Docs](https://github.com/suitenumerique/docs) runs on a Python backend and displays the application on a React/Next frontend. A [yjs provider](https://github.com/yjs/yjs) completes the stack to enable collaborative features. + +```mermaid +flowchart TD + subgraph s1["Python"] + n6["Backend"] + end + subgraph s2["Node.JS"] + n7["Frontend"] + end + subgraph s3["Node.js"] + n8["yjs provider"] + end + n1["PostrgreSQL"] --> s1 + s1 --> n1 & s2 & n2["Keycloak"] & n4["Cellar"] & s3 + n2 --> s2 & s1 + s3 --> s1 + n4 --> s2 + n1@{ shape: cyl} + n2@{ shape: hex} + n4@{ shape: rect} +``` + +## Deploy Docs + +Docs runs using: + +- a **Python** application for the backend (in `src/backend`) +- a **Node.js** application for the frontend (in `src/frontend`) +- a **Node.js** application for the y-provider (in `src/frontend/servers/y-provider`) + +This guide walks you trough a deployment from the root of [Docs repository](https://github.com/suitenumerique/docs). Clone the repository and follow the steps to deploy Docs with a minimal configuration. + +### Deploy the backend + +{{% steps %}} + +#### Create a Python application + +Select at least an `XS` plan. Smaller instances can make the build to fail. + +Inject the following environment variables + +```env +APP_FOLDER="/src/backend" +CC_PRE_BUILD_HOOK="cd src/backend && pip install pip-tools && pip-compile pyproject.toml && +pip-sync requirements.txt" +CC_PYTHON_MODULE="impress.wsgi:application" +CC_PYTHON_VERSION="3" +CC_RUN_SUCCEEDED_HOOK="cd src/backend && python manage.py migrate" +DATA_DIR="home/bas//src/backend/data" +DJANGO_CONFIGURATION="Production" +DJANGO_SECRET_KEY="" +DJANGO_SETTINGS_MODULE="impress.settings" +DJANGO_SUPERUSER_PASSWORD="" +``` + +You can add the value you want for `DJANGO_SECRET_KEY`. You can generate it using a command like `openssl rand -base64 32` + +#### Create a PosgreSQL add-on + +Inject the DB credentials into the Python application: + +```env +DB_HOST="" +DB_NAME="" +DB_PASSWORD="" +DB_PORT="" +DB_USER="" +``` + +#### Set the backend domain name + +Select **Domain names** and add use the path routing feature on Clever Cloud to set the domain ans follows: + +- Domain name: `` +- Route: `/api/v1.0/` + +**⚠️ Don't skip the trailing slash at the end of the route.** + +You can use `.cleverapps.io` domains for tests. Make sure to set a custom domain before releasing for production. + +Then, inject the following environment variables: + +```env +DJANGO_ALLOWED_HOSTS="" +DJANGO_CSRF_TRUSTED_ORIGINS="https://" +IMPRESS_BASE_URL="https://" +LOGIN_REDIRECT_URL="https://" +LOGOUT_REDIRECT_URL="https:///*" +``` + +#### Push your code + +If you push using git, add the remote as `clever-backend`, for example. + +{{% /steps %}} + +### Deploy the frontend + +{{% steps %}} + +#### Create a Node.js application + +Select at least a `M` instance for the build, and inject the following environment variables: + +```env +APP_FOLDER="./src/frontend" +CC_NODE_BUILD_TOOL="yarn" +CC_PRE_BUILD_HOOK="cd ./src/frontend && yarn install --frozen-lockfile && yarn app:build" +CC_RUN_COMMAND="cd ./src/frontend && yarn app:start" +NEXT_PUBLIC_API_BASE_PATH="/" +NEXT_PUBLIC_SW_DEACTIVATED="true" +NODE_OPTIONS="--max-old-space-size=4096" +``` + +#### Set the frontend domain name + +- Select **Domain names** and set the base domain for Docs. The frontend doesn't need any route. +- Add the domain to the environment variables: inject `NEXT_PUBLIC_API_ORIGIN="https://"` to the list of the frontend environment variables. + +#### Push your code + +If you push using git, add the remote as `clever-frontend`, for example. + +{{% /steps %}} + +### Deploy the y-provider + +{{% steps %}} + +#### Create a Node.js application + +Inject the following environment variables: + +```env +APP_FOLDER="/src/frontend/servers/y-provider" +CC_NODE_BUILD_TOOL="yarn" +CC_PRE_BUILD_HOOK="cd ./src/frontend/servers/y-provider && yarn install --frozen-lockfile && yarn build" +CC_RUN_COMMAND="cd ./src/frontend/servers/y-provider && yarn start" +COLLABORATION_LOGGING="true" +COLLABORATION_SERVER_ORIGIN="https://" +COLLABORATION_SERVER_SECRET="" +Y_PROVIDER_API_KEY="" +``` + +You can add the value you want for `COLLABORATION_SERVER_SECRET` and `Y_PROVIDER_API_KEY`. You can generate them using a command like `openssl rand -base64 32` + +#### Set y-provider domain + +Select **Domain names** and add the following domains: + +- Domain: `` +- Route: `/collaboration/api/` + +- Domain: `` +- Route: `/ws/` + +#### Connect to the backend + +Select **Exposed configuration** and inject the following environment variables into the y-provider : + +```env +COLLABORATION_API_URL="https:///collaboration/api/" +COLLABORATION_SERVER_SECRET="" +``` + +Then select the **backend** application > **Service dependencies** > **Link applications** and choose the y-provider application. + +#### Push your code + +If you push using git, add the remote as `clever-y-provider`, for example. + +{{% /steps %}} + +## How to configure Docs + +Docs depends on some services that needs configuration before it can function. Use the **Create > an add-on** function to create each dependency on Clever Cloud. + +### Keycloak + +Docs uses Keycloak as an authentication provider. Configure it by following these steps: + +{{% steps %}} + +#### Create a Keycloak add-on + +If you don't have a Keycloak instance, create one on Clever Cloud. If you already have one, skip this step. For the sake of demonstration, this guide follows [the example values provided by Docs](https://github.com/suitenumerique/docs/blob/main/docs/examples/helm/impress.values.yaml). You can rename them as you see fit. + +#### Create a new realm + +Name it `impress`. + +#### Create a new client + +Name it `impress` as well. + +#### Client settings + +##### General settings + +- Client ID: impress +- Client name: impress +- Always Display in UI: ON + +##### Access settings + +- Root URL: `https://` +- Home URL: `https://` +- Valid redirect URIs: `https:///api/v1.0/callback/*` +- Valid post logout redirect URIs: `https:///*` +- Web origins: `https://` + +##### Capability config + +- Client authentication: On +- Authorization: Off +- Authentication flow: Standard flow + +##### Find the Client Secret + +Find it in **Clients > impress > credentials**, named **Client secret*. + +##### Optional : Add an identity provider + +You can choose among different identity providers (GitHub, Google, etc, and even Clever Cloud). + +#### Inject the variables in the **backend** application + +```env +OIDC_OP_AUTHORIZATION_ENDPOINT="https:///realms/impress/protocol/openid-connect/auth" +OIDC_OP_JWKS_ENDPOINT="https:///realms/impress/protocol/openid-connect/certs" +OIDC_OP_LOGOUT_ENDPOINT="https:///realms/impress/protocol/openid-connect/session/end" +OIDC_OP_TOKEN_ENDPOINT="https:///realms/impress/protocol/openid-connect/token" +OIDC_OP_USER_ENDPOINT="https:///realms/impress/protocol/openid-connect/userinfo" +OIDC_RP_CLIENT_ID="impress" +OIDC_RP_CLIENT_SECRET="" +OIDC_RP_SCOPES="openid email" +OIDC_RP_SIGN_ALGO="RS256" +``` + +{{% /steps %}} + +### Redis + +Create a Redis add-on, but don't connect it to the application, since Docs requires an URI format that differs from the one provided by Clever Cloud. Instead, inject the variable in the **backend** application, using this format: `REDIS_URL="redis://default:@:"` + +### Cellar + +Docs uses s3 compatible storage to store uploaded files by users. + +{{% steps %}} + +#### Create a Cellar add-on + +#### Create a bucket + +#### Inject the variables in the **backend** application + +```env +AWS_S3_ACCESS_KEY_ID="" +AWS_S3_ENDPOINT_URL="" +AWS_S3_REGION_NAME="auto" +AWS_S3_SECRET_ACCESS_KEY="" +AWS_STORAGE_BUCKET_NAME="" +AWS_REQUEST_CHECKSUM_CALCULATION="when_required" +AWS_RESPONSE_CHECKSUM_VALIDATION="when_required" +``` + +{{% /steps %}} + +## 🎓 Further Help + +{{< cards >}} + {{< card link="https://github.com/suitenumerique/docs/blob/main/docs/installation.md#preparation" title="Docs documentation" subtitle="Installation instructions" icon="adjustments-horizontal" >}} +{{< /cards >}} diff --git a/content/guides/docusaurus.md b/content/guides/docusaurus.md new file mode 100644 index 000000000..c6117fc92 --- /dev/null +++ b/content/guides/docusaurus.md @@ -0,0 +1,53 @@ +--- +type: docs +title: Docusaurus +description: Build your website with the Docusaurus Static Site Generator (SSG) and host it on Clever Cloud. No dedicated runner needed. +tags: +- guides +keywords: +- docusaurus +- nodejs +- static +- ssg +- html +- js +- css +- website +aliases: +- /docusaurus +comments: false +--- + +{{< hextra/hero-subtitle >}} + Docusaurus is a static site generator that helps you build optimized websites quickly. It is designed to help you create documentation, blogs, and other content-driven sites with ease. +{{< /hextra/hero-subtitle >}} + +## Requirements + +If you need an example source code, init a new project (you'll need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs)): + +```bash +npx create-docusaurus@latest myStaticApp classic +``` + +{{% content "static-create" %}} + +### Automatic build + +Docusaurus is one of the many Static Site Generator (SSG) that [Clever Cloud automatic build](/developers/doc/applications/static/#static-site-generators-ssg-auto-build) supports in the `static` runtime, you don't have anything special to manage. To use a pico instance with a dedicated build instance change it in the [Console](https://console.clever-cloud.com) or with Clever Tools: + +```bash +clever scale --flavor pico + +# To select a bigger build instance, use: +clever scale --build-flavor M +``` + +{{% content "static-deploy" %}} + +## 🎓 Learn more + +{{< cards >}} + {{< card link="/developers/doc/applications/static" title="Deploy a Static application" subtitle="How to configure your website" icon="static" >}} + {{< card link="https://docusaurus.io/docs" title="Learn Docusaurus" subtitle="How to write and organize your content" icon="docusaurus" >}} +{{< /cards >}} diff --git a/content/guides/ekg-statsd-haskell-metrics.md b/content/guides/ekg-statsd-haskell-metrics.md new file mode 100644 index 000000000..76138282f --- /dev/null +++ b/content/guides/ekg-statsd-haskell-metrics.md @@ -0,0 +1,65 @@ +--- +type: docs +title: Ekg-statsd +description: This tutorial helps you configure ekg-statsd package on your Haskell application to push custom metrics +tags: +- deploy +- administrate +keywords: +- haskell +- ekg-statsd +- logs +- metrics +aliases: +- /doc/deploy/application/haskell/tutorials/ekg-statsd-haskell-metrics.md +--- + +## Overview + +In Haskell, metrics are usually gathered with [EKG](https://hackage.haskell.org/package/ekg). + +The package `ekg-statsd` allows to push EKG metrics over `statsd`. +EKG allows you to have access to GC metrics, make sure you compile your application with `"-with-rtsopts=-T -N"` to enable profiling. + +If you're using [warp](https://hackage.haskell.org/package/warp), you can use `wai-middleware-metrics` to report request distributions (request count, responses count aggregated by status code, responses latency distribution). + +### Configure logs for your Haskell application + +You need the following packages in your [dependencies](/developers/doc/applications/haskell#dependencies): + +* ekg-core +* ekg-statsd +* scotty +* wai-middleware-metrics + +Then add this Hello World code to your application and modify it to fit your needs: + +```haskell +{-# LANGUAGE OverloadedStrings #-} +import Control.Monad (when) +import Network.Wai.Metrics (WaiMetrics, metrics, + registerWaiMetrics) +import System.Metrics (newStore, registerGcMetrics) +import System.Remote.Monitoring.Statsd (defaultStatsdOptions, + forkStatsd) +import Web.Scotty + +handleMetrics :: IO WaiMetrics +handleMetrics = do + store <- newStore + registerGcMetrics store + waiMetrics <- registerWaiMetrics store + sendMetrics <- maybe False (== "true") <$> lookupEnv "ENABLE_METRICS" + when sendMetrics $ do + putStrLn "statsd reporting enabled" + forkStatsd defaultStatsdOptions store + return () + return waiMetrics + +main = do + waiMetrics <- handleMetrics + scotty 8080 $ do + middleware $ metrics waiMetrics + get "/" $ + html $ "Hello world" +``` diff --git a/content/guides/eleventy.md b/content/guides/eleventy.md new file mode 100644 index 000000000..a52c27e4a --- /dev/null +++ b/content/guides/eleventy.md @@ -0,0 +1,57 @@ +--- +type: docs +title: Eleventy (11ty) +description: Build your website with the Eleventy (11ty) Static Site Generator (SSG) and host it on Clever Cloud. No dedicated runner needed. +tags: +- guides +keywords: +- Eleventy +- 11ty +- nodejs +- static +- ssg +- html +- js +- css +- website +aliases: +- /eleventy +comments: false +--- +{{< hextra/hero-subtitle >}} + Eleventy (11ty) is a simple static site generator that allows you to create fast, modern websites with minimal configuration. +{{< /hextra/hero-subtitle >}} + +## Requirements + +If you need an example source code, get [11ty base blog](https://github.com/11ty/eleventy-base-blog), you'll need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git): + +```bash +git clone https://github.com/11ty/eleventy-base-blog myStaticApp +``` + +{{% content "static-create" %}} + +### Environment variables + +Next, configure the application with a pico instance with dedicated build, enough for a simple website. As Clever Cloud is based on standards, you only need to define a few variables: + +```bash +clever scale --flavor pico + +# To select a bigger build instance, use: +clever scale --build-flavor M + +clever env set CC_WEBROOT "/_site" +clever env set CC_PRE_BUILD_HOOK "npm install" +clever env set CC_BUILD_COMMAND "npx @11ty/eleventy" +``` + +{{% content "static-deploy" %}} + +## 🎓 Learn more + +{{< cards >}} + {{< card link="/developers/doc/applications/static" title="Deploy a Static application" subtitle="How to configure your website" icon="static" >}} + {{< card link="https://www.11ty.dev/docs/" title="Learn Eleventy (11ty)" subtitle="How to write and organize your content" icon="11ty" >}} +{{< /cards >}} diff --git a/content/guides/fluentd.md b/content/guides/fluentd.md new file mode 100644 index 000000000..d6a00ed4a --- /dev/null +++ b/content/guides/fluentd.md @@ -0,0 +1,147 @@ +--- +type: docs +title: Fluentd +description: How to deploy a fluentd using Docker on Clever Cloud +tags: +- deploy +keywords: +- docker +- ruby +- fluentd +aliases: +- /doc/deploy/application/docker/tutorials/fluentd +- /doc/docker/fluentd +- /fluentd +--- + +## Overview + +Since you deploy microservices on Clever Cloud, you may need some data pipes between your services to: + +* collect data from your PostgreSQL to create Elasticsearch indexes for your website search engine +* collect application logs to analyze them with Elasticsearch, then archive them with S3 +* collect Apache access logs to analyze them in MongoDB +* extract data from the database of your PHP/MySQL application to transform then load them in your other node.js/PostgreSQL application +* and many more … + +Fluentd is an open source data collector written in Ruby, which lets you unify the data collection and consumption for a better use and understanding of data. + +{{< callout type="info" >}} + Ruby application on Clever Cloud requires **Puma** webserver but fluentd is using **excon**. +{{< /callout >}} + +{{% content "create-application" %}} + + {{% content "set-env-vars" %}} + +## Configure your Fluentd + Docker application + +### Mandatory configuration + +To follow this tutorial, you will need: + +* Ruby >= 2.4.4 (w/ Rubygems) +* Bundler +* Docker +* Git +* curl +* a Ruby versions manager + +{{< callout type="info" >}} +To manage your gems and ruby versions, we recommend [rbenv](https://github.com/sstephenson/rbenv). +{{< /callout >}} + +### My application does not exists already + +#### Create a fluentd application locally + +```bash +mkdir myFluentd +cd myFluentd +touch Gemfile Dockerfile go.sh td-agent.conf +chmod +x go.sh +``` + +Inside `Gemfile` put the following: + +```ruby +source 'https://rubygems.org' + +ruby '2.4.4' + +gem 'fluentd' +gem 'fluent-plugin-td' +``` + +Then run bundler to install dependencies and generate your `Gemfile.lock` + +```bash +bundle install +``` + +Clever Cloud needs that your application answers on requests made on `0.0.0.0:8080`, we'll use a PORT environment variable for local test purposes (this variable is automatically setup on each application). +Inside `td-agent.conf` put the following: + +```yaml + + @type monitor_agent + bind 0.0.0.0 + port "#{ENV['PORT']}" + +``` + +Inside `go.sh` put the following: + +```bash +#!/bin/sh + +bundle exec fluentd --use-v1-config -c td-agent.conf + +echo "🌍 Fluentd server started" +``` + +#### Test locally + +Start you service + +```bash +PORT=9292 ./go.sh +``` + +Verify that it responds to requests + +```bash +curl 0.0.0.0:9292 +``` + +You can now read [My application already exists](#my-application-already-exists) + +#### Fine tune you application + +You can [update your configuration](https://docs.fluentd.org/v1.0/articles/config-file) with all inputs, filters and outputs you need or check for a [community based plugin](https://www.fluentd.org/plugins). + +### My application already exists + +#### Prepare your application for deployment + +Create a `Dockerfile` at the root of your project and put inside the following (assuming your start script is in `go.sh`): + +```dockerfile +FROM ruby:2.4.4 +EXPOSE 8080 +COPY Gemfile Gemfile.lock td-agent.conf go.sh ./ + +RUN bundle config --global frozen 1 +RUN bundle install +RUN chmod +x go.sh + +CMD [ "/go.sh" ] +``` + + {{% content "env-injection" %}} + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} diff --git a/content/guides/go-echoip.md b/content/guides/go-echoip.md new file mode 100644 index 000000000..5133ab5f1 --- /dev/null +++ b/content/guides/go-echoip.md @@ -0,0 +1,82 @@ +--- +title: Go - Echoip +description: Deploy EchoIP on Clever Cloud +tags: +- guides +keywords: +- go +- echoip +- EchoIP +type: "docs" +#date: 2024-05-06T09:11:52+01:00 +draft: false +type: docs +--- + +[EchoIP](https://github.com/mpolden/echoip) is a simple service for looking up + your IP address. + +This doc explains how to install and configure EchoIP from source, and how to deploy it as a [Go application](/developers/doc/applications/golang "Go documentation") on Clever Cloud. + +## How to Configure and Deploy EchoIP on Clever Cloud + + +### Download EchoIP + +You can download EchoIP from and create a new origin. + + +First clone EchoIP's repository: +``` +~ $ git clone https://github.com/mpolden/echoip.git +~ $ cd echoip +``` + +### Configure `clevercloud/go.json` + +Create the necessary files to build and run the application: +``` +echoip/ ~ $ mkdir clevercloud +echoip/ ~ $ cat << EOF > clevercloud/go.json +{ + "deploy": { + "makefile": "Makefile", + "main": "../go_home/bin/echoip" + } +} +EOF +echoip/ ~ $ git add clevercloud/ +echoip/ ~ $ git commit -m "add clevercloud files" clevercloud/ +``` + + + {{% content "set-env-vars" %}} + + + +Define necessary environment variables (this is specific to EchoIP): +``` +echoip/ ~ $ clever env set CC_RUN_COMMAND "~/go_home/bin/echoip -H X-Forwarded-For" +Your environment variable has been successfully saved +``` + + + {{% content "deploy-git" %}} + + + +Add the clevercloud git remote: +``` +echoip/ ~ $ git remote add clevercloud $(jq -r '.apps[0].git_ssh_url' < .clever.json) +``` + +Push the app for deployment: +``` +echoip/ ~ $ git push clevercloud master +``` + +Check the deployment logs: +``` +echoip/ ~ $ clever logs +``` + diff --git a/content/guides/hexo.md b/content/guides/hexo.md new file mode 100644 index 000000000..d72381bba --- /dev/null +++ b/content/guides/hexo.md @@ -0,0 +1,60 @@ +--- +type: docs +title: Hexo +description: Build your website with the Hexo Static Site Generator (SSG) and host it on Clever Cloud. No dedicated runner needed. +tags: +- guides +keywords: +- hexo +- nodejs +- static +- ssg +- html +- js +- css +- website +comments: false +--- + +{{< hextra/hero-subtitle >}} + Hexo is a fast, simple and powerful blog framework that allows you to create static websites with ease. +{{< /hextra/hero-subtitle >}} + +## Requirements + +If you need an example source code, initialize an Hexo project with [Cactus theme](https://github.com/probberechts/hexo-theme-cactus) (you'll need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs)): +```bash +npx hexo init myStaticApp --no-install +``` + +{{% content "static-create" %}} + +Import the theme as a submodule: + +```bash +git submodule add https://github.com/probberechts/hexo-theme-cactus.git themes/cactus +``` + +### Environment variables + +Next, configure the application with a pico instance with dedicated build, enough for a simple website. As Clever Cloud is based on standards, you only need to define a few variables: + +```bash +clever scale --flavor pico + +# To select a bigger build instance, use: +clever scale --build-flavor M + +clever env set CC_WEBROOT "/public" +clever env set CC_PRE_BUILD_HOOK "npm install" +clever env set CC_BUILD_COMMAND "npm run build" +``` + +{{% content "static-deploy" %}} + +## 🎓 Learn more + +{{< cards >}} + {{< card link="/developers/doc/applications/static" title="Deploy a Static application" subtitle="How to configure your website" icon="static" >}} + {{< card link="https://hexo.io/docs/" title="Learn Hexo" subtitle="How to write and organize your content" icon="hexo" >}} +{{< /cards >}} diff --git a/content/guides/hugo-static-s3.md b/content/guides/hugo-static-s3.md new file mode 100644 index 000000000..4b8523df6 --- /dev/null +++ b/content/guides/hugo-static-s3.md @@ -0,0 +1,171 @@ +--- +title: Hugo + Cellar +description: Build your website with Hugo and deploy it through Cellar, a S3-compatible object storage +tags: +- guides +keywords: + +type: "docs" +comments: false +draft: false +--- + +When creating a static website, it's possible to host it using a runtime. +You can also use Cellar, a S3-compatible object storage. This hosting method saves time on configuration and application management, and is fast. + +To do so, you need: + +- a [Clever Cloud account](/developers/doc/quickstart/) +- [Hugo](https://gohugo.io/) on your machine +- to have [created your website](https://gohugo.io/getting-started/quick-start/) files with Hugo +- a Cellar add-on; if you have never created an add-on, you can follow [this guide](/developers/doc/quickstart/#create-your-first-add-on) + +## Bucket creation and management + +To create a bucket: + +- Follow the [bucket creation instructions](/developers/doc/addons/cellar/#creating-a-bucket), +- or use third party software like [s3cmd](https://s3tools.org/s3cmd). + +{{< callout type="warning" >}} + Your bucket name must match the domain name you want to use. If your domain name is `my-static-website.com`, your bucket name must be : `my-static-website.com`. +{{< /callout >}} + +To use a custom domain, for example `cdn.example.com`, you need to create a bucket named exactly like your domain: + +```bash +s3cmd --host-bucket=cellar-c2.services.clever-cloud.com mb s3://cdn.example.com +``` + +Then, create a CNAME record on your domain pointing to `cellar-c2.services.clever-cloud.com.`. + +## Public access policy + +By default, your bucket is only visible and manageable an authenticated user. +To make your bucket publicly accessible, you have to apply a policy to the bucket + +{{< callout type="warning" >}} + This makes all of your bucket's objects publicly readable. Be careful that there aren't objects you don't want publicly exposed. +{{< /callout >}} + +To set your bucket as public, you have to apply the following policy which you can save in a file named `policy.json`: + +```json{filename="policy.json"} +{ + "Id": "Policy1587216857769", + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "Stmt1587216727444", + "Action": [ + "s3:GetObject" + ], + "Effect": "Allow", + "Resource": "arn:aws:s3:::/*", + "Principal": "*" + } + ] +} +``` + +Replace the `` with your bucket name in the policy file. Don't change the `Version` field to the current date, keep it as is. + +Now, you can set the policy to your bucket using s3cmd: + +```bash +s3cmd setpolicy ./policy.json s3:// +``` + +If you encounter errors, you might need to specify the [configuration file path](#download-the-configuration-file): + +```bash +s3cmd setpolicy ./policy.json -c path/to/s3cfg.txt s3:// +``` + +All of your objects should now be publicly accessible. +If needed, you can delete this policy by using: + +```bash +s3cmd delpolicy s3:// +``` + +The original ACL should apply to all of your objects after that. + +## Hugo configuration for Cellar + +Hugo doesn’t know by default the path to your bucket in your Cellar. You have to add a few things to guide the deployment process. + +In the folder of your website, you’ll find Hugo’s configuration file: + +- `hugo.toml` +- `hugo.yaml` +- `hugo.json` + +Open it, then add the following (according to the programing language): + +{{< tabs items="JSON,YAML,TOML" >}} + + {{< tab >}}**JSON** + +```json {filename="hugo.json"} + { + "deployment": { + "targets": [ + { + "name": "(a name for your own reference)", + "URL": "s3://?endpoint=https://®ion=fr-par" + } + ] + } + } + ``` + + +{{< /tab >}} + + {{< tab >}}**YAML** + + ```json {filename="hugo.yaml"} + deployment: + targets: + - name: "(a name for your own reference)" + - URL: "s3://?endpoint=https://®ion=fr-par" + ``` + + {{< /tab >}} + + + {{< tab >}}**TOML** +```json {filename="hugo.toml"} +[deployment] +[[deployment.targets]] +name: "(a name for your own reference)" +URL: "s3://?endpoint=https://®ion=fr-par" + ``` + +{{< /tab >}} + +{{< /tabs >}} + +- The deployment name is arbitrary and for your own reference: “production”, “test”, anything you’d like. +- The cellar host address can found on your Clever Cloud console: select your Cellar and you’ll have the “Host” field. The address looks like: `cellar-c2.services.clever-cloud.com` + +Save your configuration file: Hugo now knows where to send file when deploying. + + + +To deploy, proceed as usual: `hugo` to build the website locally, then `hugo deploy` to push files through Cellar. +If all the steps have been correctly completed, you are now able to access your website with: + `https://.` + + +Is's possible to encounter an error where the website warns the user with a "not secure" message. +This happens when the SSL certificate was not properly generated. +You can manually generate one certificate by creating an application, then adding the domain name from the "domain" tab. +The certification propagation takes about 10-15mn. + +If you still encounter an issue at this point, please contact our support team. + + + + diff --git a/content/guides/hugo.md b/content/guides/hugo.md new file mode 100644 index 000000000..99de4b0f2 --- /dev/null +++ b/content/guides/hugo.md @@ -0,0 +1,61 @@ +--- +type: docs +title: Hugo +description: Build your website with the Hugo Static Site Generator (SSG) and host it on Clever Cloud. No dedicated runner needed. +tags: +- guides +keywords: +- hugo +- static +- ssg +- html +- js +- css +- website +comments: false +aliases: +- /hugo +--- + +{{< hextra/hero-subtitle >}} + Hugo is a fast and flexible static site generator that allows you to create modern websites with ease. +{{< /hextra/hero-subtitle >}} + +## Requirements + +If you need an example source code, use the [Hugo Profile theme](https://github.com/gurusabarish/hugo-profile) example, you'll need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git): + +```bash +git clone https://github.com/gurusabarish/hugo-profile/ + +# Just keep exampleSite directory content to deploy the Hugo website +mv hugo-profile/exampleSite myStaticApp && rm -rf hugo-profile +``` + +{{% content "static-create" %}} + +Import the theme as a submodule: + +```bash +git submodule add https://github.com/gurusabarish/hugo-profile.git themes/hugo-profile +``` + +### Automatic build + +Hugo is one of the many Static Site Generator (SSG) that [Clever Cloud automatic build](/developers/doc/applications/static/#static-site-generators-ssg-auto-build) supports in the `static` runtime, you don't have anything special to manage. To use a pico instance with a dedicated build instance change it in the [Console](https://console.clever-cloud.com) or with Clever Tools: + +```bash +clever scale --flavor pico + +# To select a bigger build instance, use: +clever scale --build-flavor M +``` + +{{% content "static-deploy" %}} + +## 🎓 Learn more + +{{< cards >}} + {{< card link="/developers/doc/applications/static" title="Deploy a Static application" subtitle="How to configure your website" icon="static" >}} + {{< card link="https://gohugo.io/documentation/" title="Learn Hugo" subtitle="How to write and organize your content" icon="hugo" >}} +{{< /cards >}} diff --git a/content/guides/kibana.md b/content/guides/kibana.md new file mode 100644 index 000000000..ad0926f8e --- /dev/null +++ b/content/guides/kibana.md @@ -0,0 +1,77 @@ +--- +type: docs +title: Kibana +description: How to deploy a custom Kibana for specific using cases +tags: +- addons +keywords: +- custom +- elsaticsearch +- elastic +- kibana +aliases: +- /doc/deploy/addon/elastic/kibana +- /kibana +--- + +{{< callout type="warning" >}} +To deploy a custom Kibana, you need to ask Clever Cloud Support team to enable superuser permissions for your user. +{{< /callout >}} + +## Overview + +[Kibana](https://www.elastic.co/fr/kibana/) is the web interface available on the Clever Cloud's platform to manage your Elastic Stack. + +By default, you can enable Kibana when you create an Elastic Stack add-on. + +## Enable Kibana with your Elastic Stack add-on + +Kibana can be enabled at the add-on creation. Choose "Create an add-on" > "Elastic Stack". Select your plan, applications which will use the Elastic Stack and name the add-on. On the "options" step, enable Kibana. Then, confirm the options and your add-on will start with a Kibana instance. + +### Customize the Kibana configuration file + +You can customize the Kibana configuration file by setting the `CC_PRE_RUN_HOOK` environment variable. This variable will be executed before the Kibana instance starts. By default, it is: + +``` +CC_PRE_RUN_HOOK` = `curl https://api.clever-cloud.com/v2/providers/es-addon/kibana-setup/ | sh` +``` + +To modify this default configuration ([Configuration file for Kibana 8.3.3](https://api.clever-cloud.com/v2/providers/es-addon/kibana-setup/8.3.3)), you need to host your own config file (we strongly recommend [Cellar](/developers/doc/deploy/addon/cellar)). + +Check other available configuration file on [GitHub](https://github.com/CleverCloud/custom-kibana-config). + +> [!TIP] +> If you use a custom configuration file, host it from your own Cellar add-on or any other trusted source. + +### Disable SSO authentication + +To disable SSO authentication and use elastic users instead, you need to modify Kibana's configuration file. We provide an example configuration file for Kibana 8.3.3: + +* https://raw.githubusercontent.com/CleverCloud/custom-kibana-config/master/8.3.3/no-sso-8.3.3 + +Remember, you need to ask Clever Cloud Support team to grant superuser permissions to your user. After that, you will be able to add additional users via Kibana. + +### Multiple authentication methods + +If you need to allow for multiple authentication methods to your Kibana, you need to modify Kibana's configuration. We provide an example configuration file for Kibana 8.10.2: + +* https://raw.githubusercontent.com/CleverCloud/custom-kibana-config/master/8.10.2/sso-basic-8.10.2 + +### Add custom domain name + +You need to disable SSO authentication first. Then, you will be able to add a custom domain name in "Domain name" tab of your Kibana app. + +## Deploy Kibana on localhost + +The Kibana version should match with the ElasticSearch version. + +Follow these steps : + +1. Download/unzip Kibana in version which match with your Elastic Stack version +2. Edit kibana.yml : + * line 43 : `elasticsearch.host: :443` + * line 49 : `elasticsearch.username: kibana` + * line 50 : `elasticsearch.password: ` + * Launch Kibana (`/bin/kibana`) +3. Go to Kibana through the dedicated local address: `http://localhost:5601` +4. Connect to ElasticSearch with your Elastic username and password diff --git a/content/guides/kubernetes-operator.md b/content/guides/kubernetes-operator.md new file mode 100644 index 000000000..d88d3049d --- /dev/null +++ b/content/guides/kubernetes-operator.md @@ -0,0 +1,629 @@ +--- +title: Kubernetes Operator +description: Manage your Clever Cloud databases and addons seamlessly from Kubernetes with the Clever Kubernetes Operator +tags: +- guides +keywords: +- Kubernetes +- operator +- databases +- crd +type: "docs" +comments: false +draft: false +aliases: +- /guides/clever-operator +--- + +## What's the Clever Kubernetes Operator + +The [Clever Kubernetes Operator](https://github.com/CleverCloud/clever-kubernetes-operator) is an open source project (MIT licensed) designed to seamlessly integrate [Clever Cloud](https://www.clever-cloud.com/)'s managed services into Kubernetes environments. By leveraging Kubernetes [Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions)), the Operator enables developers to manage Clever Cloud resources directly from their Kubernetes clusters, aligning cloud-native practices with Clever Cloud's powerful platform. + +Modern applications often require a combination of containerized workloads and managed services, such as databases or caches. Managing these resources separately across platforms can become complex and error-prone. The Clever Kubernetes Operator simplifies this process by acting as a bridge, allowing developers to define and interact with Clever Cloud's resources using familiar Kubernetes paradigms. + +### Why Use the Clever Kubernetes Operator? + +The Clever Kubernetes Operator was born from a concrete need: to allow users to manage Clever Cloud services directly from a Kubernetes cluster. It reconciles the best of both worlds: + +- Keep Kubernetes' flexibility for stateless applications +- Delegate the management of critical databases and services to Clever Cloud + +While Kubernetes excels at deploying applications, databases come with operational constraints (backup, replication, restoration, updates…) that make self-management challenging. With the operator, you can maintain the comfort of a managed service while keeping control in your Kubernetes manifests. + +### Supported Services + +Originally designed for managed databases, the Clever Kubernetes Operator has expanded to support a wide range of Clever Cloud services as native Kubernetes Custom Resources: + +- **Databases**: + - PostgreSQL + - MySQL + - MongoDB +- **Key-Value Storage**: + - Redis + - Materia KV +- **Object Storage**: + - Cellar (S3-compatible) +- **Search Engines**: + - Elasticsearch +- **Message Brokers**: + - Pulsar +- **Analytics Platforms**: + - Matomo + - Metabase + - Azimutt +- **Authentication Services**: + - Keycloak +- And more services to come + +### Key Features + +The Clever Kubernetes Operator provides: + +- **Custom Resource Definitions (CRDs):** Extend Kubernetes capabilities to manage Clever Cloud services +- **Declarative Resource Management:** Use YAML manifests to declare and maintain the desired state of your services +- **Seamless Integration:** Interact with Clever Cloud's API securely and efficiently +- **Automatic Secret Injection:** Connection details are automatically injected as Kubernetes Secrets +- **Prometheus Integration:** Metrics are exposed for monitoring +- **Operator Lifecycle Manager (OLM) Compatibility:** Works with standard Kubernetes operator frameworks + +This documentation guides you through: + +- Installing and configuring the Clever Kubernetes Operator in your cluster. +- Managing Clever Cloud resources such as PostgreSQL and Redis through examples. + + +## Prerequisites + +Before you begin, ensure that you have the following tools and resources based on your intended actions: + +### To Build the Operator + +- **Git:** Clone the Clever K8S Operator repository to access the source code. +- **Rust toolchain:** Install the Rust programming language and its toolchain to compile the operator from source. Follow the installation guide at [https://rustup.rs/](https://rustup.rs/). +- **Docker:** Build container images for deploying the operator in Kubernetes. + +### To Deploy the Operator + +- **Kubernetes Cluster:** Ensure you have access to a running Kubernetes cluster. +- **Kubectl:** Install Kubernetes command-line tool for managing cluster resources Installation guide available at https://kubernetes.io/docs/tasks/tools/. +- **Clever Cloud Account Credentials:** [Obtain API tokens and secrets from your Clever Cloud](/developers/api/howto) account to configure the operator. + +These prerequisites are essential for getting started with the Clever Kubernetes Operator, whether you're contributing to its development or deploying it in production. + +## Authentication + +The Clever Kubernetes Operator requires configuration to connect to Clever Cloud's API and manage resources within your cluster. Three authentication methods are supported: + +### 1. Full OAuth1 Authentication (4 parameters) + +This is the most complete authentication method, requiring all four OAuth1 parameters: + +- _Consumer key_ +- _Consumer Secret_ +- _Token_ +- _Secret_ + +To obtain these credentials, you need to connect to the Clever Cloud API, which uses OAuth1-based authentication. As explained in the [Clever Cloud API Overview](/developers/api/howto), you need to create an OAuth consumer token in the Clever Cloud console, use it to obtain the _Consumer key_ and the _Consumer Secret_, and complete the OAuth authentication process to get the _Token_ and _Secret_. + +Configuration example: + +```toml +[api] +token = "your-token" +secret = "your-secret" +consumer-key = "your-consumer-key" +consumer-secret = "your-consumer-secret" +``` + +**Best for:** +- Production environments +- Full control over permissions +- Fine-grained access scope configuration + + +> #### Need an easier way to get these credentials? +> +> Yes, the OAuth dance can be complex. For a simpler setup, there is a small application that you can deploy on Clever Cloud that automates most of the process for you. +> +> The code and tutorial are available at [https://github.com/CleverCloud/oauth-consumer-server](https://github.com/CleverCloud/oauth-consumer-server). + +### 2. Simplified OAuth1 Authentication (token + secret) + +This method uses only the token and secret, automatically using the public client credentials (like those from Clever Tools): + +```toml +[api] +token = "your-token" +secret = "your-secret" +``` + +If you already use the Clever Cloud CLI (clever-tools), you can extract these credentials from its configuration file, typically located at `$HOME/.config/clever-cloud/clever-tools.json`. The token and secret values can be found in this file and reused for the operator configuration. + +**Best for:** +- Standard usage scenarios +- Development, testing, or demos +- Users already using Clever Cloud CLI + +This is the recommended approach for most users. + +### 3. Bearer Token Authentication ("oauthless" mode) + +The simplest method: a single token for direct use, without consumer or secret: + +```toml +[api] +token = "your-bearer-token" +``` + +**Best for:** +- Simple integrations +- Quick scripts or automation +- Environments using the "oauthless" backend authentication + + +## Installation + +The Clever Kubernetes Operator can be deployed in several ways depending on your needs. + +### Quick Deployment from DockerHub + +The simplest method is to apply the published manifests directly: + +{{% steps %}} + +#### Apply the CRDs and deployment manifests + +```bash +kubectl apply -f https://raw.githubusercontent.com/CleverCloud/clever-kubernetes-operator/main/deployments/kubernetes/v1.30.0/10-custom-resource-definition.yaml +kubectl apply -f https://raw.githubusercontent.com/CleverCloud/clever-kubernetes-operator/main/deployments/kubernetes/v1.30.0/20-deployment.yaml +``` + +This installs the CRDs and the operator deployment using the official image. + +#### Configure your credentials + +After deployment, you'll need to update the ConfigMap with your authentication credentials: + +```bash +kubectl edit configmap clever-kubernetes-operator-configuration -n clever-kubernetes-operator-system +``` + +Modify the ConfigMap to include your credentials: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: clever-kubernetes-operator-configuration + namespace: clever-kubernetes-operator-system +data: + config.toml: | + [api] + endpoint = "https://api.clever-cloud.com/v2" + token = "" + secret = "" + consumerKey = "" + consumerSecret = "" +``` + +Replace ``, ``, ``, and `` with the credentials obtained using one of the authentication methods described earlier. + +{{% /steps %}} + +### Manual Deployment from Repository + +{{% steps %}} + +#### Clone the repository + +```bash +git clone https://github.com/CleverCloud/clever-kubernetes-operator/ +cd clever-kubernetes-operator +``` + +#### Insert your credentials into the manifests + +The manifests are in the folder `/deployments/kubernetes/v1.30.0/`. Modify the `ConfigMap` object in the file `/deployments/kubernetes/v1.30.0/20-deployment.yaml`: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: clever-kubernetes-operator-configuration + namespace: clever-kubernetes-operator-system +data: + config.toml: | + [api] + endpoint = "https://api.clever-cloud.com/v2" + token = "" + secret = "" + consumerKey = "" + consumerSecret = "" +``` + +Replace ``, ``, ``, and `` with your credentials. + +#### Apply the manifests to deploy the operator + +```bash +kubectl apply -f deployments/kubernetes/v1.30.0/10-custom-resource-definition.yaml +kubectl apply -f deployments/kubernetes/v1.30.0/20-deployment.yaml +``` + +{{% /steps %}} + +### Installing via Helm Chart + +For more flexibility and customization options, you can use the Helm chart provided with the operator. + +{{% steps %}} + +#### Clone the repository + +```bash +git clone https://github.com/CleverCloud/clever-kubernetes-operator/ +cd clever-kubernetes-operator/deployments/kubernetes/helm +``` + +#### Configure your credentials in the `values.yaml` file + +Edit the `values.yaml` file to include your authentication credentials in the `config` section: + +```yaml +config: + endpoint: "https://api.clever-cloud.com/v2" + token: "" + secret: "" + consumerKey: "" + consumerSecret: "" +``` + +Replace ``, ``, ``, and `` with the credentials obtained using one of the authentication methods described earlier. + +#### Customize other Helm chart values (optional) + +The `values.yaml` file allows you to customize various aspects of the deployment, such as: + +- Resource limits and requests +- Node selector, tolerations, and affinity +- Service account configuration +- Image repository and tag +- Namespace configuration + +#### Install the chart + +```bash +helm install clever-kubernetes-operator . -n clever-kubernetes-operator --create-namespace -f values.yaml +``` + +#### Verify the installation + +```bash +kubectl get pods -n clever-kubernetes-operator +``` + +You should see the operator pod running in the specified namespace. + +{{% /steps %}} + +### Building from Source + +{{% steps %}} + +#### Clone the repository + +```bash +git clone https://github.com/CleverCloud/clever-kubernetes-operator.git +cd clever-kubernetes-operator +``` + +#### Build the binary + +The operator is written in Rust. Make sure you have the Rust toolchain installed (follow the installation guide at [https://rustup.rs/](https://rustup.rs/) if needed). + +```bash +make build +``` + +#### Configure the operator + +Create a configuration file (e.g., `config.toml`) with your credentials: + +```toml +[api] +endpoint = "https://api.clever-cloud.com/v2" +token = "" +secret = "" +consumerKey = "" +consumerSecret = "" +``` + +Replace ``, ``, ``, and `` with your credentials. + +#### Run the operator + +```bash +target/release/clever-kubernetes-operator --config config.toml +``` + +{{% /steps %}} + +## Deployment Options + +The Clever Kubernetes Operator offers flexible deployment options to suit different operational needs: + +### In-Cluster Deployment + +This is the standard deployment model where the operator runs as a pod within your Kubernetes cluster: + +- **Advantages**: + - Direct access to Kubernetes API without additional configuration + - Standard Kubernetes RBAC controls + - Follows the typical operator pattern + +- **Best for**: + - Standard Kubernetes environments + - When you want to keep all components within the cluster + +### Remote Deployment from Clever Cloud + +An alternative approach is to run the operator as a Clever Cloud application that connects to your Kubernetes cluster remotely: + +- **Advantages**: + - Reduces resource consumption on your Kubernetes cluster + - Centralizes control when managing multiple clusters + - Leverages Clever Cloud's managed platform for the operator itself + +- **Best for**: + - Managing multiple Kubernetes clusters + - Reducing cluster resource usage + - Centralizing operator management + +#### Setting up Remote Deployment + +1. Create a new application on Clever Cloud +2. Configure the application with: + - The operator binary or Docker image + - A valid `kubeconfig` file with appropriate permissions + - Your Clever Cloud API credentials +3. Deploy the application + +The operator will connect to your Kubernetes cluster using the provided `kubeconfig` and manage resources as if it were running inside the cluster. + +## Configuration + +Configuration options are available at two levels: global (applies to all namespaces) and namespace-specific. + +### Global Configuration + +Global configuration settings apply across all namespaces. Global configuration can be provided through a `ConfigMap`, a `Secret` or by the environment. + +- **Environment Variables:** + + - `CLEVER_OPERATOR_API_ENDPOINT`: The endpoint for the Clever Cloud API. + - `CLEVER_OPERATOR_API_TOKEN`: Your Clever Cloud API token. + - `CLEVER_OPERATOR_API_SECRET`: The secret associated with your API token. + - `CLEVER_OPERATOR_API_CONSUMER_KEY`: Your Clever Cloud consumer key + - `CLEVER_OPERATOR_API_CONSUMER_SECRET`: Your Clever Cloud consumer secret. + +- **Configuration Files:** By default, if the `--config` flag isn't provided to the binary, the operator looks at the following locations to retrieve its configuration (in order of priority): + + 1. `/usr/share/clever-kubernetes-operator/config.{toml,yaml,json}` + 2. `/etc/clever-kubernetes-operator/config.{toml,yaml,json}` + 3. `$HOME/.config/clever-kubernetes-operator/config.{toml,yaml,json}` + 4. `$HOME/.local/share/clever-kubernetes-operator/config.{toml,yaml,json}` + 5. `config.{toml,yaml,json}` (in the current working directory) + + +### Namespace-Level Configuration + +Namespace-level configurations override the global settings for specific namespaces. They're defined using a Kubernetes Secret resource named `clever-kubernetes-operator` with the `config` key. + +- **Creating a Namespace-Level Configuration:** Create a Kubernetes Secret with the necessary configuration keys: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: clever-secret + namespace: + stringData: + config: | + [api] + endpoint = "https://api.clever-cloud.com/v2" + token = + secret = + consumerKey = + consumerSecret = + ``` + +- **Applying the Configuration:** Apply the Secret to your namespace: + + ```bash + kubectl apply -f namespace-config.yaml + ``` + + +The operator automatically detects and applies namespace-specific configurations when interacting with resources in that namespace. + +### Validating Configuration + +To ensure your configuration applies correctly, look at the operator logs for any errors or warnings: + +```bash +kubectl logs -n clever-kubernetes-operator +``` + +## Usage Examples + +The Clever Kubernetes Operator enables you to manage Clever Cloud resources directly from your cluster using custom resources. Below are examples for various supported services. + +### How the Operator Works + +The Clever Kubernetes Operator acts as a bridge between your Kubernetes cluster and Clever Cloud. When you create a custom resource in your cluster: + +1. The operator detects the new resource +2. It calls the Clever Cloud API to create the corresponding service +3. Once the service is created, the operator automatically injects a Kubernetes Secret containing connection details +4. Your applications can then use these secrets to connect to the service + +### Managing PostgreSQL Resources + +- **Creating a PostgreSQL Instance:** Define a YAML manifest for the PostgreSQL resource: + + ```yaml + apiVersion: api.clever-cloud.com/v1 + kind: PostgreSQL + metadata: + name: my-postgresql + namespace: default + spec: + version: "14" + plan: "S" + region: "par" + encryption: true + ``` + + Apply the manifest to your cluster: + + ```bash + kubectl apply -f postgresql.yaml + ``` + +- **Verifying the Deployment:** Check the status of the PostgreSQL resource: + + ```bash + kubectl get postgresql my-postgresql -o yaml + ``` + +- **Accessing PostgreSQL:** The operator automatically creates a Secret with the same name as your resource containing connection details: + + ```bash + kubectl get secret my-postgresql -o yaml + ``` + +### Managing Redis Resources + +- **Creating a Redis Instance:** Define a YAML manifest for the Redis resource: + + ```yaml + apiVersion: clever-cloud.com/v1 + kind: Redis + metadata: + name: my-redis + namespace: default + spec: + version: "704" + plan: "dev" + region: "par" + ``` + + Apply the manifest to your cluster: + + ```bash + kubectl apply -f redis.yaml + ``` + +- **Verifying the Deployment:** Check the status of the Redis resource: + + ```bash + kubectl get redis my-redis -o yaml + ``` + +- **Accessing Redis:** Retrieve the connection details from the Clever Cloud dashboard or the resource's status field. + +### Additional Supported Resources + +The Clever Kubernetes Operator supports many other Clever Cloud services, including: + +- Elasticsearch +- MongoDB +- MySQL +- Cellar (S3-compatible object storage) +- Pulsar (message broker) +- Matomo (analytics) +- Metabase (business intelligence) +- Azimutt (database visualization) +- Keycloak (authentication) + +For examples of how to configure these resources, refer to the `examples/kubernetes` directory in the [Clever Kubernetes Operator repository](https://github.com/CleverCloud/clever-kubernetes-operator). These examples provide YAML manifests for all supported resources with their available configuration options. + +## Troubleshooting + +If you encounter issues with the Clever Kubernetes Operator, here are some common problems and their solutions: + +### Operator Pod Not Starting + +**Symptoms:** The operator pod stays in `Pending` or `CrashLoopBackOff` state. + +**Possible Solutions:** + +1. Check pod events and logs: + ```bash + kubectl describe pod -n clever-kubernetes-operator + kubectl logs -n clever-kubernetes-operator + ``` + +2. Verify resource constraints: + - Ensure your cluster has sufficient resources + - Check if there are any node selectors or taints preventing scheduling + +### Authentication Errors + +**Symptoms:** The operator logs show authentication or authorization errors when trying to connect to the Clever Cloud API. + +**Possible Solutions:** + +1. Verify your credentials are correct in the ConfigMap or Secret +2. Ensure you're using the right authentication method for your use case +3. Check if your API tokens have expired or been revoked +4. Verify network connectivity to the Clever Cloud API + +### Custom Resources Not Being Processed + +**Symptoms:** You create a custom resource, but nothing happens and no corresponding service appears in Clever Cloud. + +**Possible Solutions:** + +1. Check the operator logs for errors: + ```bash + kubectl logs -n clever-kubernetes-operator + ``` + +2. Verify the custom resource is valid: + ```bash + kubectl get -o yaml + ``` + +3. Ensure the CRDs are properly installed: + ```bash + kubectl get crds | grep clevercloud + ``` + +### Connection Secrets Not Created + +**Symptoms:** The service is created in Clever Cloud, but no Kubernetes Secret is created with connection details. + +**Possible Solutions:** + +1. Check the operator logs for errors related to secret creation +2. Verify the operator has permissions to create secrets in the target namespace +3. Check if there's a naming conflict with an existing secret + +### Version or Plan Not Available + +**Symptoms:** You get an error indicating that the specified version or plan is not available. + +**Possible Solutions:** + +1. Check the available versions and plans for the service in the Clever Cloud console +2. Update your custom resource to use a valid version and plan combination +3. Verify the region you selected supports the requested service + +### Getting Help + +If you continue to experience issues: + +1. Check the [GitHub repository](https://github.com/CleverCloud/clever-kubernetes-operator) for known issues or to report a new one +2. Contact Clever Cloud support for assistance with API or service-specific problems +3. Join the Clever Cloud community channels for peer support diff --git a/content/guides/lume-deno.md b/content/guides/lume-deno.md new file mode 100644 index 000000000..b90871ca5 --- /dev/null +++ b/content/guides/lume-deno.md @@ -0,0 +1,67 @@ +--- +type: docs +title: Lume (Deno) +description: Build your website with Lume Static Site Generator (SSG) using Deno and host it on Clever Cloud. No dedicated runner needed. +tags: +- guides +keywords: +- deno +- lume +- static +- ssg +- html +- js +- css +- website +comments: false +--- + +{{< hextra/hero-subtitle >}} + Lume is a fast and flexible static site generator built with Deno, designed to help you create modern websites with ease. +{{< /hextra/hero-subtitle >}} + +## Requirements + +If you need an example source code, use the [Lume website](https://github.com/lumeland/lume.land), you'll need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git): + +```bash +git clone https://github.com/lumeland/lume.land myStaticApp +``` +{{% content "static-create" %}} + +### Environment variables + +Next, configure the application with a pico instance with dedicated Medium build (needed for Deno), enough for a simple website. As Clever Cloud is based on standards, you only need to define a few variables: + +```bash +clever scale --flavor pico +clever scale --build-flavor M + +clever env set CC_WEBROOT "/_site" +clever env set CC_BUILD_COMMAND "deno task lume" +``` + +It defines `_site` as the folder to serve with the web server and `deno task lume` as the command to build the static files. + +### Deno installation + +Create a `mise.toml` file, add this content: + +```toml {filename="mise.toml"} +[tools] +deno = "latest" +``` + +It uses [Mise package manager](/developers/doc/reference/reference-environment-variables/#install-tools-with-mise-package-manager) to install Deno during deployment. You can replace `latest` with a specific version. + +> [!TIP] +> If you use Mise locally, run `mise trust` to trust the created `mise.toml` file + +{{% content "static-deploy" %}} + +## 🎓 Learn more + +{{< cards >}} + {{< card link="/developers/doc/applications/static" title="Deploy a Static application" subtitle="How to configure your website" icon="static" >}} + {{< card link="https://lume.land/docs/overview/about-lume/" title="Learn Lume" subtitle="How to write and organize your content" icon="deno" >}} +{{< /cards >}} diff --git a/content/guides/mdbook.md b/content/guides/mdbook.md new file mode 100644 index 000000000..a5abf0d78 --- /dev/null +++ b/content/guides/mdbook.md @@ -0,0 +1,52 @@ +--- +type: docs +title: mdBook +description: Build your website with the mdBook Static Site Generator (SSG) and host it on Clever Cloud. No dedicated runner needed. +tags: +- guides +keywords: +- mdbook +- rust +- static +- ssg +- html +- js +- css +- website +comments: false +--- + +{{< hextra/hero-subtitle >}} + mdBook is a command-line tool for creating modern online books and documentation. It is designed to help you write and organize your content in a structured way. +{{< /hextra/hero-subtitle >}} + +## Requirements + +If you need an example source code, init a new project (you'll need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [Rust](https://www.rust-lang.org/tools/install)): + +```bash +cargo install mdbook +mdbook init myStaticApp --title="my mdBook" --ignore=git +``` + +{{% content "static-create" %}} + +### Automatic build + +mdBook is one of the many Static Site Generator (SSG) that [Clever Cloud automatic build](/developers/doc/applications/static/#static-site-generators-ssg-auto-build) supports in the `static` runtime, you don't have anything special to manage. To use a pico instance with a dedicated build instance change it in the [Console](https://console.clever-cloud.com) or with Clever Tools: + +```bash +clever scale --flavor pico + +# To select a bigger build instance, use: +clever scale --build-flavor M +``` + +{{% content "static-deploy" %}} + +## 🎓 Learn more + +{{< cards >}} + {{< card link="/developers/doc/applications/static" title="Deploy a Static application" subtitle="How to configure your website" icon="static" >}} + {{< card link="https://rust-lang.github.io/mdBook/" title="Learn mdBook" subtitle="How to write and organize your content" icon="mdbook" >}} +{{< /cards >}} diff --git a/content/guides/mkdocs.md b/content/guides/mkdocs.md new file mode 100644 index 000000000..85ccbd608 --- /dev/null +++ b/content/guides/mkdocs.md @@ -0,0 +1,56 @@ +--- +type: docs +title: MkDocs +description: Build your website with the MkDocs Static Site Generator (SSG) and host it on Clever Cloud. No dedicated runner needed. +tags: +- guides +keywords: +- mkdocs +- python +- static +- ssg +- html +- js +- css +- website +comments: false +--- + +{{< hextra/hero-subtitle >}} + MkDocs is a static site generator that's geared towards project documentation. It allows you to write your documentation in Markdown and build a static website from it. +{{< /hextra/hero-subtitle >}} + +## Requirements + +If you need an example source code, init a new project (you'll need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), [Python](https://wiki.python.org/moin/BeginnersGuide/Download) and [pipx](https://pipx.pypa.io/stable/)): + +```bash +pipx mkdocs new myStaticApp +``` + +You can also use [uvx](https://docs.astral.sh/uv/guides/tools/): +```bash +uvx mkdocs new myStaticApp +``` + +{{% content "static-create" %}} + +### Automatic build + +MkDocs is one of the many Static Site Generator (SSG) that [Clever Cloud automatic build](/developers/doc/applications/static/#static-site-generators-ssg-auto-build) supports in the `static` runtime, you don't have anything special to manage. To use a pico instance with a dedicated build instance change it in the [Console](https://console.clever-cloud.com) or with Clever Tools: + +```bash +clever scale --flavor pico + +# To select a bigger build instance, use: +clever scale --build-flavor M +``` + +{{% content "static-deploy" %}} + +## 🎓 Learn more + +{{< cards >}} + {{< card link="/developers/doc/applications/static" title="Static runtime documentation" subtitle="How to configure your website" icon="static" >}} + {{< card link="https://www.mkdocs.org/getting-started/" title="MkDocs documentation" subtitle="How to write and organize your content" icon="docs" >}} +{{< /cards >}} diff --git a/content/guides/moodle.md b/content/guides/moodle.md new file mode 100644 index 000000000..73281a75a --- /dev/null +++ b/content/guides/moodle.md @@ -0,0 +1,138 @@ +--- +type: docs +title: Moodle +description: Deploy the world's open source learning platform on Clever Cloud +tags: +- guides +keywords: +- moodle +- mysql +- php +- css +- cms +aliases: +- /moodle +--- + +[Moodle](https://moodle.org) is a learning platform designed to provide +educators, administrators and learners with a single robust, secure and +integrated system to create personalised learning environments. + +This doc explains how to configure Moodle from source. Alternatively, an already configured repository exists as well on [Clever Cloud's GitHub page](https://github.com/CleverCloud/moodle). + +## How to Configure and Deploy Moodle on Clever Cloud + +{{% steps %}} + +### Download Moodle + +You can download Moodle from and initialize a Git repository at root with `git init`. + +### Configure `config.php` + +Duplicate `config-dist.php` and rename it `config.php`. Update the following variables as follows: + +```php {filename="config.php", linenos=table} +?php // Moodle configuration file + +unset($CFG); +global $CFG; +$CFG = new stdClass(); + +$CFG->dbtype = 'mysqli'; +$CFG->dblibrary = 'native'; +$CFG->dbhost = getenv("MYSQL_ADDON_HOST"); +$CFG->dbname = getenv("MYSQL_ADDON_DB"); +$CFG->dbuser = getenv("MYSQL_ADDON_USER"); +$CFG->dbpass = getenv("MYSQL_ADDON_PASSWORD"); +$CFG->prefix = 'mdl_'; +$CFG->dboptions = array ( + 'dbpersist' => 0, + 'dbport' => getenv("MYSQL_ADDON_PORT"), + 'dbsocket' => '', + 'dbcollation' => 'utf8mb4_0900_ai_ci', +); + +$CFG->wwwroot = getenv("URL"); +$CFG->dataroot = getenv("APP_HOME") . '/moodledata'; +$CFG->admin = getenv("ADMIN"); + +$CFG->directorypermissions = 0777; + +$CFG->sslproxy = true; + +require_once(__DIR__ . '/lib/setup.php'); + +// There is no php closing tag in this file, +// it is intentional because it prevents trailing whitespace problems! +``` + +Commit changes. + +### Declare the PHP Application + +On Clever Cloud Console, click **Create** > **An application** and choose a [PHP](/developers/doc/applications/php) application with Git deployment. Add a [MySQL](/developers/doc/addons/mysql) add-on during the process. + +### Set Up Environment Variables + +Add the following [environment variables](/developers/doc/develop/env-variables) to tour PHP application: + +```shell +CC_PHP_VERSION="8" +MAX_INPUT_VARS="5000" +URL="`. + +Add this variable to your **PHP application** and replace `/some/empty/folder` by `/moodledata`. Don't forget to **update changes**. + +### Set Up Domain + +Moodle needs an URL declared in variables to work properly. You can set it up in **Domains names**, from your PHP application menu. If you don't have a domain name yet, you can use a `cleverapp.io` subdomain provided by Clever Cloud for test purposes. + +Don't forget to update `URL=" **Information** > **Deployment URL** and add it to Git with `git remote add clever `. Then, push your code with `git push clever -u master` + +💡 If you get a reference error when pushing, try this: `git push clever main:master`. + +{{% /steps %}} + +## Cron for Moodle + +Moodle [recommends to set up a Cron job](https://docs.moodle.org/en/Cron) that runs every minute. For the Cron to execute as a PHP file, you will need to add a shebang at the very top of `admin/cli/cron.php`, like this: `#!/usr/bin/env php`. + +### Declare the cron in Clever Cloud + +Create a `clevercloud/cron.json` file with a string to run `admin/cli/cron.php`every minute: + +```json {filename="clevercloud/cron.json"} +[ + "* * * * * $ROOT/admin/cli/cron.php" +] +``` + +You might encounter errors when the Cron tries to access `moodledata` in your FS Bucket. For FS Bucket backups, look for a dedicated tool like [rclone](https://rclone.org). + +**Note**: this repository is already configured to run `/admin/cli/cron.php` every minute as a [cron job](/developers/doc/administrate/cron/). + +## 🎓 Further Help + +{{< cards >}} + {{< card link="/developers/doc/applications/php" title="PHP" subtitle="Deploy a PHP application on Clever Cloud" icon="php" >}} + {{< card link="/developers/doc/administrate/cron" title="CRON" subtitle="Set up a CRON job for your app" icon="code-bracket" >}} + {{< card link="/developers/doc/addons/fs-bucket" title="FS Bucket" subtitle="External File System for your apps" icon="fsbucket" >}} + {{< card link="/developers/doc/addons/mysql" title="MySQL" icon="mysql" subtitle="Your self-hosted managed relational database" >}} + {{< card link="https://docs.moodle.org/en/Installation_quick_guide" title="Moodle Documentation" subtitle="Check Moodle installation guide" icon="moodle" >}} +{{< /cards >}} + +See [Moodle installation documentation](https://docs.moodle.org/en/Installation_quick_guide) for further help and development configuration. diff --git a/content/guides/node-js-mongo-db.md b/content/guides/node-js-mongo-db.md new file mode 100644 index 000000000..b323ba77c --- /dev/null +++ b/content/guides/node-js-mongo-db.md @@ -0,0 +1,42 @@ +--- +type: docs +title: Node.js & MongoDB +description: The goal of this article is to show you how to deploy a Node.js with MongoDB application on Clever Cloud. +tags: +- deploy +keywords: +- nodejs +- mongodb +aliases: +- /doc/deploy/application/javascript/tutorials/node-js-mongo-db +- /doc/nodejs/nodejs-mongodb-sample-app +--- + +## Overview + +The goal of this article is to show you how to deploy a Node.js + MongoDB application on Clever Cloud. +The application is a very simple todo list. You can add and delete values. More information about the application: + +* [GitHub repo](https://github.com/CleverCloud/demo-nodejs-mongodb-rest) + +{{% content "create-application" %}} + + {{% content "set-env-vars" %}} + +## Configure your Node.js + MongoDB application + +### My application does not exists already + +If you want to test easily a Node.js deployment on Clever Cloud, just clone the [GitHub repo](https://github.com/CleverCloud/demo-nodejs-mongodb-rest). + + {{% content "env-injection" %}} + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +## Configure your database + +Make sure you have created a MongoDB add-on in the Clever Cloud console, and that it's linked to your application. When it's done, you will be able to access all of your add-on [environment variables](#setting-up-environment-variables-on-clever-cloud) from the application. + +{{% content "more-config" %}} diff --git a/content/guides/node-statsd-nodejs-metrics.md b/content/guides/node-statsd-nodejs-metrics.md new file mode 100644 index 000000000..71b341eb0 --- /dev/null +++ b/content/guides/node-statsd-nodejs-metrics.md @@ -0,0 +1,37 @@ +--- +type: docs +title: Node-statsd +description: This tutorial helps you configure node-statsd package on your Node.js application to push custom metrics +tags: +- deploy +keywords: +- nodejs +- metrics +- logs +- node-statsd +aliases: +- /doc/deploy/application/javascript/tutorials/node-statsd-nodejs-metrics +--- + +## Overview + +In Node.js, you can use the `node-statsd` package to push custom metrics. + +### Configure metrics for your Node.js application + +You only need the `node-statsd` package in your [dependencies](/developers/doc/applications/nodejs#npm-module-dependencies): + +Then add this Hello World code to your application and modify it to fit your needs: + +```javascript +// npm install node-statsd + +const StatsD = require('node-statsd'), + client = new StatsD(); + +// Increment: Increments a stat by a value (default is 1) +client.increment('my_counter'); + +// Gauge: Gauge a stat by a specified amount +client.gauge('my_gauge', 123.45); +``` diff --git a/content/guides/nuxt.md b/content/guides/nuxt.md new file mode 100644 index 000000000..5ad3b7e93 --- /dev/null +++ b/content/guides/nuxt.md @@ -0,0 +1,107 @@ +--- +type: docs +title: Nuxt +description: Build your website with Nuxt, either as a static site or using a NodeJs app, and host it on Clever Cloud. No dedicated runner needed. +tags: +- guides +keywords: +- nuxt +- nodejs +- static +- ssg +- html +- js +- css +- website +comments: false +--- + +{{< hextra/hero-subtitle >}} + Nuxt is a powerful and versatile web framework for building modern web applications, offering a seamless development experience with server-side rendering, static site generation, and hybrid capabilities. +{{< /hextra/hero-subtitle >}} + +Clever Cloud supports deploying both [fully static and on-demand rendered](https://nuxt.com/docs/guide/concepts/rendering) Nuxt 4 projects: + +- The `static` rendering mode is ideal for most content-oriented websites where you don't need per-visitor server-side customization. Consider using a [Static runtime](/developers/doc/applications/static/) when using this mode, with the automatic site generation. Learn more about [static hosting with Nuxt](https://nuxt.com/docs/getting-started/deployment#static-hosting). +- The `server` or `hybrid` rendering modes are optimal for dynamic applications requiring server-side customization or a mix of static and server-rendered pages. For these modes, consider using a [Node.js runtime](/developers/doc/applications/nodejs). Learn more about [Node.js hosting with Nuxt](https://nuxt.com/docs/getting-started/deployment#nodejs-server). + +If you need an example source code compatible with Nuxt static generation, get [Nuxt Boilerplate](https://github.com/renegadevi/nuxt-boilerplate) (you'll need [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs)): + +```bash +git clone https://github.com/renegadevi/nuxt-boilerplate myStaticApp +``` + +{{% content "static-create" %}} + +### Automatic build + +Nuxt is one of the many Static Site Generator (SSG) that [Clever Cloud automatic build](/developers/doc/applications/static/#static-site-generators-ssg-auto-build) supports in the `static` runtime. Then, you don't have anything special to manage. To use a pico instance with a dedicated build instance change it in the [Console](https://console.clever-cloud.com) or with Clever Tools: + +```bash +clever scale --flavor pico + +# To select a bigger build instance, use: +clever scale --build-flavor M +``` + +{{% content "static-deploy" %}} + +## Deploy a Node.js application + +To deploy your Nuxt project to Clever Cloud, you need to **create a new application**. + +### Create a Node.js application + +You can create an application from the [Console](https://console.clever-cloud.com) or through [Clever Tools](https://github.com/CleverCloud/clever-tools/): + +```bash +npm i -g clever-tools +clever login + +cd myStaticApp +clever create -t node +``` + +To deploy on Clever Cloud, your local folder needs to be a git repository (if not, `git init`) linked to an application. If you already have an application on Clever Cloud and want to link it to the current local folder: + +```bash +clever link your_app_name_or_ID +``` + +### Environment variables + +Next, configure the application with a medium build instance. The host instance is XS, enough for a simple website. As Clever Cloud uses industry standards, you only need to define a few variables: + +```bash +clever scale --build-flavor M +clever scale --flavor XS + +clever env set CC_PRE_BUILD_HOOK "npm run build" +clever env set CC_RUN_COMMAND "node .output/server/index.mjs" +``` + +### Push your code + +Once you complete these steps, commit your content to the local repository and deploy it: + +```bash +git add . +git commit -m "First deploy" +clever deploy +clever open +``` + +You can display your website's URL or add a custom domain to it (you'll need to configure DNS): + +```bash +clever domain +clever domain add your.website.tld +``` + +## Learn more + +{{< cards >}} + {{< card link="/developers/doc/applications/nodejs" title="Deploy a Node.js application" subtitle="Learn more on deploying a Node.js application" icon="node" >}} + {{< card link="/developers/doc/applications/static" title="Deploy a Static application" subtitle="Learn more on deploying a Static application" icon="static" >}} + {{< card link="https://nuxt.com/docs" title="Learn Nuxt" subtitle="How to write and organize your content" icon="nuxt" >}} +{{< /cards >}} diff --git a/content/guides/otree.md b/content/guides/otree.md new file mode 100644 index 000000000..48ef9a942 --- /dev/null +++ b/content/guides/otree.md @@ -0,0 +1,96 @@ +--- +title: oTree +description: The powerful framework for multiplayer strategy games and complex surveys +tags: +- guides +keywords: +- otree +- python +type: "docs" +comments: false +draft: false +--- + +oTree is a powerful framework for multiplayer strategy games and complex surveys. It is built on Python and Django, and it allows you to create interactive web applications with ease. + +If you need an example source code, init a new project (you’ll need `git`, `python` and `pip`, `pipx` or `uv`): + +```bash +pip install otree +otree startproject oTreeExample + +# You can also use pipx +pipx otree startproject oTreeExample + +# Or uv +uvx otree startproject oTreeExample +``` + +## Create a Python application + +You can create an application in the [Console](https://console.clever-cloud.com) or through [Clever Tools](https://github.com/CleverCloud/clever-tools/): + +```bash +# Install Clever Tools if you don't have it yet +# You can also use your package manager: https://www.clever.cloud/developers/doc/cli/install/ +npm i -g clever-tools +clever login + +cd oTreeExample +clever create -t python +``` + +To deploy on Clever Cloud, your local folder need to be a git repository (if not, `git init`). + +## Deploy oTree + +oTree uses de SQLite database by default, but we recommend using a PostgreSQL database for production deployments. You can create it and link it to your Python application in the [Console](https://console.clever-cloud.com) or through [Clever Tools](https://github.com/CleverCloud/clever-tools/): + +```bash +# Here we use a XXS Small plan, but you can choose the one fitting your needs +clever addon create postgresql-addon --plan xxs_sml --link oTreeExample oTreePg +``` + +### Configure the application + +Set the following environment variables: + +```bash +clever env set OTREE_PRODUCTION "1" + +# Ask a password for the admin interface (user: admin), use STUDY for no login +clever env set OTREE_AUTH_LEVEL "DEMO" + +# Automatically generate a random password, or use your own +clever env set OTREE_ADMIN_PASSWORD $(openssl rand -base64 32) + +# We use a script to bind $DATABASE_URL to the PostgreSQL add-on before starting the server +clever env set clever env set CC_RUN_COMMAND "bash run.sh" +``` + +In the `run.sh`, you'll only need: + +```bash +#!/bin/bash + +export DATABASE_URL=${POSTGRESQL_ADDON_URI} +otree prodserver 9000 +``` + +### Deploy the Python application + +Now you can deploy your application: + +```bash +git add . +git commit -m "First deploy" +clever deploy +``` + +You can display your website’s URL or add a custom domain to it (you’ll need to configure DNS): + +```bash +clever domain +clever domain add your.website.tld +``` + diff --git a/content/guides/pgpool.md b/content/guides/pgpool.md new file mode 100644 index 000000000..a46cd13b9 --- /dev/null +++ b/content/guides/pgpool.md @@ -0,0 +1,390 @@ +--- +type: docs +title: Pgpool-II +description: How to configure and use Pgpool-II for PostgreSQL add-ons +tags: +- addons +keywords: +- balancing +- connection +- limit +- load +- pgpool +- pool +- postgres +- proxy +- sql +aliases: +- /deploy/addon/postgresql/pgpool +- /doc/deploy/addon/postgresql/pgpool +- /pgpool +--- + +Pgpool-II is a tool available on application instances to help manage your connection pool and load balancing of your PostgreSQL add-ons. + +{{< callout type="warning" >}} +Pgpool-II is not available on Docker instances. If you want to use Pgpool-II, you can add it and configure it in your Dockerfile. +{{< /callout >}} + +## What's Pgpool-II? + +{{% content "pgpool" %}} + +## Why use Pgpool-II? + +**Connection pooling**: Pgpool-II maintains established connections to the PostgreSQL servers, and reuses them whenever a new connection with the same properties (user name, database, protocol version, and other connection parameters if any) comes in. It reduces the connection overhead, and improves the system's overall throughput. + +**Load balancing**: If a database is replicated (because running in either replication mode or native replication mode), performing a `SELECT` query on any server will return the same result. Pgpool-II takes advantage of the replication feature in order to reduce the load on each PostgreSQL server. It does that by distributing `SELECT` queries among available servers, improving the system's overall throughput. In an ideal scenario, read performance could improve proportionally to the number of PostgreSQL servers. Load balancing works best in a scenario where a lot of users execute many read-only queries at the same time. + +**Automated fail over**: If one of the database servers goes down or becomes unreachable, Pgpool-II will detach it and will continue operations by using the rest of the database servers. Some sophisticated features that help for automated failovers including timeouts and retries. + +**Limiting Exceeding Connections**: PostgreSQL puts a limit on the amount of concurrent connections, so that new connections are rejected when this number is reached. Raising this maximum number of connections, however, increases resource consumption and has a negative impact on overall system performance. Pgpool-II also limits the number of concurrent connections, but extra connections will be queued instead of returning an error immediately. Or you can configure it to return an error when the connection limit is exceeded (`4.1` or later). + +**In Memory Query Cache**: In memory query cache allows to save a `SELECT` statement with its result. If an identical `SELECT` comes in, Pgpool-II returns the value from cache. Since neither SQL parsing nor access to PostgreSQL are involved, using in memory cache is extremely fast. On the other hand, it might be slower than the normal path in some cases, because it adds some overhead of storing cache data. + +The various features are available in the [official Pgpool documentation](https://www.pgpool.net/docs/latest/en/html/index.html). + +{{< callout type="info" >}} +PostreSQL add-ons only support the **Streaming** mode, which is the most used and recommended mode for Pgpool-II. If you need other modes or features that aren't supported on Clever Cloud, contact [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice). +{{< /callout >}} + +## How to configure Pgpool-II + +### Generate direct variables for PG + +Go to the "Add-on dashboard" tab of your PostgreSQL add-ons and click on the "Generate direct hostname and port" button. + +### Enable Pgpool-II + +In order to configure Pgpool-II, the first thing to do is to link your PostgreSQL add-on. To do that, you can go to the `Service Dependencies` page of your application +and select your PostgreSQL add-on. + +Once linked, you can enable the Pgpool-II feature by defining the following environment variable: `CC_ENABLE_PGPOOL=true`. +If you ever need to stop using Pgpool-II, you can remove this variable or set it to `false`. + +Your application will use a Unix Domain Socket to connect to Pgpool-II. Unix domain sockets are faster than TCP sockets because there is no handshake and the connection is made locally on the same machine. A special environment variable will be injected to your environment variables: `CC_PGPOOL_SOCKET_PATH`. This variable contains the path to the Unix Domain Socket you have to connect to. See [Usage](#usage) below for some examples on how to use it. + +The available Pgpool-II variables and their descriptions are available on our [environment variables reference page](/developers/doc/reference/reference-environment-variables/). + +### Concurrent session and pool size + +You can use the `CC_PGPOOL_NUM_INIT_CHILDREN` and `CC_PGPOOL_MAX_POOL` environment variables to set the number of **concurrent sessions** and the number of **connection pool caches per connection**. + +Let's take an example where you have 3 PostgreSQL servers, and the `CC_PGPOOL_NUM_INIT_CHILDREN` variable configured with a value of **32**. + +On startup, Pgpool-II will start **32** processes, one process per connection. The `CC_PGPOOL_MAX_POOL` variable is used to configure the number of cached connections per connection (process). This option is mostly used when you have different credentials for the same PostgreSQL server (database, user…). But in the case of **Streaming** mode on Clever Cloud, you have access to only one database, and the credentials are the same on all add-ons with binary replication. You should not need to change the default value of this variable (**1** by default). + +An example of the `SHOW POOL_POOLS;` command with `CC_PGPOOL_NUM_INIT_CHILDREN=32` and `CC_PGPOOL_MAX_POOL=1`: + +```shell +psql -U u1mgltc2ezvkylo2cjno -d bjzfhkl5qcdhdqatyqjk + +bjzfhkl5qc**********=> show pool_pools; + pool_pid | start_time | pool_id | backend_id | database | username | create_time | pool_backendpid | +----------+---------------------+---------+------------+----------------------+----------------------+---------------------+-----------------+ + 3526 | 2021-06-02 15:22:12 | 0 | 0 | bjzfhkl5qcdhdqatyqjk | u1mgltc2ezvkylo2cjno | 2021-06-02 15:22:35 | 1520665 | + 3526 | 2021-06-02 15:22:12 | 0 | 1 | bjzfhkl5qcdhdqatyqjk | u1mgltc2ezvkylo2cjno | 2021-06-02 15:22:35 | 1665071 | + 3526 | 2021-06-02 15:22:12 | 0 | 2 | bjzfhkl5qcdhdqatyqjk | u1mgltc2ezvkylo2cjno | 2021-06-02 15:22:35 | 531483 | + 3527 | 2021-06-02 15:22:12 | 0 | 0 | | | | 0 | + 3527 | 2021-06-02 15:22:12 | 0 | 1 | | | | 0 | + 3527 | 2021-06-02 15:22:12 | 0 | 2 | | | | 0 | + 3528 | 2021-06-02 15:22:12 | 0 | 0 | | | | 0 | + 3528 | 2021-06-02 15:22:12 | 0 | 1 | | | | 0 | + 3528 | 2021-06-02 15:22:12 | 0 | 2 | | | | 0 | + ... | ... | . | . | | | | . | +``` + +We can see the 32 available processes (**3526**, **3527**, **3528...**), and active connections for process **3526**, with an open connection for each PostgreSQL server (**1520665**, **1665071** and **531483**). + +If a process remains inactive for more than **300** seconds, it will be deleted and a new process will take its place. This value can be configured with the `CC_PGPOOL_CHILD_LIFE_TIME` variable. This is a measure to prevent memory leaks and other unexpected errors in Pgpool-II children. + +Cached connections for each process do not have a default expiration time, but you can set one if needed with the `CC_PGPOOL_CONNECTION_LIFE_TIME` variable. + +It's also possible to specify the lifetime of a Pgpool-II child process (`CC_PGPOOL_CHILD_MAX_CONNECTIONS`) and the time in seconds to disconnect a client if it remains inactive since the last request (`CC_PGPOOL_CLIENT_IDLE_LIMIT`). + +### Replication and load balancing + +Use Pgpool-II to distribute the load and separate **WRITE** and **READ** queries between your PostgreSQL servers. + +When using the **Streaming** mode, it's not Pgpool-II that manages the replication of your databases. Clever Cloud engineers must manually set up the replication on the PostgreSQL side, otherwise known as **binary**, **Hot Standby** or **Streaming** replication. To schedule this procedure, you can contact [Clever Cloud Support](https://console.clever-cloud.com/ticket-center-choice) or make a request via our [sales form](https://www.clever-cloud.com/en/contact-sales). + +Once replication is in place, you can use the `CC_PGPOOL_FOLLOWERS` environment variable to add the followers to your Pgpool-II configuration. This variable is in **JSON** format, and must contain the **host**, **port** and **weight** of each follower. + +{{< callout type="info" >}} +For the `HOST` and `PORT`, you must use the values of the `POSTGRESQL_ADDON_DIRECT_HOST` and `POSTGRESQL_ADDON_DIRECT_PORT` variables. +{{< /callout >}} + +An example of the `CC_PGPOOL_FOLLOWERS` variable with two followers: + +```json{linenos=table} +[ + { + "hostname": "", + "port": "", + "weight": "1" + }, + { + "hostname": "", + "port": "", + "weight": "1" + } +] +``` + +The weight is used to specify the load balance ratio of the backends, you can also configure the weight of the leader with the `CC_PGPOOL_LEADER_WEIGHT` variable. + +{{< callout type="info" >}} +You can set a higher value for followers to avoid overloading the leader with `SELECT` queries that could be made on followers. +{{< /callout >}} + +Many other **load balancing** options are configurable with environment variables. You can refer to our [environment variables reference page](/developers/doc/reference/reference-environment-variables/) and the [official Pgpool-II documentation](https://www.pgpool.net/docs/latest/en/html/runtime-config-load-balancing.html) for more information. + +### Health check + +Pgpool-II periodically connects to the configured PostgreSQL backends to detect any error on the servers or networks. If an error is detected, Pgpool-II performs failover or degeneration depending on the configurations. + +The health check is not activated by default, but you can activate it with the `CC_PGPOOL_HEALTH_CHECK_PERIOD` variable. + +Many other health check options are configurable with environment variables, such as: + +- `CC_PGPOOL_HEALTH_CHECK_TIMEOUT`: Specifies the timeout in seconds to give up connecting to the backend PostgreSQL if the TCP connect does not succeed within this time. +- `CC_PGPOOL_HEALTH_CHECK_MAX_RETRIES`: Specifies the maximum number of retries before giving up and initiating failover when health check fails. +- `CC_PGPOOL_HEALTH_CHECK_RETRY_DELAY`: Specifies the amount of time (in seconds) to sleep before retrying after a failed health check retries. +- `CC_PGPOOL_CONNECT_TIMEOUT`: Specifies the amount of time in milliseconds before giving up connecting to backend using `connect()` system call. + +You can consult the [official Pgpool-II documentation](https://www.pgpool.net/docs/latest/en/html/runtime-config-health-check.html) to get more information about the **health check**. + +### In memory cache + +In memory cache saves the pair of `SELECT` statement and its result. If the same `SELECT` comes in, Pgpool-II returns the value from cache. This feature can be activated with the `CC_PGPOOL_MEMORY_CACHE_ENABLED=on` variable. + +Many other in memory cache options are configurable with environment variables, such as: + +- `CC_PGPOOL_MEMQCACHE_TOTAL_SIZE`: Specifies the shared memory cache size in bytes. +- `CC_PGPOOL_MEMQCACHE_MAX_NUM_CACHE`: Specifies the number of cache entries. This is used to define the size of cache management space. +- `CC_PGPOOL_MEMQCACHE_CACHE_BLOCK_SIZE`: Specifies the cache block size. +- `CC_PGPOOL_MEMQCACHE_EXPIRE`: Specifies the life time of query cache in seconds. +- `CC_PGPOOL_MEMQCACHE_AUTO_CACHE_INVALIDATION`: Automatically deletes the cache related to the updated tables. +- `CC_PGPOOL_MEMQCACHE_MAXCACHE`: Specifies the maximum size in bytes of the `SELECT` query result to be cached. +- `CC_PGPOOL_CACHE_SAFE_MEMQCACHE_TABLE_LIST`: Specifies a comma-separated list of table names whose `SELECT` results should be cached by Pgpool-II. +- `CC_PGPOOL_CACHE_UNSAFE_MEMQCACHE_TABLE_LIST`: Specifies a comma-separated list of table names whose `SELECT` results should NOT be cached by Pgpool-II. + +You can consult the [official Pgpool-II documentation](https://www.pgpool.net/docs/latest/en/html/runtime-in-memory-query-cache.html#GUC-MEMQCACHE-AUTO-CACHE-INVALIDATION) to get more information about the **in memory cache**. + +### Scalability + +When the scalability of your application is enabled, you may need to tweak the `CC_PGPOOL_NUM_INIT_CHILDREN` value. This is what we are going to see here. + +Auto scalability will add or remove instances following your needs. This means that you may have multiple instances running at the same time for a certain period of time. +If your application restarts, you will have `your current instance number * 2` instances running in parallel while the deployment finishes and the old instances are stopped. +A new deployment **starts** new instances alongside the old ones. + +This means that have up to `maximum scalability * 2` instances can run at the same time. And if all of your instances open the maximum connections they are allowed to, +it means there will be up to `maximum scalability * 2 * CC_PGPOOL_NUM_INIT_CHILDREN` connections at the same time. We will call this result `MaxCon`. + +{{< callout type="warning" >}} +Each PostgreSQL add-on has a connection limit which varies following the plan you are using. You must be sure that `MaxCon` doesn't exceed your plan's max connections. If it does, you might have issues connecting to the remote PostgreSQL add-on. You have to adjust `CC_PGPOOL_NUM_INIT_CHILDREN` to a number that makes sense for your scalability parameters. +{{< /callout >}} + +#### Example + +Let's say that I'm hosting a simple PHP application on `1 XS` instance, with a scalability that can go up to `4 M` instances. And I'm using the PostgreSQL `S Small Space` plan +which has a connection limit of `125`. + +Now my application receives a lot of traffic and scales up to `4 M` instances. But at the same time, I also need to deploy a hot fix. This means that `4 new M` instances will be started, alongside the already existing `4 M` instances. I need to make sure that `MaxCon` doesn't go above `125`. + +Here is the summary: + +- 8 instances: 4 currently running, 4 currently deploying my hot fix +- 125 max connections: the maximum number of connections of my PostgreSQL add-on's plan +- 5 other connections: I want to be able to use PG Studio or any CLI tool at the same time, in case I need it + +`CC_PGPOOL_NUM_INIT_CHILDREN = ( (125 - 5) / 8 ) = 15`. If I set `CC_PGPOOL_NUM_INIT_CHILDREN` to `15`, each instance should have enough connections to query the database without errors. And it also leaves me some spare connections (`5`) available if anything goes wrong and I need to connect to my database using a CLI tool or PG Studio. + +## Tips / debug + +### Connecting to Pgpool-II + +Connect via [ssh](/developers/doc/administrate/ssh-clever-tools/) to your application and use the [psql](https://docs.postgresql.fr/10/app-psql.html) command. + +```bash +ssh -t ssh@sshgateway-clevercloud-customers.services.clever-cloud.com +``` + +Then, launch the `psql` command with : + +```bash +psql +``` + +### Showing configured nodes + +You can use the [`SHOW POOL_NODES;`](https://www.pgpool.net/docs/latest/en/html/sql-show-pool-nodes.html) command. + +```shell +bjzfhkl5qc**********=> SHOW POOL_NODES; + node_id | hostname | port | status | lb_weight | role | select_cnt | load_balance_node | +---------+-----------------------------------------------------------+------+--------+-----------+---------+------------+-------------------+ + 0 | bjzfhkl5qc**********-postgresql.services.clever-cloud.com | 57** | up | 0.333333 | primary | 0 | false | + 1 | b3diajq7iy**********-postgresql.services.clever-cloud.com | 57** | up | 0.333333 | standby | 2 | false | + 2 | bmtwtemn40**********-postgresql.services.clever-cloud.com | 57** | up | 0.333333 | standby | 1 | true | +``` + +### Watching Pgpool-II processes + +You can use the [`SHOW POOL_PROCESSES;`](https://www.pgpool.net/docs/latest/en/html/sql-show-pool-processes.html) command to see processes waiting for connections and processing a connection. + +```shell +bjzfhkl5qc**********=> SHOW POOL_PROCESSES; + pool_pid | start_time | database | username | create_time | pool_counter +----------+---------------------+----------------------+----------------------+---------------------+-------------- + 21554 | 2021-06-03 11:28:36 | bjzfhkl5qc********** | u5dh6v2ymn********** | 2021-06-03 11:28:48 | 1 + 11409 | 2021-06-02 19:54:53 | | | | + 11410 | 2021-06-02 19:54:53 | | | | + 21566 | 2021-06-03 11:29:20 | | | | +``` + +### Listing managed pools + +You can use the [`SHOW POOL_POOLS;`](https://www.pgpool.net/docs/latest/en/html/sql-show-pool-pools.html) command to see the list of pools managed by Pgpool-II. + +```shell +bjzfhkl5qc**********=> SHOW POOL_POOLS; + pool_pid | start_time | pool_id | backend_id | database | username | create_time | pool_backendpid | +----------+---------------------+---------+------------+----------------------+----------------------+---------------------+-----------------+ + 21554 | 2021-06-03 11:28:36 | 0 | 0 | bjzfhkl5qc********** | u5dh6v2ymn********** | 2021-06-03 11:28:48 | 1549123 | + 21554 | 2021-06-03 11:28:36 | 0 | 1 | bjzfhkl5qc********** | u5dh6v2ymn********** | 2021-06-03 11:28:48 | 1695967 | + 21554 | 2021-06-03 11:28:36 | 0 | 2 | bjzfhkl5qc********** | u5dh6v2ymn********** | 2021-06-03 11:28:48 | 562378 | + 11409 | 2021-06-02 19:54:53 | 0 | 0 | | | | 0 | + 11409 | 2021-06-02 19:54:53 | 0 | 1 | | | | 0 | + 11409 | 2021-06-02 19:54:53 | 0 | 2 | | | | 0 | + 11410 | 2021-06-02 19:54:53 | 0 | 0 | | | | 0 | + 11410 | 2021-06-02 19:54:53 | 0 | 1 | | | | 0 | + 11410 | 2021-06-02 19:54:53 | 0 | 2 | | | | 0 | + 21566 | 2021-06-03 11:29:20 | 0 | 0 | | | | 0 | + 21566 | 2021-06-03 11:29:20 | 0 | 1 | | | | 0 | + 21566 | 2021-06-03 11:29:20 | 0 | 2 | | | | 0 | +``` + +### Statistics of SQL commands + +You can use the [`SHOW POOL_BACKEND_STATS;`](https://www.pgpool.net/docs/latest/en/html/sql-show-pool-backend-stats.html) command to see the statistics of SQL commands. + +```shell +bjzfhkl5qc**********=> SHOW POOL_BACKEND_STATS; + node_id | hostname | port | status | role | select_cnt | insert_cnt | update_cnt | delete_cnt | +---------+-----------------------------------------------------------+------+--------+---------+------------+------------+------------+------------+ + 0 | bjzfhkl5qc**********-postgresql.services.clever-cloud.com | 57** | up | primary | 0 | 0 | 0 | 1 | + 1 | b3diajq7iy**********-postgresql.services.clever-cloud.com | 57** | up | standby | 2 | 0 | 0 | 0 | + 2 | bmtwtemn40**********-postgresql.services.clever-cloud.com | 57** | up | standby | 1 | 0 | 0 | 0 | +``` + +### Using the PCP command + +The [PCP tool](https://www.pgpool.net/docs/latest/en/html/pcp-commands.html) is pre-configured and available on your application. + +```bash +pcp_pool_status -h /tmp -U pcp -w +``` + +### Managing nodes + +Attach or detach a given node to Pgpool-II; + +```bash +pcp_pool_status -h /tmp -U pcp -w -n 0 +pcp_pool_status -h /tmp -U pcp -w -n 0 +``` + +### Statistical data + +Display the statistical data of the health check on the given node ID + +```bash +pcp_pool_status -h /tmp -U pcp -w -n 0 -v +Node Id : 0 +Host Name : bjzfhkl5qc**********-postgresql.services.clever-cloud.com +Port : 57** +Status : up +Role : primary +Last Status Change : 2021-06-02 19:54:53 +Total Count : 0 +Success Count : 0 +Fail Count : 0 +Skip Count : 0 +Retry Count : 0 +Average Retry Count : 0.000000 +Max Retry Count : 0 +Max Health Check Duration : 0 +Minimum Health Check Duration : 0 +Average Health Check Duration : 0.000000 +Last Health Check : +Last Successful Health Check : +Last Skip Health Check : +Last Failed Health Check : +``` + +You can find all PCP commands in the [official Pgpool-II documentation](https://www.pgpool.net/docs/latest/en/html/pcp-commands.html). + +## Usage + +{{< callout type="info" >}} +Please note that to connect to Pgpool-II, the default port **5432** must be used. So if you already have a different port set in your code, you have to change it or simply remove the port from the connection information. +{{< /callout >}} + +### PHP using PDO + +Using [PDO](https://www.php.net/manual/fr/ref.pdo-pgsql.connection.php), you have to use the `unix_socket` option in your DSN: + +```php{linenos=table} +getMessage(); +} +?> +``` + +### WordPress + +For WordPress, you can change the `DB_HOST` variable in your `wp-config.php`: + +```php{linenos=table} +// To connect using a socket, the syntax is: `localhost:/path/to/socket` +define( 'DB_HOST', "localhost:" . getenv("CC_PGPOOL_SOCKET_PATH") ); +``` + +### Node.js + +On Node.js, using the `pg` npm package: + +```javascript{linenos=table} +const { Client } = require('pg'); +client = new Client({ + // This variable is injected during the deployment + host: process.env["CC_PGPOOL_SOCKET_PATH"], + // Get the database name from the environment + database: process.env["POSTGRESQL_ADDON_DB"], + // Get the database user from the environment + user: process.env["POSTGRESQL_ADDON_USER"], + // Get the database password from the environment + password: process.env["POSTGRESQL_ADDON_PASSWORD"], +}); + +client.connect(); +``` diff --git a/content/guides/play-framework-1.md b/content/guides/play-framework-1.md new file mode 100644 index 000000000..1828dc5a6 --- /dev/null +++ b/content/guides/play-framework-1.md @@ -0,0 +1,79 @@ +--- +type: docs +title: Play Framework 1.x Scala +description: Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller (MVC) architectural pattern +tags: +- deploy +keywords: +- scala +- play +aliases: +- /doc/applications/java/play-framework-1 +- /doc/deploy/application/java/by-framework/play-framework-1 +- /doc/deploy/application/scala/tutorials/play-framework-1 +- /doc/java/play-framework-1 +- /doc/play-framework +--- + +## Overview + +Clever Cloud supports Play 1.x applications natively. The present guide explains how to set up your application to run on Clever Cloud. + +{{% content "create-application" %}} + + {{% content "set-env-vars" %}} + +## Configure your Scala + Play! 1 application + +### Select Play! 1.x version + +Clever Cloud supports Play! **1.2**, **1.3**, **1.4**, **1.5**. You can select the Play! version for your application by setting the `PLAY1_VERSION` [environment variable](#setting-up-environment-variables-on-clever-cloud) (or by putting it in a file named `clevercloud/play1_version`). + +The `PLAY1_VERSION` environment variable can contain one of the following values: + +* `1.2` or `12` for **Play! 1.2**. +* `1.3` or `12` for **Play! 1.3**. +* `1.4` or `14` for **Play! 1.4**. +* `1.5` or `15` for **Play! 1.5**. + +### Play! configuration with application.conf + +By default, your application will run on Clever Cloud with the option `--%clevercloud`. +It means that you can define special keys in your `application.conf` file that will be used only on Clever Cloud. + +You can for example: + +* set production mode so the files are compiled at startup time and the errors are logged in a file: + + ```bash + %clevercloud.application.mode=prod + ``` + +* set up a mysql database (using environment variables) + + ```bash + %clevercloud.db.url="jdbc:mysql://"${MYSQL_ADDON_HOST}"/"${MYSQL_ADDON_DB} + %clevercloud.db.driver=com.mysql.jdbc.Driver + %clevercloud.db.user=${MYSQL_ADDON_USER} + %clevercloud.db.pass=${MYSQL_ADDON_PASSWORD} + ``` + +More information on [playframework.com](https://www.playframework.com). + +### HTTPS support + +HTTPS is handled by Clever Cloud ahead of your application, your application retrieves the traffic in plain http. To be able to use `request.secure`, you have to add `XForwardedSupport=all` in `application.conf`. + + {{% content "new-relic" %}} + + {{% content "env-injection" %}} + +To access the environment variables from your code, you need to add `my.option=${MY_VARIABLE}` in your `application.conf` file, and then use the configuration item `my.option` in your application. e.g `%clevercloud.db.url="jdbc:mysql://"${MYSQL_ADDON_HOST}"/"${MYSQL_ADDON_DB}` + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/guides/play-framework-2.md b/content/guides/play-framework-2.md new file mode 100644 index 000000000..36f73d8b7 --- /dev/null +++ b/content/guides/play-framework-2.md @@ -0,0 +1,139 @@ +--- +type: docs +title: Play Framework 2 Scala +description: Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller (MVC) architectural pattern +tags: +- deploy +keywords: +- scala +- play +aliases: +- /doc/applications/java/play-framework-2 +- /doc/deploy/application/java/by-framework/play-framework-2 +- /doc/deploy/application/scala/tutorials/play-framework-2 +- /doc/java/play-framework-2 +- /doc/scala/play-framework-2 +- /java/play-framework-2 +- /scala/play-framework-2 +--- + +## Overview + +Clever Cloud supports Play! 2 applications natively. The following guide explains how to set up your application to run on Clever Cloud. + +{{% content "create-application" %}} + + {{% content "set-env-vars" %}} + +## Configure your Scala + Play! 2 application + +### Mandatory configuration + +* Starting from **Play 2.4**, your application needs **Java 8** to run. Please read [select java version](/developers/doc/applications/java/java-war/#available-java-versions "Select Java version") for more information. + +Play! 2 applications use sbt. Please have a look at [deploy Scala apps](/developers/doc/applications/scala) for a complete documentation on sbt deployment options. + +### Generate application secret + +To deploy a Play! application you have to set a secret in your `conf/application.conf` the environment variable name depends on your Play2! version: + +* 2.6.x: `play.http.secret.key=${?APPLICATION_SECRET}`, to generate secret use `sbt playGenerateSecret`; +* 2.4.x -> 2.5.x: `play.crypto.secret=${?APPLICATION_SECRET}` -> `sbt playGenerateSecret`; +* 2.3.x: `application.secret=${?APPLICATION_SECRET}` -> `sbt play-generate-secret`. + +Then, in your Clever Cloud application define `APPLICATION_SECRET` [environment variable](#setting-up-environment-variables-on-clever-cloud) with the generated value. + +### Custom config file + +If you don't want to use the default `conf/application.conf` configuration file, you can use the `SBT_DEPLOY_GOAL` [environment variable](#setting-up-environment-variables-on-clever-cloud) `SBT_DEPLOY_GOAL=-Dconfig.resource=clevercloud.conf` + +### HTTPS support + +HTTPS is handled by Clever Cloud ahead of your application, your application retrieves the traffic in plain http. + +If you want to redirect HTTP traffic to HTTPS, please have a look at [How to Redirect to HTTPS With Play +2.4](https://www.clever-cloud.com/blog/engineering/2015/12/01/redirect-to-https-in-play/). + +#### HTTP support with Play! 2.x < 2.4 + +To be able to use `request.secure`, you have to add `trustxforwarded=true` in `application.conf`. + +### Multi-module project + +If you have a single repository with multiple modules, then you can specify which module to run with `CC_SBT_TARGET_DIR` [environment variable](#setting-up-environment-variables-on-clever-cloud). + +For instance, if your Sbt project contains a `shared` and `play` module and you want to execute the `play` module, then add +`CC_SBT_TARGET_DIR=play` environment variable. + + {{% content "new-relic" %}} + + {{% content "env-injection" %}} + +To access the environment variables from your code, you need to add `my.option=${MY_VARIABLE}` in your `application.conf` file, and then use the configuration item `my.option` in your application. e.g `%clevercloud.db.url="jdbc:mysql://"${MYSQL_ADDON_HOST}"/"${MYSQL_ADDON_DB}`. +You can also use the `System.getenv("MY_VARIABLE")` method. Be aware that it can return null. + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +## Known problems with Play! 2 + +### sbt-plugin unresolved dependency error + +If your project fails with the error `sbt.ResolveException: unresolved dependency: play#sbt-plugin;2.0: not found` this is because some versions of Play2 try to retrieve a nonexistent version of "sbt-plugin" which is required by the framework. +You have two options to fix this problem: + +* You can set the "play.version" environment variable in the `/clevercloud/sbt.json` file. For example, for Play 2.0.4: + +``` javascript +{ + "deploy": { + "goal": "-Dplay.version=2.0.4" + } +} +``` + +* You can modify `plugins.sbt` in the project folder of your app like the following: + +``` scala +// Comment to get more information during initialization +logLevel := Level.Warn + +// The Typesafe repository +resolvers += "Typesafe repository" at "https://repo.typesafe.com/typesafe/releases/" + +// Use the Play sbt plugin for Play projects +addSbtPlugin("play" % "sbt-plugin" % "2.0.4") // The important part of the configuration +``` + +Both alternatives effectively fulfill the task at hand; you are free to select the one that best suits your preference. + +More info on [playframework.com](https://www.playframework.com). + +### Bad root server path error + +The error occurs when we cannot find a bin to execute your project. + +### Failed to acquire connection: Too many connections + +You may run into this error during deployments: + +``` scala +[error] c.j.b.h.AbstractConnectionHook - Failed to acquire connection to jdbc:
Sleeping for 1000ms and trying again. Attempts left: 10. Exception: null.Message:FATAL: too many connections for role "" +``` + +By default, Play! opens a pool of 10 connections, which is more than the connection limit allowed by DEV database plans. During a no-downtime deployment, there are at least two instances of the application running in parallel, so it's 20 connections. + +To avoid connection exhaustion, you should limit your pool at half the number of available connections (if you have horizontal scaling enabled, adjust accordingly). + +``` scala +# conf/application.conf + +db.default.partitionCount=2 +db.default.maxConnectionsPerPartition=5 +db.default.minConnectionsPerPartition=5 +``` + +{{% content "more-config" %}} + +{{% content "url_healthcheck" %}} diff --git a/content/guides/proxysql.md b/content/guides/proxysql.md new file mode 100644 index 000000000..f2581446d --- /dev/null +++ b/content/guides/proxysql.md @@ -0,0 +1,202 @@ +--- +type: docs +title: ProxySQL +description: How to configure and use ProxySQL for MySQL add-ons +tags: +- addons +keywords: +- proxysql +- proxy +- sql +- mysql +- connection +- limit +- pool +aliases: +- /deploy/addon/mysql/proxysql +- /doc/deploy/addon/mysql/proxysql +- /proxysql +--- + +ProxySQL is a tool available on applications instances to help you manage your connection pool towards your MySQL add-on. + +{{< callout type="warning" >}} +ProxySQL is not available on Docker instances. If you want to use ProxySQL, you can add it and configure it in +your Dockerfile. +{{< /callout >}} + +## What is ProxySQL + +{{% content "proxysql" %}} + +## When do I need ProxySQL + +You might need ProxySQL if your application can't manage a connection pool. This is usually the case with PHP applications or any other application that do not +have a connection pooling policy in place. + +{{< callout type="info" >}} +A connection pool will cache your database connections and keep them open for future requests. +The connections can then be reused if needed or closed if they weren't used after a certain time. +{{< /callout >}} + +By using connection pooling from ProxySQL to your MySQL add-on, you make sure that a certain number of connections stay open to your add-on, leading to faster requests. + +For example, on a PHP application, each HTTP request will spawn a new Apache worker and your PHP code will be executed. If your application does an SQL request, a new TCP connection will be open to the remote MySQL add-on. Once your SQL request is done, the TCP connection will be closed and a new one will need to be opened on the next SQL query. + +Each new connection means a new [TCP handshake](https://en.wikipedia.org/wiki/Transmission_Control_Protocol#Connection_establishment) which takes some time. +If you use TLS to secure the connection, then there is an [aditionnal handshake](https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_handshake). All of this, multiplied +by the number of connections you make to your add-on can greatly increase your application's response time. + +One of the goals of ProxySQL is to keep the connections open to your MySQL add-on. Your application can then connect to the local proxy +using a [Unix Domain Socket](https://en.wikipedia.org/wiki/Unix_domain_socket) for each SQL request it has to do. +Unix Domain Sockets are faster than TCP sockets because there are no handshakes and the connection is made locally on the same machine. + +When ProxySQL receives a new SQL query, it will open a new connection to the remote MySQL add-on if no connection is currently available. But if one is available, it will be reused and the query should take less time. The connection will then be kept for further use. + +## How to configure ProxySQL + +In order to configure ProxySQL, the first thing to do is to link your MySQL add-on. To do that, you can go to the `Service Dependencies` page of your application +and select your MySQL add-on. + +Once linked, you can enable the ProxySQL feature by defining the following environment variable: `CC_ENABLE_MYSQL_PROXYSQL=true`. +If you ever need to stop using ProxySQL, you can remove this variable or set it to `false`. + +You can customize some other parameters: + +- `CC_MYSQL_PROXYSQL_MAX_CONNECTIONS`: Integer. This is the maximum connections ProxySQL will open to your add-on. See the [Scalability](#scalability) part +below for more explanations on how to customize this variable. Defaults to `10`. +- `CC_MYSQL_PROXYSQL_USE_TLS`: Boolean (`true` or `false`). This controls whether ProxySQL should open a secure connection using `TLS` to your add-on. Defaults to `true`. + +To connect to ProxySQL, a special environment variable will be injected to your environment variables: `CC_MYSQL_PROXYSQL_SOCKET_PATH`. This variable contains the +path to the Unix Domain Socket you have to connect. See [Usages](#usages) below for some example on how to use it. + +### Scalability + +When the scalability of your application is enabled, you may need to tweak the `CC_MYSQL_PROXYSQL_MAX_CONNECTIONS` value. This is what we are going to see here. + +Auto scalability will add or remove instances following your needs. This means that you may have multiple instances running at the same time for a certain period of time. +If your application restarts, you will have `your current instance number * 2` instances running in parallel while the deployment finishes and the old instances are stopped. +A new deployment **starts** new instances with the old ones alongside them. + +This means that have up to `maximum scalability * 2` instances can run at the same time. And if all of your instances open the maximum connections they are allowed to, +it means there will be up to `maximum scalability * 2 * CC_MYSQL_PROXYSQL_MAX_CONNECTIONS` connections at the same time. We will call this result `MaxCon`. + +Each MySQL add-on has a connection limit which varies following the plan you are using. You must be sure that `MaxCon` doesn't exceed your plan's max connections. If it does, you might have issues connecting to the remote MySQL add-on. You have to adjust `CC_MYSQL_PROXYSQL_MAX_CONNECTIONS` to a number that makes sense for your scalability parameters. + +#### Example + +Let's say that I'm hosting a simple PHP application on `1 XS` instance, with a scalability that can go up to `4 M` instances. And I'm using the MySQL `S Small Space` plan +which has a connection limit of `125`. + +Now my application receives a lot of traffic and scales up to `4 M` instances. But at the same time, I also need to deploy a hot fix. This means that `4 new M` instances will be started, alongside the already existing `4 M` instances. I need to make sure that `MaxCon` doesn't go above `125`. + +Here is the summary: + +- 8 instances: 4 currently running, 4 currently deploying my hot fix +- 125 max connections: the maximum number of connections of my MySQL add-on's plan +- 5 other connections: I want to be able to use PHPMyAdmin or any CLI tool at the same time, in case I need it + +`CC_MYSQL_PROXYSQL_MAX_CONNECTIONS = ( (125 - 5) / 8 ) = 15`. If I set `CC_MYSQL_PROXYSQL_MAX_CONNECTIONS` to `15`, each instance should have enough connections to query the database without errors. And it also let you some spare connections (`5`) available if anything goes wrong and you need to connect to your database using a CLI tool or PHPMyAdmin. + +## Usages + +### PHP using PDO + +Using [PDO](https://www.php.net/manual/en/ref.pdo-mysql.connection.php), you have to use the `unix_socket` option in your DSN: + +```php +getMessage(), (int)$e->getCode()); +} +``` + +### Wordpress + +For Wordpress, you can change the `DB_HOST` variable in your `wp-config.php`: + +```php +// To connect using a socket, the syntax is: `localhost:/path/to/socket` +define( 'DB_HOST', "localhost:" . getenv("CC_MYSQL_PROXYSQL_SOCKET_PATH") ); +``` + +### Symfony + +For symfony, you will need to edit its [configuration](https://symfony.com/doc/current/configuration.html#configuration-environments). + +A working example would be: + +```yaml +dbal: + unix_socket: '%env(CC_MYSQL_PROXYSQL_SOCKET_PATH)%' + url: 'mysql://%env(MYSQL_ADDON_USER)%:%env(MYSQL_ADDON_PASSWORD)%@localhost/%env(MYSQL_ADDON_DB)%?serverVersion=%env(MYSQL_ADDON_VERSION)%' +``` + +### Node.js + +On Node.js, using the `mysql` npm package, you have to set the `socketPath` property: + +```javascript +const mysql = require('mysql'); +const connection = mysql.createConnection({ + // Get ProxySQL unix domain socket path from the environment + socketPath : process.env["CC_MYSQL_PROXYSQL_SOCKET_PATH"], + // Get the database user from the environment + user : process.env["MYSQL_ADDON_USER"], + // Get the database password from the environment + password : process.env["MYSQL_ADDON_PASSWORD"], + // Get the database name from the environment + database : process.env["MYSQL_ADDON_DB"] +}); +connection.connect(function(err) { + if (err) { + console.error('error connecting: ' + err.stack); + return; + } + + console.log('connected as id ' + connection.threadId); +}); +``` + +## Metrics + +ProxySQL exposes some metrics using Prometheus. Some of those metrics are ingested in our metrics system. You can then explore them +in the [Web Console](/developers/doc/metrics#display-metrics). + +Here is the list of currently tracked metrics, those may evolve over time: + +- `prometheus.proxysql_access_denied_max_connections_total` +- `prometheus.proxysql_access_denied_max_user_connections_total` +- `prometheus.proxysql_access_denied_wrong_password_total` +- `prometheus.proxysql_client_connections_connected` +- `prometheus.proxysql_client_connections_hostgroup_locked` +- `prometheus.proxysql_client_connections_non_idle` +- `prometheus.proxysql_client_connections_total` +- `prometheus.proxysql_connpool_conns` +- `prometheus.proxysql_connpool_conns_latency_us` +- `prometheus.proxysql_connpool_conns_queries_total` +- `prometheus.proxysql_connpool_conns_status` +- `prometheus.proxysql_connpool_conns_total` +- `prometheus.proxysql_connpool_data_bytes_total` +- `prometheus.proxysql_connpool_get_conn_failure_total` +- `prometheus.proxysql_connpool_get_conn_success_immediate_total` +- `prometheus.proxysql_connpool_get_conn_success_latency_awareness_total` +- `prometheus.proxysql_connpool_get_conn_success_total` +- `prometheus.proxysql_connpool_memory_bytes` +- `prometheus.proxysql_mysql_error_total` +- `prometheus.proxysql_server_connections_connected` + +Those metrics might help you follow how effective your connection pool is or have more insights into your client's requests. + +Keep in mind that each instance will have those metrics because each instance has its own ProxySQL service. diff --git a/content/guides/python-django-sample.md b/content/guides/python-django-sample.md new file mode 100644 index 000000000..40114bb85 --- /dev/null +++ b/content/guides/python-django-sample.md @@ -0,0 +1,77 @@ +--- +type: docs +title: Django +description: The goal of this article is to show you how to deploy a Django application on Clever Cloud +tags: +- deploy +keywords: +- python +- django +aliases: +- /doc/deploy/application/python/tutorials/python-django-sample +- /doc/python/python-django-sample +- /guides/django +- /python/python-django-sample +- /python-django-sample +--- + +## Overview + +The goal of this article is to show you how to deploy a Django application on Clever Cloud. +The application is a very basic one. More information about the application in the[GitHub repo](https://github.com/CleverCloud/django-example). + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +## Configure your Django application + +Note : + +- Select at least a `nano` instance (`pico` doesn't have enough resources for a Django project). +- Connect your Django project to Postgresql version 12+ if you're using django 4.2+ (postgresql 11 is deprecated since this version). + +### My application does not exists already + +If you want to test easily a Django deployment on Clever Cloud, just clone the [GitHub repo](https://github.com/CleverCloud/django-example) and go the next section. + +### My application already exists + +{{< callout type="warning" >}} + Do not forget to add the `CC_PYTHON_MODULE` environment variable in any Python project so that we get your required modules. +{{< /callout >}} + +### Fine tuning the application + +You can find a lot more configuration options such as choosing python version and more on our dedicated [Python documentation](/developers/doc/applications/python). + + {{% content "new-relic" %}} + +### Manage.py tasks + +Clever Cloud supports execution of multiple [manage.py](https://docs.djangoproject.com/fr/3.2/ref/django-admin/) tasks. + +The tasks are launched after the dependencies from `requirements.txt` have been installed, and before the web server starts. + +You can declare the `manage.py` tasks with the environment variable `CC_PYTHON_MANAGE_TASKS="migrate"`. + +Values must be separated by a comma: + +```bash +CC_PYTHON_MANAGE_TASKS="migrate, assets:precompile" +``` + + {{% content "env-injection" %}} + +To access environment variables from your code, just get them from the environment with: + +```python +import os +os.getenv("MY_VARIABLE") +``` + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} diff --git a/content/guides/ruby-on-rails.md b/content/guides/ruby-on-rails.md new file mode 100644 index 000000000..d910930ce --- /dev/null +++ b/content/guides/ruby-on-rails.md @@ -0,0 +1,41 @@ +--- +type: docs +title: Ruby on Rails +description: Ruby on Rails is an open source web application framework which runs on the Ruby programming language +tags: +- deploy +keywords: +- ruby +- rails +aliases: +- /deploy/application/ruby/by-framework/ruby-on-rails +- /doc/deploy/application/ruby/ruby-on-rails +- /ruby-on-rails +--- + +## Overview + +Ruby on Rails is an open source web application framework which runs on the Ruby programming language. It is a full-stack framework: it allows creating pages and applications that gather information from the web server, talk to or query the database, and render templates out of the box. As a result, Rails features a routing system that is independent of the web server. + +Clever Cloud allows you to deploy any Ruby on Rails application. This page will explain you how to set up your application to run it on our service. +You do not need to change a lot in your application, the *requirements* will help you configure your applications with some mandatory files to add, and properties to setup. + +- [An example of Ruby on Rails application on Clever Cloud](https://github.com/CleverCloudDemos/demo-rubyonrails-pg-rest) + +{{% content "create-application" %}} + + {{% content "set-env-vars" %}} + +{{% content "ruby" %}} + + {{% content "new-relic" %}} + + {{% content "env-injection" %}} + +To access environment variables from your code, just get them from the environment with `ENV["MY_VARIABLE"]`. + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} diff --git a/content/guides/ruby-rack-app-tutorial.md b/content/guides/ruby-rack-app-tutorial.md new file mode 100644 index 000000000..93d2b2339 --- /dev/null +++ b/content/guides/ruby-rack-app-tutorial.md @@ -0,0 +1,121 @@ +--- +type: docs +title: Ruby Rack full tutorial +description: How to write a hello world web application using Rack and deploy it on Clever Cloud +tags: +- deploy +keywords: +- ruby +- rack +aliases: +- /doc/deploy/application/ruby/tutorials/ruby-rack-app-tutorial +--- + +## Overview Introduction + +Currently, Clever Cloud supports Rack-based applications. +Created in 2007, Rack has become the de-facto standard for ruby web applications and is used in many frameworks such as Ruby on Rails. + +## Configure your Rack based application + +### Mandatory configuration + +To follow this tutorial, you will need: + +* Ruby >= 1.9.2 (w/ Rubygems) +* Bundler (`gem install bundler` and you're good to go!) +* Your preferred editor +* Git (for the deploy part) + +{{< callout type="info">}} +To manage your gems and ruby versions, we recommend [rbenv](https://github.com/sstephenson/rbenv). If you use a system-wide installation of ruby, You will have to use `sudo` with the `gem` and `bundle` commands, or use arguments that will make gem and bundle install the gem in directories you have write-permissions in. +{{< /callout >}} + +### My application does not exists already + +#### Create a Ruby + Rake application locally + +You can deploy a demo application by following these instructions: + +```bash +mkdir helloworld-rack +cd helloworld-rack +touch hello.rb config.ru Gemfile ## or gems.rb +``` + +Inside `hello.rb` put the following: + +```ruby +class HelloWorld + def call(env) + [200, {"Content-Type" => "text/plain"}, ["Hello world!"]] + end +end +``` + +Inside the `config.ru` (That is, the main Rack entry-point) put: + +```ruby +require './hello' +run HelloWorld.new +``` + +The `gems.rb` or `Gemfile` file will contain our dependencies: + +```ruby +source 'https://rubygems.org' + +gem 'rack', '~>1.5.1' + + +gem "puma", "~> 6.4" +``` + +We don't need any more dependencies. The `gems.rb` or `Gemfile` is mandatory to deploy +on Clever Cloud. + +Do not forget to init an empty git repository with `$ git init` + +#### Test your application locally + +To test your application, just fetch the dependencies using bundler: + +```shell +$ bundle install +Fetching gem metadata from https://rubygems.org/.......... +Resolving dependencies... +Using rack (1.5.2) +Using puma (6.4.2) +Using bundler (1.3.5) +Your bundle is complete! +Use `bundle show [gemname]` to see where a bundled gem is installed. +``` + +And start your application: + +```bash +$ bundle exec rackup +[2013-09-16 17:35:26] INFO WEBrick 1.3.1 +[2013-09-16 17:35:26] INFO ruby 2.0.0 (2013-06-27) [x86_64-linux] +[2013-09-16 17:35:26] INFO WEBrick::HTTPServer#start: pid=5656 port=9292 +``` + +You can now test with your browser at `http://localhost:9292`. + +You can now read [My application already exists](#my-application-already-exists) + +### My application already exists + +{{% content "create-application" %}} + + {{% content "set-env-vars" %}} + + {{% content "env-injection" %}} + +To access environment variables from your code, just get them from the environment with `ENV["MY_VARIABLE"]`. + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} diff --git a/content/guides/ruby-rack.md b/content/guides/ruby-rack.md new file mode 100644 index 000000000..9482cf9b1 --- /dev/null +++ b/content/guides/ruby-rack.md @@ -0,0 +1,49 @@ +--- +type: docs +title: Ruby Rack +description: How to deploy a web application using Rack on Clever Cloud +tags: +- deploy +keywords: +- ruby +- rack +aliases: +- /doc/deploy/application/ruby/tutorials/ruby-rack-app +- /doc/ruby/ruby-rack +--- + +## Overview + +Currently, Clever Cloud supports Rack-based applications. +Created in 2007, Rack has become the de-facto standard for ruby web applications and is used in many frameworks such as Ruby on Rails. + +{{% content "create-application" %}} + + {{% content "set-env-vars" %}} + +## Configure your Ruby and Rake application + +### Mandatory configuration + +Be sure that: + +* Bundler is installed locally (`gem install bundler`) +* you have a `config.ru` file +* Git (for the deploy part) +* you have a `gems.rb` or `Gemfile` containing your dependencies + +### Tutorial and sample app + +- [An hello world tutorial of a Ruby and Rack application](/developers/guides/ruby-rack-app-tutorial) + + {{% content "new-relic" %}} + + {{% content "env-injection" %}} + +To access environment variables from your code, just get them from the environment with `ENV["MY_VARIABLE"]`. + + {{% content "deploy-git" %}} + + {{% content "link-addon" %}} + +{{% content "more-config" %}} diff --git a/content/guides/tutorial-drupal.md b/content/guides/tutorial-drupal.md new file mode 100644 index 000000000..d2f990f7b --- /dev/null +++ b/content/guides/tutorial-drupal.md @@ -0,0 +1,93 @@ +--- +type: docs +title: Drupal +description: This article shows you how to deploy a Drupal-based website on Clever Cloud +tags: +- deploy +keywords: +- php +- drupal +aliases: +- /doc/deploy/application/php/tutorials/tutorial-drupal +- /doc/php/tutorial-drupal +- /php/tutorial-drupal +--- + +## Overview + +[Drupal](https://new.drupal.org) applications almost work out of the box on Clever Cloud, you just have a few adjustments to make. + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +{{% content "new-relic" %}} + +{{% content "env-injection" %}} + +{{% content "link-addon" %}} + +## Configure your database + +Make sure you have created a MySQL database add-on in the Clever Cloud console, and that it's linked to your application. When it's done, you will be able to access all of your add-on environment variables from the application. You can use them as `DATABASE_URL=$MYSQL_ADDON_URI`. + + {{% content "deploy-git" %}} + +### Git specific Drupal instructions + +We at this point assume you have downloaded the source files of drupal from [drupal.org](https://new.drupal.org/download) and already have linked your MySQL add-on. + +* Open `.gitignore` file and delete `sites/*/settings*.php` line +* Copy the file `sites/default/default.settings.php` to `sites/default/settings.php` +* Open `sites/default/settings.php` and line 213, replace + +```php{linenos=table} +$databases = array(); +``` + +by + +```php{linenos=table} + $databases = array ( + 'default' => + array ( + 'default' => + array ( + 'database' => getenv('MYSQL_ADDON_DB'), + 'username' => getenv('MYSQL_ADDON_USER'), + 'password' => getenv('MYSQL_ADDON_PASSWORD'), + 'host' => getenv('MYSQL_ADDON_HOST'), + 'port' => getenv('MYSQL_ADDON_PORT'), + 'driver' => 'mysql', + 'prefix' => '', + ), + ), + ); +``` + +* Replace the line `$settings['hash_salt'] = ''` (`$drupal_hash_salt` for Drupal 7) with `$settings['hash_salt'] = getenv('DRUPAL_SALT')`. You can generate salts with [this link](https://www.passwordtool.hu/). Add a new `DRUPAL_SALT` [environment variable](/developers/doc/applications/php#configure-your-php-application) to the application with the salt you have generated. +* As mentioned in this [article](/developers/doc/addons/fs-bucket), with Git deployments, files that are uploaded by users must be +persisted in a File System Bucket. In order to do so, [add a File Bucket](/developers/doc/addons/fs-bucket) via the console. +* At the root of your application, create a `clevercloud/buckets.json` file (create a `clevercloud` +folder in which you create a `buckets.json` file). +* Copy the `bucket.json` content from the FS bucket addon dashboard (make sure to edit the `folder` field): + +```javascript{linenos=table} +[ + { + "bucket_host": "-fsbucket.services.clever-cloud.com", + "folder": "/sites/default/files" + } +] +``` + +* Send these Drupal files via Git. +* When finished, get the url that you can find in the *domains* panel in the left sidebar. Then open the following link: + +`https://yourapplication.cleverapps.io/install.php` + +Do not forget the **/install.php** page otherwise installation will not happen. + +{{% content "deploy-ftp" %}} + +{{% content "more-config" %}} diff --git a/content/guides/tutorial-laravel.md b/content/guides/tutorial-laravel.md new file mode 100644 index 000000000..f292d0f3e --- /dev/null +++ b/content/guides/tutorial-laravel.md @@ -0,0 +1,177 @@ +--- +type: docs +title: Laravel +description: This article shows you how to deploy a Laravel application on Clever Cloud +tags: +- deploy +keywords: +- php +- laravel +aliases: +- /doc/deploy/application/php/tutorials/tutorial-laravel +- /doc/php/tutorial-laravel +- /tutorial-laravel +--- + +{{< hextra/hero-subtitle >}} + Laravel is a PHP web application framework with expressive, elegant syntax. This guide walks you through the minimal requirements to successfully deploy your app. +{{< /hextra/hero-subtitle >}} + +## Overview + +Deploying a Laravel application on Clever Cloud requires: + +- [PHP application](/developers/doc/applications/php) +- A database add-on: ([MySQL](/developers/doc/addons/mysql) or [PostgreSQL](/developers/doc/addons/postgresql)) +- An [FS Bucket](/developers/doc/addons/fs-bucket) for persistent storage. + +The following sections explain how to set up each instance step by step: + +## Configure your Laravel Application + +{{% steps %}} + +### Create a PHP application + +From the Clever Cloud Console, create a new PHP application and choose your deployment method: [git, GitHub or FTP](/developers/doc/quickstart/#choose-how-to-deploy). + +### Add `DocumentRoot` variable + +Add the following environment variable in the Console: `CC_WEBROOT="/public"`. + +Or set it with the Clever Cloud CLI: + + ```bash + clever env set CC_WEBROOT /public + ``` + +### Add your application key variable + +Make sure `config/app.php` contains the following line: + +```php + 'key' => env('APP_KEY'), +``` + +Locally, run `php artisan key:generate`. It should output something like `base64:tQbFzxwUfOfKKqNlbjXuduwaUFDQUy+NL8DBfgb3o3s=`. + +Copy this value and add an environment variable named `APP_KEY`, with this value. + +### Configure monolog to use syslog + +Make sure `config/logging.php` contains the following line: + +```php + 'default' => env('LOG_CHANNEL', 'stack'), +``` + +In your environment variables, add the `LOG_CHANNEL=syslog` environment variable. This allows you to read your application logs directly from the console or the [CLI](/developers/doc/cli) tool. + +### Optional: configure the front-end build + +If you need to build your frontend assets (eg. JavaScript or CSS files), you can either add it as a step in your composer file, or you can add a post build hook with the `CC_PRE_RUN_HOOK` environment variable. + +For example: `CC_PRE_RUN_HOOK="npm install && npm run prod"`. + +This step is necessary if you are building your Laravel application with [Blade](https://laravel.com/docs/10.x/blade), for example. + +### Connect a database + +Edit `config/database.php` to set the correct environment variable names. For example, replace `DB_xxx` by `MYSQL_ADDON_xxx` for a MySQL database. + +For instance for MySQL: + +```php{linenos=table} + // … + 'connections' => [ + // … + 'mysql' => [ + 'driver' => 'mysql', + 'host' => env('MYSQL_ADDON_HOST', '127.0.0.1'), + 'port' => env('MYSQL_ADDON_PORT', '3306'), + 'database' => env('MYSQL_ADDON_DB', 'forge'), + 'username' => env('MYSQL_ADDON_USER', 'forge'), + 'password' => env('MYSQL_ADDON_PASSWORD', ''), + 'unix_socket' => env('DB_SOCKET', ''), + 'charset' => 'utf8mb4', + 'collation' => 'utf8mb4_unicode_ci', + 'prefix' => '', + 'strict' => true, + 'engine' => null, + ], + // … + ] + // … +``` + +Create a database add-on (either MySQL or PostgresSQL) and link it to your application. If your add-on already exists, use the **Service Dependencies > Link add-ons** dropdown menu in your application options, to select the name of the add-on you want to link and use the add button to finish the process. + +### Optional: automatically run migrations upon deployment + +If you want to have database migrations automatically run during each deployment, add this hook instruction to the application's environment variables `CC_POST_BUILD_HOOK=php artisan migrate --force` + +### Configure storage + +Create a FS Bucket add-on and link it to your application. Note its host (you can see it from the add-on configuration panel, or in the environment variables exported by the add-on). It looks like `bucket-01234567-0123-0123-0123-012345678987-fsbucket.services.clever-cloud.com`. + +Create a new environment variable called `CC_FS_BUCKET` and set `/storage/app:` as its value. + +{{% /steps %}} + +## Optional Further Configuration + +### Task scheduling + +If your app uses [task scheduling](https://laravel.com/docs/scheduling), you need to configure a cron to run the scheduling process: + +1. Create a `clevercloud/cron.json` file in your project, containing: + +```json +[ + "* * * * * $ROOT/clevercloud/cron.sh" +] +``` + +This installs a cron to run `clevercloud/cron.sh` every minute. + +2. Create a `clevercloud/cron.sh` file in your project (with execute permissions), containing: + +```bash +#!/bin/bash -l +set -euo pipefail + +pushd "$APP_HOME" +php artisan schedule:run >> /dev/null 2>&1 +``` + +Note: the PHP CLI process uses a `memory_limit` configuration value that depends on the instance's size (you can verify this value by connecting to your app using SSH and running `php -i`). + +If one of your scheduled tasks needs to allocate more memory than this limit, the `php artisan schedule:run` process is going to silently crash. + +To allow it to use more memory, you can call [`ini_set()`](https://www.php.net/manual/en/function.ini-set) inside a `php_sapi_name() === 'cli'` condition from an early hook to the app's lifecycle (like the `AppServiceProvider`). + +See [this Gist](https://gist.github.com/dsferruzza/e57dd3db957efe7a649325868f0024a4) for an example implementation. + +### Trusted Proxy + +To ensure Laravel correctly handles HTTP requests when using the Clever Cloud HTTP reverse proxy (Sōzu), add the following code to the `config/trustedproxy.php` file: + +```php{linenos=table} + env('CC_REVERSE_PROXY_IPS'), +]; +``` + +This environment variable exists in any Clever Cloud instance. This configuration specifies to trust Clever Cloud proxies, allowing Laravel to seamlessly recognize HTTP requests in the presence of a proxyhugo server. + +{{% content "more-config" %}} + +## Go Further + +{{< cards >}} + {{< card link="/developers/doc/metrics/new-relic" title="Monitor your App with New Relic" subtitle="Connect your application to New Relic." icon="new-relic" >}} + {{< card link="/developers/doc/addons/fs-bucket" title="FS Bucket" subtitle="External File System for your apps" icon="fsbucket" >}} + {{< card link="/developers/doc/develop/build-hooks" title="Deployment hooks" subtitle="Learn about custom commands used in this guide." icon="rocket-launch" >}} + {{< card link="https://laravel.com/docs/10.x/deployment" title="Laravel Documentation" subtitle="Read Laravel documentation on deployments." icon="laravel" >}} +{{< /cards >}} diff --git a/content/guides/tutorial-symfony.md b/content/guides/tutorial-symfony.md new file mode 100644 index 000000000..5517e10f0 --- /dev/null +++ b/content/guides/tutorial-symfony.md @@ -0,0 +1,144 @@ +--- +type: docs +title: Symfony +description: This article shows you how to deploy a Symfony application on Clever Cloud +tags: +- deploy +keywords: +- php +- symfony +aliases: +- /doc/applications/php/symfony +- /doc/deploy/application/php/tutorials/tutorial-symfony +- /doc/php/tutorial-symfony +- /php/tutorial-symfony +- /tutorial-symfony +--- + +## Overview + +This tutorial assumes that your application is based on Symfony >= 3.4 and Symfony Flex. +Symfony applications almost work out of the box on Clever Cloud, you just have a few adjustments to make. + +{{% content "create-application" %}} + +{{% content "set-env-vars" %}} + +## Configure your Symfony application + +### Configure `DocumentRoot` + +Add a new [environment variable](#setting-up-environment-variables-on-clever-cloud) called `CC_WEBROOT` and set `/public` as its value `CC_WEBROOT=/public`. + +### Configure your application secret + +`APP_SECRET` [environment variable](#setting-up-environment-variables-on-clever-cloud) is required to generate CSRF tokens. By default for [symfony/framework-bundle](https://github.com/symfony/framework-bundle) generates one when it's installed via [Symfony Flex](https://github.com/symfony/flex). +If you do not use Flex, make sure to change your `APP_SECRET`. The default value is `ThisTokenIsNotSoSecretChangeIt`, **change it**. + +### Configure the Symfony environment + +If you're using [`.env` file](https://symfony.com/blog/improvements-to-the-handling-of-env-files-for-all-symfony-versions) in your application, please don't commit productions credentials in this file or in a `.env.production` file. They are not meant to be committed alongside your applications. Clever Cloud allows you to inject environment in your app, so you can dynamically link databases and have separate environments with the same code base. + +From the console, you can edit the application's environment variables. Click on "expert mode", you'll be able to directly paste the contents of the `.env` file. + +From the CLI, it's even simpler: `clever env import < .env`. + +You will also need to set the environment variable `APP_ENV` to one of: + +- dev +- test +- prod + +You can anyway add your environment with any of the methods mentioned in [Setting up environment variables on Clever Cloud](#setting-up-environment-variables-on-clever-cloud). + +### Configure monolog to get application logs + +For your application logs to be collected and available in the console and CLI, you need to configure monolog to use its `error_log` output. +That does not mean that it will only output error level logs, you can set it to use any level, here is an example with the info level (and above): + +```yaml{filename="config_prod.yml"} +monolog: + handlers: + filter_for_errors: + type: fingers_crossed + action_level: error + handler: error_log_handler + excluded_404s: + # regex: exclude all 404 errors from the logs + - ^/ + + error_log_handler: + type: error_log + level: info +``` + +### Configure Symfony to work behind Clever Cloud reverse proxies + +You can use the `CC_REVERSE_PROXY_IPS` [environment variable](#setting-up-environment-variables-on-clever-cloud) that contains a list of trusted IP addresses, separated by commas. + +```shell{filename=".env"} +TRUSTED_PROXIES=127.0.0.1,${CC_REVERSE_PROXY_IPS} +``` + +```yaml{filename="config/packages/framework.yaml"} +framework: + # … + trusted_proxies: '%env(TRUSTED_PROXIES)%' +``` + +For more information on configuring symfony behind a reverse proxy, you can read the [official documentation](https://symfony.com/doc/current/deployment/proxies.html). + +### Apache 404 error after deployment + +If everything looks fine and you still get 404 errors, remember that CleverCloud works with an Apache server, so you'll need an htaccess in the `/public` directory. +Symfony got your back on this: just run `composer require symfony/apache-pack`. See [the official documentation of Symfony](https://symfony.com/doc/current/setup/web_server_configuration.html) for more information. + + {{% content "new-relic" %}} + + {{% content "env-injection" %}} + + {{% content "link-addon" %}} + +## Configure your database + +Make sure you have created a database add-on in the Clever Cloud console, and that it's linked to your application. When it's done, you will be able to access all of your add-on [environment variables](#setting-up-environment-variables-on-clever-cloud) from the application. + +Change the default `DATABASE_URL` environment variable used in your `config/packages/doctrine.yaml` to `_ADDON_URI` where `` depending on the database add-on you created (e.g. `MYSQL` for MySQL, `POSTGRESQL` for PostgreSQL or `MONGODB` for MongoDB) or be sure to use the environment variable in your production configuration file as explained in the [configuration documentation of Symfony](https://symfony.com/doc/current/configuration.html#configuration-environments). + +### Configure ProxySQL for MySQL + +To manage your connection pool towards your MySQL add-on, you can set-up a [ProxySQL](/developers/guides/proxysql). + +Once you have activated the ProxySQL (through the environment variable), a configuration example would be: + +```yaml{filename="doctrine.yaml"} +dbal: + unix_socket: '%env(CC_MYSQL_PROXYSQL_SOCKET_PATH)%' + url: 'mysql://%env(MYSQL_ADDON_USER)%:%env(MYSQL_ADDON_PASSWORD)%@localhost/%env(MYSQL_ADDON_DB)%?serverVersion=%env(MYSQL_ADDON_VERSION)%' +``` + +### Optional: run tasks after build step + +If you want to have database migrations automatically run during each deployment, or frontend assets which must be built, you can write all these commands in `clevercloud/post_build.sh` like this one: + +```shell{filename="clevercloud/post_build.sh"} +# Database migrations +./bin/console doctrine:migrations:migrate --no-interaction + +# Frontend build + yarn install && yarn run build +``` + +Make sure this file is executable: + +```shell +chmod +x clevercloud/post_build.sh +``` + +Then, add this to the application's environment variables `CC_POST_BUILD_HOOK=./clevercloud/post_build.sh`. + + {{% content "deploy-git" %}} + +{{% content "deploy-ftp" %}} + +{{% content "more-config" %}} diff --git a/content/guides/tutorial-wordpress.md b/content/guides/tutorial-wordpress.md new file mode 100644 index 000000000..74ac07ce9 --- /dev/null +++ b/content/guides/tutorial-wordpress.md @@ -0,0 +1,202 @@ +--- +type: docs +title: WordPress +description: This article shows you how to deploy a WordPress-based website on Clever Cloud +tags: +- deploy +keywords: +- php +- wordpress +aliases: +- /doc/deploy/application/php/tutorials/tutorial-wordpress +- /doc/php/tutorial-wordpress +- /php/tutorial-wordpress +- /tutorial-wordpress +- /wordpress +--- + +## Overview + +[WordPress](https://WordPress.org) applications almost work out of the box on Clever Cloud, you just have a few adjustments to make. + +First, you could check [our global PHP documention](/developers/doc/deploy/application/php/php-apps/). + +This tutorial is mainly concerning a Git deployment. However, you can deploy using a classic FTP PHP app. Choose "FTP" when you create a new PHP app. + +{{% content "create-application" %}} + + {{% content "set-env-vars" %}} + + {{% content "deploy-git" %}} + +{{% content "deploy-ftp" %}} + +## Configure your WordPress application + +### Configuration file + +Rename the file `wp-config-sample.php` to `wp-config.php`. All the PHP code for the configuration should be written in this file. + +### Configure your database + +Make sure you have created a MySQL database add-on in the Clever Cloud console, and that it's linked to your application. When it's done, you will be able to access all of your add-on [environment variables](#setting-up-environment-variables-on-clever-cloud) from the application. You can use them, in `wp-config.php`, as : + +```php +define( 'DB_NAME', getenv("MYSQL_ADDON_DB") ); +define( 'DB_USER', getenv("MYSQL_ADDON_USER") ); +define( 'DB_PASSWORD', getenv("MYSQL_ADDON_PASSWORD") ); +define( 'DB_HOST', getenv("MYSQL_ADDON_HOST").':'.getenv("MYSQL_ADDON_PORT") ); +``` + +{{< callout type="warning" >}} +**Make sure you use ** in `wp-config.php` the port the add-on dashboard provides. Use the `MYSQL_ADDON_PORT` environment variable for that. We **don't** use the default MySQL port. +{{< /callout >}} + +### SSL Configuration + +Since your website is behind a reverse proxy managed by Clever Cloud, you need to detect specific headers like **X_FORWARDED_PROTO** or **HTTP_X_FORWARDED_PROTO** to enable SSL. +To do so edit `wp-config.php` and add the following code above the last `require_once` call. + +```php{linenos=table} +if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] == 'https') { + $_SERVER['HTTPS'] = 'on'; +} elseif (isset($_SERVER['X_FORWARDED_PROTO']) && $_SERVER['X_FORWARDED_PROTO'] == 'https') { + $_SERVER['HTTPS'] = 'on'; +} +``` + +#### Using a CDN as Cloudflare with SSL (avoid infinite loops) + +As with SSL configuration, you need to detect specific headers like **X_FORWARDED_PROTO** or **HTTP_X_FORWARDED_PROTO** to enable SSL. In this case, the chained proxies might concatenate those headers. As a result, headers values can look like +```php [HTTP_X_FORWARDED_PROTO] => https, https``` +The previous code snippet would not enable SSL on the Clever Cloud application, resulting in mixed content or infinite loop. + +In order to avoid this, you'll need to add the following code snippet to your `wp-config.php` file (it replaces the previous code snippet). Add the following code above the last `require_once` call or at the beginning of the `wp-config.php` file. + +To do so edit `wp-config.php` and add the following code above the last `require_once` call. + +```php +function check_proto_set_ssl($forwarded_protocols){ + $secure = 'off'; + if ( strstr($forwarded_protocols , ",") ) { + $previous = null; + foreach ( explode(",", $forwarded_protocols) as $value ) { + if ( $previous ) { + trim($value) == $previous && trim($value) == 'https' ? $secure = 'on' : $secure = 'off'; + } + $previous = trim($value); + } + $_SERVER["HTTPS"] = $secure; + }else{ + $forwarded_protocols == 'https' ? $_SERVER["HTTPS"] = 'on' : $_SERVER["HTTPS"] = $secure = 'off'; + } +} + +if (isset($_SERVER['HTTP_X_FORWARDED_PROTO'])) { + check_proto_set_ssl($_SERVER['HTTP_X_FORWARDED_PROTO']); +} elseif (isset($_SERVER['X_FORWARDED_PROTO'])) { + check_proto_set_ssl($_SERVER['X_FORWARDED_PROTO']); +} +``` + +### Configure storage + +To store static files, you need to configure a FS Bucket. + +Create a FS Bucket add-on and link it to your application. Note its host (you can see it from the addon configuration panel, or in the environment variables exported by the addon). It looks like `bucket-01234567-0123-0123-0123-012345678987-fsbucket.services.clever-cloud.com`. + +To use the bucket in your wordpress app, there are 2 methods : + +#### Environment variables + +Create a new [environment variable](#setting-up-environment-variables-on-clever-cloud) called `CC_FS_BUCKET` and set `/:` as its value. + +If you need to have many associated buckets with your app, you need to create en new encironment variable, with a suffix : `CC_FS_BUCKET_1`, `CC_FS_BUCKET_2`… + +#### JSON + +{{< callout emoji="🧹" >}} +**This method is deprecated** +We strongly recommend that you use environment variables. + +If you want to switch from this method to the environment variables, you need to remove the `buckets.json` file. Otherwise, the environment variables will be ignored. +{{< /callout >}} + +At the root of your application, create a `clevercloud/buckets.json` file (create a `clevercloud` folder in which you create a `buckets.json` file). +Add the following lines in this file. Do not forget to replace `bucketId` by the bucketId displayed in the [information](/developers/doc/addons/fs-bucket) section of the FS Bucket add-on. + +```javascript + [ + { + "bucket" : "bucketId", + "folder" : "/" + } + ] +``` + +### Install a WordPress plugin with Git + +If you choose git deployment over FTP, the code of your plugins won't be tracked by git. This implies that you will not be able to install plugins from the administration panel and persist them between two deployments. + +To solve this problem, we recommend to install the plugin manually by copying the content of the plugin to the `/wp-content/plugins/` folder, add the new files to git and then deploy your application. + +The plugin will then be available in the **Extensions** section of your admin panel and you will be able to manage it as others WordPress plugins. +To uninstall the plugin, the procedure is the same as before except that you have to delete the folder corresponding to the plugin you want to delete. The extension will be automatically disabled, but we recommend you to delete it from you admin panel before removing the file, in order to clean your database and all files that the plugin could have created. + +## Optimise and speed-up your WordPress + +There are multiple ways to optimise your WordPress and speed-up its response time. +We provide different tools and software to help you in this task as [Varnish](/developers/doc/administrate/cache) for the HTTP cache, and [Redis](/developers/doc/addons/redis) for the object caching. + +### Performance plugins + +{{< callout type="warning" >}} +We recommend you to **not** use performance plugins like W3 Total Cache or JetPack as they are intended to be used on a shared hosting server. +We noticed performances problems when performance plugins are enabled and we recommend to use Varnish and Redis if you need performance optimisations on Clever Cloud. +{{< /callout >}} + +### HTTP Cache with Varnish + +Enabling [Varnish](/developers/doc/administrate/cache) for your application is very simple. All instances of PHP provide [Varnish](/developers/doc/administrate/cache), you just have to configure your application to use it. + +1. To use Varnish in your application, you have to create a `varnish.vcl` file in the `clevercloud` folder of your application. If this folder doesn't exist, create it in the **root** of your project. + +2. Copy [this code](https://raw.githubusercontent.com/CleverCloud/varnish-examples/master/wordpress.vcl) into the `varnish.vcl` file you just created. It'll configure Varnish to work with your WordPress. + +3. To properly purge the Varnish cache of your application when a post is created/updated, a comment is posted, … we recommend you to install the [Varnish HTTP Purge](https://WordPress.org/plugins/varnish-http-purge/) plugin to your WordPress. It'll purge the Varnish cache for you and give you the possibility to purge it manually. + +If you need to manually purge the Varnish cache, the plugin provides a **Purge Varnish cache** button on the top bar of your website. + +### Object cache with Redis + +[Redis](/developers/doc/addons/redis) is an [add-on](#linking-a-database-or-any-other-add-on-to-your-application) that offers you a good way to speed-up your application by caching some of the objects of your application, as the result of SQL queries of your application, improving the response time. + +To enable [Redis](/developers/doc/addons/redis) for your WordPress, you need to disable other Object Cache and Data Cache of your application (as those provided by *W3 Total Cache* for example). Make sure they aren't enabled to avoid conflicts and performance problems. + +1. [Create a Redis add-on](/developers/doc/addons/redis) for your application. + +2. Add the following lines to your `wp-config.php` file. Make sure they are **before** the `require_once(ABSPATH . 'wp-settings.php');` line, otherwise the Redis connexion will not work for your application and your application will return only white pages! + +```php +define('WP_CACHE_KEY_SALT', 'tvm_'); +define('WP_REDIS_CLIENT', 'pecl'); +define('WP_REDIS_HOST', getenv('REDIS_HOST')); +define('WP_REDIS_PORT', getenv('REDIS_PORT')); +define('WP_REDIS_PASSWORD', getenv('REDIS_PASSWORD')); +``` + +3. Download [this file](https://plugins.svn.WordPress.org/redis-cache/trunk/includes/object-cache.php) who manages the connexion with Redis and WordPress and moves it to your `/wp-content` folder. The file **must** be named `object-cache.php`. + +Redis should now work with your WordPress. + + {{% content "new-relic" %}} + +## Deploy WordPress the immutable way + +Discover a new way to deploy WordPress using Composer with Bedrock's boilerplate : [our tutorial on GitHub](https://github.com/CleverCloud/clever-wordpress) + + + + + +{{% content "more-config" %}} diff --git a/content/postmortem/2024-08-02.md b/content/postmortem/2024-08-02.md new file mode 100644 index 000000000..563a44d27 --- /dev/null +++ b/content/postmortem/2024-08-02.md @@ -0,0 +1,663 @@ +--- +title: '2024-08-02' +description: 'A minor release resulted in a cascade of errors that perturbed platform stability and customer service. How it went wrong,what we’ve learnt' +date: 2024-08-08T15:31:41+02:00 +draft: false +excludeSearch: true +type: docs +--- +{{< hextra/hero-subtitle >}} + A minor release resulted in a cascade of errors that perturbed platform stability and customer service. How it went wrong,what we’ve learnt +{{< /hextra/hero-subtitle >}} + +On Friday, August 2nd, 2024 Clever Cloud’s platform became unstable, leading to downtime of varying duration and scope, for many customers. The impact was both on the API itself, and on some services running as add-ons or runtimes. + +These events occurred because: + +* A planned minor maintenance of the Messaging component has locked the cluster causing an incident ([www.clevercloudstatus.com/incidents/880](https://www.clevercloudstatus.com/incidents/880)) between **2:00 PM CEST** and **2:29 PM CEST** +* As an indirect consequence, the infrastructure experienced I/O and memory pressure between **3:40 PM CEST** and **4:16 PM CEST** causing some hypervisors to crash. + +Impacts were observed for customers relying on the EU-FR-1 (PAR) region, and remote zones depending on the EU-FR-1 control plane (OVHcloud, Scaleway, and Oracle). Privates and on-premise zones weren’t impacted. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProductImpact
RuntimesCustomers with applications running on impacted hypervisors may have seen performance degradation. +Customers applications traffic served through impacted load balancers also may have suffered from traffic issues.
Runtimes deploymentDeployment API was unreachable during the incident, leading to new deployment or upscale/downscale operations not to succeed.
Databases (MySQL, PostgreSQL, Redis, MongoDB)Customers with databases running on impacted hypervisors may have seen performance degradation or even unavailability. No data has been lost during the incident.
Cluster services (Elastic, Couchbase, Cassandra, …) Depending on both infrastructure pressure and the running technology, some nodes may have survived the incident, hence the provided service may have been fulfilled. We know for sure, some clusters had issues during the incident, others didn’t.
VPN / IPSecMost of the VPN endpoints were unavailable during the incident.
Observability The service has been unavailable but no data has been lost.
+ +## Timeline + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TimelineComponentDescription
2024-08-02 10:06 CESTMessagingClever Cloud data team starts a minor rolling maintenance upgrade of the Apache Pulsar component to release 3.3.1. This maintenance also enables a new balancer algorithm for bundles placement optimization.
10:08 CESTMessagingMonitoring shows connection issues to the messaging platform.
10:09 CESTMessagingEngineers confirm connections issues to produce data into the event bus.
10:10 CESTMessagingMessaging issues impact agents on hypervisors, log forwarders from load balancers and deployments — Impact starts —
10:11 CESTMessagingMonitoring graphs show the backlog ramping up and no new producers / consumers to succeed. (backlog means consumption isn’t streamlined with production).
10:13 CESTMessagingMonitoring starts to show a recovery state - reads happening again - Cluster convergence.
10:18 CESTMessagingMonitoring shows no writes anymore. Backlogs are stalled and no reads from the event bus.
10:20 CESTMessagingThe cluster is considered defective.
10:58 CESTMessagingEngineering team understands that the new parameter is conflicting in a transparent rolling upgrade. They're rolling back the parameters.
11:10 CESTDeploymentsCustomers can no longer deploy their application
11:36 CESTMessagingMessaging Brokers fail to restart. A conflictual metadata blocks the reload. Engineering team shuts down client proxies to release brokers.
11:36 CESTMessagingMonitoring shows "Lookup request" queue is full on all brokers (50k pending requests).
11:46 CESTMessagingAn unassigned topic fails to load (unloaded state prevents it to be manipulated from admin commands, like deletion).
11:48 CESTDeploymentsEngineering team behind deployments looks for a countermeasure to overcome messaging issues.
11:50 CESTDeploymentsAs a workaround, they enable notification events to switch on RabbitMQ.
12:22 CESTMessagingAll brokers have been shut down. Incriminated topics are successfully loaded and deleted. All brokers are now being started progressively.
12:28 CESTMessagingAll brokers have been started.
12:30 CESTInfrastructureLots of hypervisors have their CPU load drastically increase. Almost all hypervisors of all regions are impacted. Some hypervisors are more impacted than others.
12:31 CESTDeploymentsThe Deployments workaround is running successfully. Deployments are ok in theory, but fails to find enough resources to consume the queues.
12:35 CESTDeploymentsLoad balancers can't sync with Deployments API due to Messaging issues. This leads to unsynced load balancers configuration for moving applications deployments (scale up/down, new deployments, etc.).
12:35 CESTInfrastructureMonitoring alerts "HV Agent has too many tasks" start to raise. From this point, multiple hypervisors may randomly kill VM management processes.
12:36 CESTLoad BalancersSome load balancers are among VM killed and watchdog monitoring components reload every impacted service exposed through the load Balancers.
12:38 CESTCore APIsThe main API components crashed due to out-of-memory (OOM) errors.
12:39 CESTInfrastructureWatchdog is being stopped to prevent it from reloading all failed components. Engineers prefer to understand what's happening and start components one by one.
12:42 CESTNetworkSome private networks are flapping, some services like the observability platform become unavailable for a couple of minutes.
12:47 CESTInfrastructureHypervisor (1) reboot (kernel panic - hung VM tasks on interacting with KVM API).
12:48 CESTInfrastructureHypervisors (3) reboot (kernel panic - hung VM tasks on interacting with KVM API or ext4 filesystem).
12:50 CESTObservabilityMetrics API ingestion is disabled to preserve the underlying storage cluster. Buffering ensures ingestion availability.
12:51 CESTInfrastructureHypervisor (1) reboot (kernel panic - hung VM tasks on writing to ext4 disks).
12:54 CESTMessagingMessaging proxies are restarted. Connections are recovering and production / consumption of messages is ok. — Messaging OK —
13:05 CESTLoad BalancersThe Clever Cloud API is down and the admin tools as well.
13:10 CESTCore APIsMain API starts to consume events from the workaround queue.
13:30 CESTInfrastructureClever Cloud engineers identify too many CPU load on hypervisors caused mostly by small VMs (pico/nano)
13:30 CESTObservabilityFew cluster critical nodes are not reachable, reporting "the database may have data loss and availability loss", it is in a locked state. Engineers decided to shut down the whole cluster for proper restart later.
13:35 CESTObservabilityA global maintenance is set on all monitoring instances on all regions to avoid them sending too many monitoring events and overloading orchestrator actions. No more monitoring actions are sent (upscale, downscale, unreachable, disk, etc.).
13:35 CESTInfrastructureClever Cloud engineers notice too many disk reads on hypervisors, mostly small VMs (pico/nano). They think it might be related to Vector not being able to push VMs logs to pulsar, triggering small VMs to SWAP
13:44 CESTCore APIsThe Clever Cloud API is reading and acknowledging events from deployments from 100k at 12:50 CEST to 8.5K
13:49 CESTCore APIsThe Clever Cloud API has finished processing deployment events.
13:50 CESTInfrastructureSome hypervisors (12) are flagged to drain some workload out
13:50 CESTLoad BalancersShutdown is performed on some load balancers to free CPU and memory usage as there are others instances that still need resources.
14:00 CESTCore APIsCore services are being recovered and deployments are being reloaded. This will synchronize back load balancers for customer's applications trying to reach their new deployments.
14:08 CESTCore APIsSome zombies VM are being cleaned to accelerate the recovery process.
14:38 CESTLoad BalancersWe have gathered information from load balancers configurations to verify the VM states of the back office admin interface.
14:39 CESTCore APIsCritical core services are OK. Deployments are being rolled out.
14:50 CESTCore APIsAdmin interface has been moderated instead of stopped by human error. Quickly fixed.
15:03 CESTLoad BalancersThe back office admin interface is up and running.
15:07 CESTDeploymentsOrchestrator instruction queues still have difficulties to be processed. We keep receiving a lot of Monitoring actions even while the monitoring instances are in maintenance mode.
15:40 CESTInfrastructureHypervisors have experienced reboots around 12:48 CEST. Recovery process is occurring and will take a couple of minutes.
15:45 CESTObservabilityWe clear the monitoring instance alert queue to drop monitoring events that were still queued to avoid flooding the orchestrator instructions.
15:56 CESTCore APIsSome private Wireguard networking meshes seem still experiencing network issues.
16:00 CESTDeploymentsWe observe that some ochestrator actions are taking multiple seconds (+30s in some cases), slowing down the orchestration operations.
16:05 CESTDeploymentsA RabbitMQ node is on an overloaded hypervisor and is thus overloaded too. It slows down the cluster used by orchestrator.
16:05 CESTInfrastructureInfrastructure engineers delivered new hypervisors on the EU-FR-1 region that were drained then parked for upgrade, to add capacity to help other overloaded hypervisors.
16:15 CESTDeploymentsA RabbitMQ node is removed from the cluster because the node is overloaded and disturbs the orchestration. orchestrator is now correctly working.
16:16 CESTCore APIsCustomer applications are being deployed to scale up deployments.
16:19 CESTLoad BalancersOne ADC has kernel panic and it is unable to boot.
16:19 CESTLoad BalancersAdmin ADCs are running and the configuration is synchronized. A rule is removed on load balancers to prevent customers from deploying through the console.
16:24 CESTCore APIsIn the meantime, we continue to identify noisy VMs that have been impacted by the Pulsar outage.
16:33 CESTObservabilityAttempt to restart the Metrics API - Wireguard mesh networking issue encountered due to stale conntrack.
17:05 CESTInfrastructurePreviously flagged HV are back to schedule Runtimes VM.
17:06 CESTLoad BalancersPreviously shut ADC are now up and running.
17:06 CESTLoad BalancersEvery regional L7LB has been rolling restarted.
17:07 CESTLoad BalancersBegin the rolling restart of every L4 load balancers.
17:14 CESTDeploymentsSome load balancer virtual machine are still unreachable, The HV agent is restarted and the load balancer as well.
17:28 CESTObservabilityThe FoundationDB cluster powering the Metrics API is now healthy.
17:30 CESTLoad BalancersEvery L4LB has been rolling restarted.
17:30 CESTLoad BalancersEvery dedicated L7LB has been rolling restarted.
17:32 CESTObservabilityMetrics API directories are started and warms up.
17:33 CESTLoad BalancersSome customers endpoints may be not responsive, engineering and support teams up to investigate.
17:49 CESTLoad BalancersThese endpoints are now back online.
18:00 CESTObservabilityCleanup of EU-FR-1 region Monitoring instance duplicate hosts.
18:13 CESTObservabilityMonitoring PAR6 AZ back in production and sending monitoring events.
18:19 CESTObservabilityMonitoring PAR7 AZ back in production and sending monitoring events.
18:20 CESTCore APIsAll deployments are now being rolled out. — Deployments ok —
18:22 CESTLoad BalancersAccess logs productions is ok, processing pipeline is starting.
18:24 CESTObservabilityMonitoring PAR8 AZ back in production and sending monitoring events.
18:30 CESTInfrastructureStill a few hundreds of VMs are consuming very high CPU rates and being cleaned.
18:30 CESTCustomersWe ensure premium customers not having applications without VMs instances.
18:35 CESTCore APIsWe estimate approximately 1h30 to have fully recovered all deployment of applications.
18:36 CESTInfrastructureAll Hypervisors have recovered to a nominal load
18:36 CESTObservabilityMaintenance is removed on Monitoring, we start receiving oncall alerts again.
18:39 CESTCustomersWe ensure non-premium customers not having applications without VMs instance.
18:40 CESTDeploymentsWe restart all HV agents on the infrastructure as it suspects communication errors between agents on hypervisors and control plane.
18:40 CESTCore APIsWe restart add-ons providers apis which seem to be unable to communicate with the control plane event bus.
18:53 CESTDeploymentsAll dangling virtual machines in stopping state have been destroyed and application are deploying.
19:05 CESTVPN - IPSecAll IPSec links should be back online.
20:45 CESTObservabilityMetrics API directories are ready to serve.
20:50 CESTObservabilityMetrics API queries are enabled.
20:50 CESTObservabilityTelemetry confirmed that we are processing access logs
20:51 CESTObservabilityMetrics API ingest is enabled with a ramp up QoS policy.
22:53 CESTObservabilityMetrics API ingestion policy is disabled, the cluster is fully functional. +
22:53 CESTAll impacts resolved — IMPACT END —
+ +## Analysis + +### Messaging Maintenance (Apache Pulsar) + +Apache Pulsar is used as the fundamental layer of messaging. This component has interesting multi-tenancy capabilities and supports very high cardinality of namespace/topics creation. It’s not exempt of bugs, and it regularly receives a fair amount of bug fixes. Minor releases are applied as a rolling upgrade basis. When it happens, topics are handed over from a broker to another. Since the architecture of Apache Pulsar has strong separation between the messaging layer and the storage layer, brokers are stateless and the topic handover is a seamless operation that doesn’t affect connected clients. They will receive a notice that the topic has moved to another broker, and connect to the new one. This is an expected behavior implemented by clients and constantly happening for broker load management, resizing, etc. In our topology, there are additional proxies between customers' clients and brokers, so only proxies are seeing this administrative rebalancing. + +In this minor maintenance, we opt in for an optimized balancer named `TransferShedder` instead of the native `OverloadShedder`. + +```shell +loadManagerClassName=org.apache.pulsar.broker.loadbalance.extensions.ExtensibleLoadManagerImpl +``` + +```shell +loadBalancerLoadSheddingStrategy=org.apache.pulsar.broker.loadbalance.extensions.scheduler.TransferShedder +``` + +Pulsar scalability is performed through the concept of bundles which are kind of scalability groups to perform administrative tasks. This change also implies moving from the modular bundle unloading strategy to the extensible one. These changes bring many improvements by removing storage on the metadata layer, and having a pre-assignation for the next broker when unloading a topic which shortens the switch from a broker to another. + +This new *extensible unload strategy* relies on non-persistent real time replication among brokers. Which means when a first broker is upgraded, it initializes the system topic to synchronize other brokers with load metadata. Unfortunately, the extension failed to initialize properly, and doesn’t create the system topic, but without crashing the broker which will be seen up by our monitoring : + +```shell +2024-08-02T08:48:53,344+0000 [CompletableFutureDelayScheduler] WARN org.apache.pulsar.broker.loadbalance.extensions.channel.ServiceUnitStateChannelImpl - clevercloud-pulsar-broker-c3-n1:8080 failed to wait for owner for serviceUnit:orga_79bb9459-98d7-48bb-91ea-cd64204d8140/logs/0x80000000_0xc0000000; Trying to return the current owner:Optional[clevercloud-pulsar-broker-c3-n1:8443] java.util.concurrent TimeoutException: null +2024-08-02T08:48:53,344+0000 [CompletableFutureDelayScheduler] ERROR org.apache.pulsar.broker.loadbalance.extensions.channel.ServiceUnitStateChannelImpl - clevercloud-pulsar-broker-c3-n1:8080 failed to get active owner broker. serviceUnit:orga_79bb9459-98d7-48bb-91ea-cd64204d8140/logs/0x80000000_0xc0000000, state:Owned, owner:Optional[clevercloud-pulsar-broker-c3-n1:8443] +java.util.concurrent.CompletionException: java.lang.IllegalStateException: The new owner clevercloud-pulsar-broker-c3-n1:8443 is inactive. Caused by: java.lang.IllegalStateException: The new owner clevercloud-pulsar-broker-c3-n1:8443 is inactive. +``` + +Since the monitoring didn’t catch it, the broker was up so the rolling process continued. The more it started, the more they tried to reach the topic metadata, fulfilling the *Lookup requests queue* : + +```shell +2024-08-02T08:49:12,448+0000 [pulsar-io-3-5] WARN org.apache.pulsar.client.impl.MultiTopicsConsumerImpl - Failed to get partitions for topic to determine if new partitions are added +java.util.concurrent.CompletionException: org.apache.pulsar.client.api.PulsarClientException$TooManyRequestsException: {"errorMsg":"Failed due to too many pending lookup requests","reqId":1946266099531305237, "remote":"clevercloud-pulsar-broker-c3-n9/192.168.2.9:6650", "local":"/192.168.2.9:58654"} Caused by: org.apache.pulsar.client.api.PulsarClientException$TooManyRequestsException: {"errorMsg":"Failed due to too many pending lookup requests","reqId":1946266099531305237, "remote":"clevercloud-pulsar-broker-c3-n9/192.168.2.9:6650", "local":"/192.168.2.9:58654"} +``` + +Ultimately, the topic has never been properly created and brokers ended up in a state where no topics were loaded : + +```shell +2024-08-02T09:16:23,828+0000 [pulsar-io-3-7] WARN org.apache.pulsar.client.impl.BinaryProtoLookupService - [non-persistent://pulsar/system/loadbalancer-broker-load-data] failed to get Partitioned metadata : {"errorMsg":"Failed to get partition metadata","reqId":2658063197115238188, "remote":"clevercloud-pulsar-broker-c3-n1/192.168.2.1:6650", "local":"/192.168.2.1:34522"} org.apache.pulsar.client.api.PulsarClientException$BrokerMetadataException: {"errorMsg":"Failed to get partition metadata","reqId":2658063197115238188, "remote":"clevercloud-pulsar-broker-c3-n1/192.168.2.1:6650", "local":"/192.168.2.1:34522"} +2024-08-02T09:16:24,346+0000 [broker-client-shared-scheduled-executor-7-1] WARN org.apache.pulsar.client.impl.PulsarClientImpl - [topic: non-persistent://pulsar/system/loadbalancer-broker-load-data] Could not get connection while getPartitionedTopicMetadata -- Will try again in 795 ms +2024-08-02T09:16:24,348+0000 [pulsar-io-3-15] ERROR org.apache.pulsar.broker.service.ServerCnx - non-persistent://pulsar/system/loadbalancer-broker-load-data [id: 0xa5782645, L:/192.168.2.1:6650 - R:/192.168.2.1:34522] [SR:192.168.2.1, state:Connected] Failed to get partition metadata java.util.concurrent.CompletionException: java.lang.IllegalStateException: The registry already closed.Caused by: java.lang.IllegalStateException: The registry already closed. +``` + +When we noticed the fall of the bandwidth on the platform, we understood that no topics were loaded, we rolled back the modification on the unload strategy but we decided to stick with the 3.3.1 release. + +Switching back to the old policy is a quick move. Configuration revisions are versioned, and this one in particular was pretty simple, yet we faced a new problem. The new unload strategy created a system topic that was unloadable by brokers because of a metadata conflict. The topic wasn’t assigned to any brokers, and it was a showstopper to initialize: Brokers wouldn’t start… We ended up stopping all brokers to start only one, preventing metadata conflict between them, then it succeeded to load the topic, so that we could finally delete it, unlocking all brokers start process. After that, in less than 10 minutes, all brokers were back to a nominal situation so we started proxies. + +It’s worth mentioning that for non minor releases, we use a simulation process that emulates a full environment where we inject changes. This validates upgrades and changes by observing the infrastructure behavior before going to production. This process wasn’t used for minor maintenance upgrades or (apparently) small changes in the configuration profile. + +### Hypervisor IO/CPU pressure + +The unavailability of the Apache Pulsar messaging layer has led to the buffering of telemetry agents on the Virtual Machines (VMs) running on Hypervisors (Servers). Customers VMs embed an observability agent named Vector ([https://vector.dev/](https://vector.dev/)) we chose for its ability to be very efficient and safe (being written in safe Rust). These agents started to buffer in memory while Messaging service endpoints weren’t available. Even if the format is rather efficient, for small VMs it reached a limit of memory which triggered a lot of memory pressure on the kernel. When it happens, the kernel tries to flush all possible memory, wipes all disk caches, and ultimately remove processes from memory to load them instruction per instruction from disk. + +At this stage, this is generating a lot of IO disk pressure on the underlying hypervisor (we noticed ~25Gbps on disks). These small VMs are spreaded globally among our Availability Zones, so we ended up having an overloaded server infrastructure. + +Clever Cloud also runs on top of Clever Cloud, which usually has many benefits. In this case, it turned out to be a chicken and egg situation : we needed the scheduler to perform some massive actions and comply with deployments, but the control plane was performing suboptimally and the infrastructure struggled to provide available resources. + +### Hypervisor crashes — Kernel Panics + +A few minutes after the hypervisors got their load increased, we started to see kernel panics on some of our host hypervisors. Those kernel panics were triggered by the khungtaskd kernel thread. This watchdog thread, living inside the Linux kernel, is responsible for watching all tasks the kernel is handling. It iterates over all the tasks and checks all tasks in the `TASK_UNINTERRUPTIBLE` state. + +The `TASK_UNINTERRUPTIBLE` state means that a task can’t be interrupted. This is the `D` state you can see in `ps` or `htop`. For example, you can get this state by reading or writing to the disk but there are also other syscalls that can put your process in this state. + +If the task is in this state for too long (default is 120s), then khungtaskd dumps a trace of the task (which program caused it, its current callstack, ..) in the kernel ring buffer. In our case, we also chose to panic when we have programs in this state: it usually means the kernel either has a bug or something else is going wrong. This watchdog already helped us multiple times in the past to crash the host before it gets completely unreachable and unpredictable. + +Some of our hypervisors had processes stuck in `TASK_UNINTERRUPTIBLE` for too long, for various reasons: writing to disk, KVM syscalls, .. An analysis of the source code ( [https://elixir.bootlin.com/linux/v6.10.3/source/kernel/hung_task.c#L91](https://elixir.bootlin.com/linux/v6.10.3/source/kernel/hung_task.c#L91) ) confirms our thoughts on the observed behavior. + +{{< figure src="/developers/images/ccpm-2024-08-02-image_0.png" caption="Stuck processes leading to a Kernel Panic" width="800px">}} + +### Monitoring down → upscale + +During the event, the monitoring infrastructure triggered a lot of events for both infrastructure and customer services. We observed almost x3 deployments as usual during that day. Multiple reasons can explain this observation: + +* The loss of hypervisors due to kernel panics made a lot of instances unreachable, leading to lots of deployments to honor the contract (e.g. number of minimum instances) +* VMs that were under memory pressure were usually unresponsive and so they were (correctly) seen as unreachable +* VMs that were on overloaded hypervisors might have also been slowed down due to the high CPU usage of the hypervisor. Those VMs had less CPU time to do their usual operations, making their load average increase. Our monitoring took that as an increase of CPU usage and they were ordered to upscale if they were configured to +* Some of our monitoring instances took more time to do their checks because they were overloaded as well. Because the monitoring data was missing due to late checks, it was interpreted as lack of data and so as unreachable VMs, triggering more Monitoring/Unreachable events +* Customers seeing their service unavailable are trying to trigger redeployment of their applications, which adds more scheduling tasks on the infrastructure + +Our monitoring infrastructure, by observation of many key metrics (CPU Loads, CPU Steal, Availability, health checks, etc.) triggered a significantly higher rate of deployments, which at the time, wasn’t helping both to chill down the control plane already processing at the best it could and the overall infrastructure already overloaded. + +### Soothing the control plane + +Once we understood some Virtual Machines (VMs) were inducing an abnormal high load on Hypervisors (HVs), we started to filter out machines that could help to free some resources. All non critical services have been shut down like the Observability platform: We stopped the _Long Term Storage for Observability_ metrics data (our Warp10/FoundationDB cluster). Critical services benefit from In Memory Observability (Warp10 in memory standalones), so this was acceptable to preserve all available resources. + +Overloaded VMs were collected, sorted and it appeared they shared a common pattern: they were small VMs with few memory resources. The reason has been covered a few lines above. The process after identifying them is obviously to kill them one by one by the SRE team. Nothing fancy here, but soon we started to regain control over all hypervisors. + +## Lessons & enhancements + +We’ve learnt many lessons this Friday and we already identified many enhancements we will give to the platform. Sure this kind of incident occurring during a summer holiday period is tricky, but we escalated the problem quickly to call people on holiday as soon as 13:00 CEST. We identified two groups of enhancements. A first one, measurable, and identified as a key infrastructure management where some of the measurement are : + +* Pulsar Broker health +* Pulsar Cluster health +* Hypervisor load +* Hypervisor I/O +* Hypervisor reboot (Kernel Panic) +* Zombies VM +* RabbitMQ Broker health +* RabbitMQ Cluster health +* Deployment queue consumption + +These measurements give us KPIs to measure where we've been operationally good, and where we have lacked some visibility or reaction. We qualified them with four inputs: + +* Time of event +* Time of detection +* Time of decision +* Time of resolution + +This factual approach helped to challenge ourselves on established rules and showed we can improve or rethink some part of the infrastructure. + +Other topics raised but without KPI analysis: + +* Dealing with too many monitoring alerts +* Backup Bastion — a regional bastion is vulnerable +* Control Plane recovery process +* Correlation between monitoring and Orchestration +* Fault domain separation vs multi tenancy +* Rethink for runtime images and the role of the hypervisor +* Isolation for waved release upgrades (Pulsar) + +All the above questions and KPIs convert to actionable actions for teams that you may question at any time. + +### Actions in progress + +Following immediate actions, we created a lot of issues to avoid the same behavior in the future: + +* Runtime image redesign / better hypervisor integration +* Regionalized observability for redundancy +* Better profiling for small VMs : + * Vector configuration + * `buffer.max_events` / `buffer.max_size` (must be at least 256Mo if `type=disk`) + * `buffer.type` `memory` (default) → switch to `disk` + * `buffer.when_full` `block` (default) → `drop_newest` + * Journald verbosity and `SystemMaxUse` + * Cgroups restrictions for better process control + * I/O restrictions for VM manager +* Better zombies VM detection + +We don’t face a lot of outages and big issues, because by design, we strive to do a good job of running production applications for our customers. As we grow, challenges grow, and we’re committed to achieve great production SLA because it’s our DNA, our mission: running your production workloads. + +This experience will help us become even more reliable and we thank you for your help during this difficult time. diff --git a/content/postmortem/2025-03-03.md b/content/postmortem/2025-03-03.md new file mode 100644 index 000000000..e9c976583 --- /dev/null +++ b/content/postmortem/2025-03-03.md @@ -0,0 +1,218 @@ +--- +title: '2025-03-03' +description: 'An electrical power outage resulted in a cascade of errors that perturbed platform stability and customer service. A detailed explanation of encountered issues, what we’ve learned.' +date: 2025-03-07 +draft: false +excludeSearch: true +type: docs +--- +{{< hextra/hero-subtitle >}} +An electrical power outage resulted in a cascade of errors that perturbed platform stability and customer service. A detailed explanation of encountered issues, what we’ve learned. +{{< /hextra/hero-subtitle >}} + +On Monday, March 3rd, 2025 Clever Cloud’s platform became unstable, leading to downtime of varying duration and scope, for many customers. The impact was both on the API itself, and on some services running as add-ons or runtimes. + +These events occurred because: + +* A power outage on one of our data center providers caused a temporary disruption of our services on the PAR6 Availability Zone (AZ) from EU-FR-1 at 14:55 CET +* As an indirect consequence, networking traffic was perturbed, the infrastructure experienced I/O and memory pressure between 14:58 and 16:30 CET leading to instabilities and downtime. + +Impacts were observed for customers relying on the EU-FR-1 (PAR) region, and remote zones depending on the EU-FR-1 control plane (GOV, OVHcloud, Scaleway, and Oracle) and some privates zones. On-premise zones weren’t impacted. + +Status were communicated through : https://www.clevercloudstatus.com/incidents/959 + +| Product | Impact | +|---------|--------| +| Runtimes | Applications may have experienced performance degradation and traffic issues due to impacted hypervisors and load balancers | +| Runtimes deployment | The incident prevented new deployments, upscaling and downscaling operations from succeeding due to the Deployment API being unreachable | +| Databases (MySQL, PostgreSQL, Redis, MongoDB) | The incident may have caused performance degradation or unavailability for customers whose databases were running on affected hypervisors. Data loss did not occur | +| Cluster services (Elastic, Couchbase, Cassandra, …) | The service may have been maintained on some nodes, depending on the infrastructure pressure and the technology used. While some clusters were impacted during the incident, others were not | +| VPN / IPSec | Most of the VPN endpoints were unavailable during the incident | +| Observability | The service has successfully recovered from the electrical issue, and logs were available | + +## Timeline + +| Timeline | Component | Description | +|-----------|-----------|-------------| +| 14:55 CET | Infrastructure | Power outage at PAR6 (Green Data) data center | +| 14:56 CET | Load Balancers | Monitoring advertises the loss of a load balancer - 1st event | +| 14:56 CET | Infrastructure | Monitoring shows a global incident reporting many unavailabilities | +| 14:57 CET | Infrastructure | Infrastructure team opens a crisis conference | +| 14:58 CET | Infrastructure | Power is back, servers and network equipment are restarting (confirmed later by data center incident report) | +| 14:58 CET | Customers | Support team received notification from external monitoring and customers that some websites are down (Console, admin, etc.) | +| 14:58 CET | Customers | Tech team reported that GitLab is also unavailable | +| 14:58 CET | Infrastructure | Tech team created an incident canal #incident-03-03-2025 | +| 15:00 CET | Infrastructure | Infrastructure team summoned others on call teams and members on canal #incident-03-03-2025 | +| 15:02 CET | Infrastructure | Hypervisors and network equipment have rebooted | +| 15:02 CET | Infrastructure | Several PAR6 hypervisors (12 of them) are indicating that their RAID array are rebuilding | +| 15:05 CET | Infrastructure | Reporting that AZ Monitoring is under heavy load | +| 15:06 CET | Infrastructure | Infrastructure team confirmed that we have retrieved every hypervisors on PAR6 since at least 4 minutes to 6 minutes | +| 15:08 CET | Network | A network provider hosted in PAR6 reports 2 powerline cuts | +| 15:10 CET | Infrastructure | Report from one of our network provider confirming the electrical outage | +| 15:14 CET | Messaging | Pulsar is back up online | +| 15:14 CET | Observability | Pulsar in-memory observability didn't restart properly | +| 15:18 CET | Observability | Pulsar in-memory observability is online | +| 15:19 CET | Infrastructure | A RabbitMQ node came back to the cluster after we fixed the communication between the hypervisor and the queue | +| 15:27 CET | DBaaS | Main addon databases clusters is correctly restarting | +| 15:27 CET | DBaaS | Check the availability of internal databases clusters | +| 15:29 CET | DBaaS | DBaaS team start to handle manually all ciphered databases which are still down (due to an unavailabilty of the addon provider APIs) | +| 15:30 CET | Infrastructure | Seeing a lot of WireGuard connectivity issues on multiple distributed clusters | +| 15:30 CET | Infrastructure | Asked to priorise GitLab databases restarts | +| 15:33 CET | Infrastructure | Some hypervisors are overloaded, probably due to Vector/Telegraf not being able to push data to Warp10/Pulsar. Started to list all VMs with CPU load > 1 to relieve the infrastructure | +| 15:37 CET | Infrastructure | Check if Ceph/Cellar are okay. Some daemons seem to hang and 1/4 of OSD are still down on PAR6, requests are served correctly | +| 15:38 CET | DBaaS | Asked DBaaS team to prioritize Clever Cloud's GitLab databases | +| 15:38 CET | Infrastructure | Listed all applications with VMs CPU load > 1, starting to kill them to relieve the infrastructure | +| 15:42 CET | DBaaS | Databases reboot are still lock on some Hypervisor due to a network issue | +| 15:42 CET | Infrastructure | Fixed a network setup issue on a specific Hypervisor | +| 15:45 CET | Messaging | Listed all GitLab and Premium services databases for DBaaS team | +| 15:45 CET | Observability | A global maintenance is set on all monitoring servers in EU-FR-1 to avoid flooding the Orchestration core API with redeploy events | +| 15:45 CET | DBaaS | Asked to reboot PostgreSQL add-on provider in priority | +| 15:49 CET | Deployments | We lacked 2.8k VMs on the infrastructure | +| 15:52 CET | Infrastructure | Some deployments are failing on PAR6 due to unbound on some HV not restarted, no DNS available | +| 15:54 CET | Observability | See timeouts on Vector logs when connecting to Pulsar | +| 15:55 CET | Infrastructure | Unlock first HVs to allow databases reboot (HV iptables rules) | +| 15:56 CET | Messaging | We hit the max connections threshold on Pulsar | +| 15:56 CET | Infrastructure | Vector logs timeouts fixed, by corrective iptables on hypervisor | +| 15:59 CET | Infrastructure | All Hypervisor iptables generated are restored on PAR6 HVs and services have been restarted | +| 16:00 CET | DBaaS | Can now repair databases down impacted by hypervisors network issues | +| 16:03 CET | Infrastructure | Connectivity issues due to conntrack issue (need to purge conntrack table) | +| 16:05 CET | Customers | Some load balancers are unsynced due to RabbitMQ crash | +| 16:05 CET | Load Balancers | Start the rolling restart of unsynced load balancers | +| 16:06 CET | Infrastructure | Some deployments are still failing on PAR6 due to WireGuard problems with the DNS recursor of the AZ, the recursor is dropped from unbound / resolv.conf of all PAR6 hypervisors | +| 16:07 CET | Load Balancers | For some applications it's not a load balancer issue, but the application have no instances running | +| 16:08 CET | Infrastructure | Dropped UDP conntracks on the hypervisor of PAR6 DNS recursor to recover WireGuard mesh topologies | +| 16:19 CET | Messaging | WireGuard issues on BookKeeper cluster for Pulsar | +| 16:28 CET | Deployments | Purge delayed alerts on Zabbix monitoring | +| 16:30 CET | Deployments | Restart all applications without any VMs | +| 16:34 CET | DBaaS | Elasticsearch add-ons repair is locked due to the unavailability of our LDAP | +| 16:34 CET | Deployments | Reboot of Keycloack | +| 16:42 CET | Customers | Nodes of Couchbase have been reintroduced in their cluster | +| 16:45 CET | Infrastructure | Finished killing overloaded VMs | +| 16:47 CET | Deployments | Stop instances that are blocked and have failed their deployments and redeploy the application | +| 16:47 CET | Deployments | Fix a Ruby error on bastion that prevent to redeploy application | +| 16:58 CET | Deployments | Stacking semaphores in BDS Orchestrator | +| 16:58 CET | Infrastructure | Network issue on Warp10 FoundationDB | +| 17:00 CET | Deployments | Disabled HA replication of some queues to speed up RabbitMQ | +| 17:17 CET | DBaaS | Recovery of our LDAP enable an Elasticsearch add-ons recovery | +| 17:18 CET | Load Balancers | Restart all add-on providers to be able to properly reload last load balancers | +| 17:20 CET | Load Balancers | End the rolling restart of all impacted load balancers at Clever Cloud | +| 17:28 CET | Observability | Zabbix on PAR8 back in action | +| 17:31 CET | Deployments | Still 1.3k VMs to deploy | +| 17:35 CET | Infrastructure | Two FoundationDB's VMs could not be started because the NVMe was unavailable | +| 17:37 CET | Deployments | Increased concurrent deployments from 300 to 400 to increase recovery speed | +| 17:50 CET | Observability | Cleaning up old hosts in Paris Monitoring to avoid sending too much outdated monitoring events | +| 17:57 CET | Observability | Zabbix on PAR7 back in action | +| 18:00 CET | Deployments | Started to restart all applications still seen as unavailable by Monitoring | +| 18:05 CET | Infrastructure | Restart Sydney orchestration that are unsynced | +| 18:05 CET | Observability | Zabbix on PAR6 back in action | +| 18:18 CET | Infrastructure | Force to stop all VMs in stopping status | +| 18:45 CET | Observability | Remove the maintenance mode of Monitoring | +| 18:53 CET | Deployments | Deploy last application in failing deployment state | +| 18:54 CET | Infrastructure | Investigating under-replicated Kafka partitions on Warp10 | +| 18:55 CET | DBaaS | All databases are up and running | +| 19:00 CET | DBaaS | Some Elasticsearch are down again (due to an heavy resources usage on recovery) | +| 19:11 CET | Deployments | Finished to restart all applications still seen as unavailable by Zabbix | +| 19:12 CET | Infrastructure | Starting to recover the Ceph cluster, 2 physical machines don't have any network, one has a network configuration issue | +| 19:16 CET | Infrastructure | Start the recovery of Ceph cluster | +| 19:23 CET | Core APIs | Restart of Logs API | +| 19:35 CET | DBaaS | All add-ons are OK | +| 20:25 CET | Infrastructure | All Ceph machines are correctly restarted, cluster is recovering 0.3% of degraded objects | +| 20:48 CET | Infrastructure | Ceph cluster has recovered degraded objects, HEALTH_OK | +| 21:20 CET | DBaaS | Last replica down identified was rebuid | + +## Analysis + +### Power Outage + +We’re still waiting for a detailed explanation from the data center operator, but the same day was scheduled a planned maintenance which consisted in testing UPS for a given time. We observed a 5 seconds window between the power cut and the power recovery. + +It led to an instant restart of our entire Availability Zone (AZ). Unfortunately, we can’t provide more insights about the origin of the failure for the moment except a faulty component has cause the power cut, which is unacceptable since we're running at least 2N (most are 2N+1) power adduction with separated power source. A single faulty component shouldn't have any impact on the two power lines. + +We're expecting a better postmortem from our data center operator. + +### Networking connectivity issue + +Our network relies on multiple transits to ensure both a good Internet connectivity and a good resilience. These transits are spread among three Points of Presence (PoP). During the restart of networking routers, there appears to be an issue with accessing the region via public connectivity, despite these multiple transits. +Our observability system was unfortunately located on the lost AZ, so we lost the flows to analyze the traffic during the power cut. +Known Issues: +- In some cases, when a router reboots, it may start receiving traffic before it knows where to route it. A specific starting sequence may be enforced to avoid this behavior. + +#### Possible Causes of Downtime +- A transit partner did not notice that the session was down before the BGP session timed out (a few minutes), so traffic continued to be routed through them even though we were no longer there to handle it. Another transit partner continued to announce our prefixes even though they couldn't route the traffic to our network. +- There is a 3-minutes timeout on the BGP sessions of the routers, with no Bidirectional Forwarding Detection (BFD) to accelerate convergence. + +#### Unclear Areas +- In the nominal situation, most of our traffic is gathered at TH2 POP, so we shouldn't have seen such a significant impact. +However, most of our traffic exits through another transit partner through the incriminated AZ (correlate with the one of the possible cause of downtime) +- Did the other routers still have announcements (received from the power cut AZ routers) when they received traffic to send to the internet, because the BGP sessions hadn't yet timed out? (correlate with the one of the possible cause of downtime) + +Network issues were gone at 15:15 CET. We run a simulated copy of our networking topology inside the GNS3 emulator. We will quickly replicate this hypothesis to try to reproduce and tests some enhancements. + +### Messaging Maintenance (Apache Pulsar) + +Learning from a previous outage last summer, we invested a lot in this layer and enhancements made likely focused on improving the resilience and fault tolerance of the system. This includes better monitoring, automated failover processes, auto healing and enhanced data replication strategies with better isolation. + +By leveraging Pulsar's disaggregated architecture and the investments made in infrastructure and operational practices, the system was able to recover swiftly from the loss of an AZ. This resilience underscores the importance of continuous improvement and preparedness in maintaining high availability and reliability. + +While the service has been wavering for a couple of minutes, reshuffling all connections on remaining AZs, we confirmed the Pulsar's ability to recover quickly. Yet the proxy layer combined with the metadata management wasn’t enough to quickly accept massive new connections (hundreds of thousands) in a very short time window. + +We already identified the problem for metadata management, and along the year we made many improvements which led us to decide we need a radical enhancement for a more scalable solution. Unfortunately this work is not ready yet. We will also enhance the connection management. + +### Hypervisor IO/CPU pressure, images + +The difficulty for accepting massive new connections on the Apache Pulsar messaging layer has led to the buffering of telemetry agents on the Virtual Machines (VMs) running on Hypervisors (servers). Customers VMs embed an observability agent named Vector we chose for its ability to be very efficient and safe. We anticipated these agents buffering would induce an I/O pressure on the hypervisor. + +This overload had an impact on small VMs that reached a limit of memory which triggered swapping then a lot of pressure on the hypervisor. We changed our image base format from the last months to enhance the testability of images. Guard rules have been developed to ensure a better process isolation using CGroups inside these new images, preventing small VMs to stress memory. Unfortunately these changes were in evaluation to ensure the stability of the design, but didn't make it to production for the incident. + +As a consequence, these VMs overloaded was seen as unavailable from the monitoring, then rescheduled which causes a chicken and egg situation: we needed the scheduler to perform some massive actions and comply with deployments, but the control plane was performing sub-optimally and the infrastructure struggled to provide available resources. + +Also, a few hours before the incident, we deployed multiple enhanced images, with new tooling but fewer available space. This led to deployment errors for some customers. We rolled back some images globally or for some applications, and will fix this issue until next images update. + +### Orchestration + +Initially, we implemented an orchestration system based on an offering model (similar to Apache Mesos), which provided a solid foundation for managing our services. In an offering model, an orchestrator manages the allocation and deallocation of resources, such as virtual machines (VMs), to ensure efficient utilization and meet service demands. + +However, the orchestrator can become stuck due to semaphore locking issues during VM assignment for several reasons: +- **Resource Contention:** Semaphores are used to control access to shared resources, ensuring that only a limited number of processes can access them simultaneously. If multiple VMs are attempting to acquire the same resource concurrently, contention can occur, leading to semaphore locks. This can cause the orchestrator to wait indefinitely if the locks are not released promptly. +- **Deadlocks:** A deadlock situation arises when two or more processes are each holding a resource and waiting for the other to release a resource they need. In the context of VM assignment, if the orchestrator and other processes are waiting for each other to release semaphores, it can result in a deadlock, causing the orchestrator to become stuck. +- **Improper Semaphore Management:** If semaphores are not properly initialized, acquired, or released, it can lead to locking issues. For instance, if a semaphore is not released after a VM assignment operation completes, other processes waiting for that semaphore will remain blocked, including the orchestrator. +- **High Load and Scalability Issues:** Under high load conditions, the orchestrator may struggle to manage the increased number of VM assignment requests. If semaphores are used to serialize access to critical sections of code, excessive locking can occur, leading to performance bottlenecks and causing the orchestrator to become unresponsive. +- **Timeouts and Retries:** If the orchestrator encounters timeouts while waiting for semaphores to be released, it may repeatedly retry the operation. Without proper back-off strategies, this can exacerbate contention and further delay VM assignments, leading to a stuck state. + +To mitigate these issues, it's essential to implement robust semaphore management practices, monitor resource usage, and employ strategies to detect and resolve deadlocks. Additionally, optimizing the orchestrator's algorithms for scalability and efficiency can help prevent semaphore locking problems. + +The problem is, while this locking mechanism helps to provide the best determinism in an offering model, it can also lower the rate of VM instance creation. During the recovery process, we had to continuously adjust this locking variable to allow more service to be queued for scheduling. + +However, recognizing the need for enhanced capabilities and a broader range of product offerings, we have transitioned over the past few months to a new orchestration model. This shift is designed to offer more performance, more resiliency, advanced features and support a wider diversity of products. The new orchestration is being rapidly implemented as a new backend, and we are making swift progress in integrating it into our existing infrastructure. This upgrade will not only improve our operational efficiency but also enable us to deliver more innovative solutions to our clients. This is already in production for the Logs Drains which behaved as expected during the incident. + +## Actions + +### Databases + +- #63 Enhance replication monitoring for MySQL databases +- #290 Enhance providers API to use replication to ease ciphered databases reboot + +### Runtimes + + - #856 Enforce guard I/O rules at Hypervisor level + - #857 Enhance observability for small profile VM memory pressure + + ### Networking + + - #832 Ensure OSPF/BGP convergence times on routers + - #898 Enhance boot sequence process on routers + - #899 Ensure a good resiliency for border routing BGP announces + + ### Orchestration + + - #900 Ensure a failsafe VM restart capability + - #901 Enhance hypervisor sequence of start process + - #902 Ensure a better network configuration compliance across upgrades + - #864 Better observability for unresponsive VM + - #903 Improve AZ monitoring resiliency + +### Conclusion + +Our response to this outage demonstrated significant improvements compared to previous incidents. The team's actions and coordinated efforts mitigated the impact and expedited the resolution process. Most of the challenges we encountered were related to ongoing projects and enhancements that are nearing completion. These issues have provided valuable insights that will further strengthen our systems and processes. + +We are confident that the measures we are implementing will prevent similar occurrences in the future and enhance our overall reliability and performance. We’re sincerely sorry for the inconvenience caused to our customers, and we’re committed to provide the best quality of service. We plan to organize a meeting for every demanding customer to explain both the incident and our actions. diff --git a/content/postmortem/_index.md b/content/postmortem/_index.md new file mode 100644 index 000000000..d7bddfae5 --- /dev/null +++ b/content/postmortem/_index.md @@ -0,0 +1,10 @@ +--- +title: 'Postmortem' +description: +date: 2024-08-08T15:32:06+02:00 +draft: false +type: docs +--- + +- [2024-08-02](/developers/postmortem/2024-08-02) +- [2025-03-03](/developers/postmortem/2025-03-03) diff --git a/data/icons.yaml b/data/icons.yaml new file mode 100644 index 000000000..c5a439214 --- /dev/null +++ b/data/icons.yaml @@ -0,0 +1,126 @@ +# Cards icons +adjustments-horizontal: +api: +arrow-down-tray: +arrow-path: +arrow-trending-up: +arrow-up-on-square-stack: + +banknotes: +bell: +bookmark-square: +bubbles: +building-library: + +chart-bar-square: +checklist: +circle-stack: +clock: +cloud-arrow-up: +code-bracket: +cog-6-tooth: +command-line: +cursor-arrow-ripple: + +document-check: + +endpoints: +eye-dropper: + +feather: +lifebuoy: + +magnifying-glass: +map-pin: + +new: + +pencil-square: +play-circle: +plug: + +rocket-launch: + +science: +server-stack: +shovel: + +tcp-ip-service: +traffic-light: + +window: +wrench-screwdriver: + +# Runtimes +docker: +frankenphp: +bun: +go: +haskell: +java: +linux: +node: +ruby: +php: +# alternative logo +#php: +python: +rust: +scala: +elixir: +dotnet: +static: +v: +# Add-ons +mysql: +pg: +mongo: +fsbucket: +cellar: +redis: +elastic: +creds: +kibana: +keycloak: +pulsar: +jenkins: +matomo: +# ------------- Materia ------------- +# Original design +#materia: +# Sphere from iconify +materia: +# Brands +git: +clamav: +clever: +new-relic: +metabase: +# Frameworks +meteor: +maven: +moodle: +docs-suite: + +drupal: +wordpress: +django: +symfony: +laravel: +play: +gradle: +fluentd: + +# Static +11ty: +astro: +deno: +docs: +docusaurus: +hexo: +hugo: +html: +mdbook: +nuxt: + +kubernetes: diff --git a/data/runtime_versions.yml b/data/runtime_versions.yml new file mode 100644 index 000000000..362e7a345 --- /dev/null +++ b/data/runtime_versions.yml @@ -0,0 +1,79 @@ +bun: + eol_source: https://github.com/oven-sh/bun/releases + default: + - 1.2.19 + +dotnet: + eol_source: https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core + default: + - 8.0 + accepted: + - 6.0 (EOL) + - 9.0 + +elixir: + eol_source: https://hexdocs.pm/elixir/compatibility-and-deprecations.html + default: + - 1.18 + accepted: + - 1.8 (EOL) + - 1.9 (EOL) + - 1.10 (EOL) + - 1.11 (EOL) + - 1.12 (EOL) + - 1.13 (EOL) + - 1.14 + - 1.15 + - 1.16 + - 1.17 + - 1.18 + +java: + eol_source: https://adoptium.net/fr/support/ + default: + - 11 + accepted: + - 24 + - 23 (EOL) + - 21 + - 17 + - 11 + - 8 + - 7 (EOL) + - graalvm-ce + +node: + eol_source: https://nodejs.org/en/about/releases/ + default: + - 22.18.0 (npm 10.9.3) + +php: + eol_source: https://www.php.net/supported-versions.php + default: + - 8 (8.4) + accepted: + - 5.6 (EOL) + - 7 (EOL) + - 7.1 (EOL) + - 7.2 (EOL) + - 7.3 (EOL) + - 7.4 (EOL) + - 8 + - 8.0 (EOL) + - 8.1 + - 8.2 + - 8.3 + - 8.4 + +python: + eol_source: https://devguide.python.org/versions/#python-release-cycle + default: + - 3 + accepted: + - 2 + - 3 + - 3.9 + - 3.10 + - 3.11 + - 3.12 + - 3.13 diff --git a/data/software_versions_shared_dedicated.yml b/data/software_versions_shared_dedicated.yml new file mode 100644 index 000000000..0a58eee47 --- /dev/null +++ b/data/software_versions_shared_dedicated.yml @@ -0,0 +1,34 @@ +dev_message: "**Important**: Dev plans are free and **solely for testing purposes**. They don't provide the same guarantees or SLAs as dedicated plans." + +elastic: + dedicated: + - v7.17.10 + - v8.10.2 + +mongo: + dedicated: + - v4.0.3 + dev: + - v4.0.3 + +mysql: + dedicated: + - 5.7 (EOL) + - 8.0 + - 8.4 + dev: + - 8.0 + +pg: + dedicated: + - v13.21 + - v14.18 + - v15.13 + - v16.9 + - v17.5 + dev: + - v15.13 + +redis: + dedicated: + - v8.0.3 diff --git a/data/tooltips.toml b/data/tooltips.toml new file mode 100644 index 000000000..e696e7c88 --- /dev/null +++ b/data/tooltips.toml @@ -0,0 +1,5 @@ +IaaS = "Infrastructure-as-a-Service" +PaaS = "Platform-as-a-Service" +WAR = "Web Archive" +JEE = "Java Enterprise Edition" +EAR = "Enterprise Archive" diff --git a/commons/get-help/community.md b/drafts/community.md similarity index 50% rename from commons/get-help/community.md rename to drafts/community.md index 27a685099..05d34873f 100644 --- a/commons/get-help/community.md +++ b/drafts/community.md @@ -1,22 +1,26 @@ --- +type: docs title: Community -position: 2 +weight: 6 tags: +- help +keywords: - support +- community +- gitter +- irc +draft: true --- -# Community +Engage in our Developer Community by seeking or providing advice on application and development level questions. We have a community of developers using our platform and you can help and be helped there. -Engage in our Developer Community by seeking or providing advice on application and development level questions. We have a community of developers using our platform and you can help make it stronger. +## Gitter + +* English room: +* French room: ## Public IRC Channel We’re also available on IRC. You can join our channel: * [#clevercloud on irc.freenode.net](irc://irc.freenode.net:6667/clevercloud) - -## Mailing List - -Our mailing list is available is where we announce new features and beta programs. Be part of it to try our new features, or having access to our developer community. - -* diff --git a/drafts/elastic.md b/drafts/elastic.md new file mode 100644 index 000000000..4d24565b2 --- /dev/null +++ b/drafts/elastic.md @@ -0,0 +1,19 @@ +--- +type: docs +title: Elastic +description: Elastic guides +tags: +- guides +keywords: +- elastic +- kibana +- APM +aliases: +- /doc/deploy/addon/elastic/kibana +comments: false +draft: true +--- +{{< cards >}} + {{< card link="/developers/guides/elastic/kibana" title="Customize Kibana" subtitle= "Deploy and customize a Kibana server on Clever Cloud" icon="kibana" >}} + +{{< /cards >}} diff --git a/drafts/medusajs.md b/drafts/medusajs.md new file mode 100644 index 000000000..eed0a3bbd --- /dev/null +++ b/drafts/medusajs.md @@ -0,0 +1,46 @@ +--- +title: 'Medusa.js' +date: 2023-11-13T11:00:11+01:00 +draft: true +type: docs +--- + +## Create your Medusa.js project from scratch + +1. Deploy a PostgreSQL add-on and a Redis add-on +2. Copy the value of `POSTGRESQL_ADDON_URI` +3. In your terminal, run `npx create-medusa-app@latest --db-url ` +4. Follow the steps to configure your Medusa project +5. In your code, replace `DB_URL` by `POSTGRESQL_ADDON_URI` +6. Create a Node.js app in Clever Cloud +7. Inject your environment variables +8. Set a domain name and inject it as an environment variable: `MEDUSA_URL`=`}} + {{< card link="/developers/guides/proxysql" title="ProxySQL" subtitle= "Configure and use ProxySQL for MySQL add-ons" icon="mysql" >}} +{{< /cards >}} diff --git a/drafts/notifications.md b/drafts/notifications.md new file mode 100644 index 000000000..d27e09946 --- /dev/null +++ b/drafts/notifications.md @@ -0,0 +1,154 @@ +--- +type: docs +title: Notifications +description: How to setup and configure notifications via clever-tools +tags: +- cli +- reference +keywords: +- notification +- webhook +- e-mail +- email +- slack +- flowdock +aliases: +- /doc/administrate/clever-tools/notifications +- /doc/cli/notifications/ +draft: true +--- + +The *Notifications* service allows you to choose the events of interest to you +and decide where to send corresponding notifications. + +## E-mails + +Historically and by default, deployment result e-mails (deployment succeeded or +failed) were always sent to the owners of an application, namely the user +themselves or the organisation's members. + +Using the `notify-email` command of *clever-tools*, you can choose to disable +this or to restrict it to only some applications. + +To do this, you need to delete the hook named *Default deployment result +e-mails*, then add a new one and set it to your liking. + +Issue this command to learn more about this: `clever help notify-email`. + +In the future, this service will also handle credits warning notifications and +others to come. You will be able to choose wether or not to receive an e-mail +and/or for these events to be forwarded to a web service via a *webhook*. + +## Webhooks + +Webhooks are defined as follows: + +> A webhook in web development is a method of augmenting or altering the +> behavior of a web page, or web application, with custom callbacks. These +> callbacks may be maintained, modified, and managed by third-party users and +> developers who may not necessarily be affiliated with the originating website +> or application. +> — Wikipedia[^1] + +[^1]: Excerpted from Wikipedia's [webhook page](https://en.wikipedia.org/wiki/Webhook) + +In practical terms, this means that you can choose to receive all deployment +result events on an endpoint of your application without having to listen to +all events via the Websocket API. No more lost events and having to reconnect +to the websocket if and when it fails. + +*clever-tools* has a `webhooks` command which allows you to list existing +webhooks, remove one or add a new one. + +You can issue this command to learn more about it: `clever help webhooks`. + +### Example: Slack deployment results Webhook + +First, you will have to create the *Incoming WebHooks* integration on Slack: + +Let's go to the [custom integrations +page](https://slack.com/apps/manage/custom-integrations), once there go to +*Incoming WebHooks*. + +You will find an *Add Configuration* button on the left which will take you to +the page where you need to configure the integration. You just need to select +the channel where you want the notifications to be posted, then it will show +you the Webhook URL, it starts with `https://hooks.slack.com/services/`. Copy +that URL. + +Now, let's create the Webhook! + +Go into the application directory for which you want to receive notifications +and there issue this command: + +```shell +clever webhooks add "deployment results on Slack" https://hooks.slack.com/services/xxxxxx/yyyyyy/zzzzzzzzzzzzz --format slack --event META_DEPLOYMENT_RESULT +``` + +#### Events available + +The list of values that can be assigned to `--event` option: + +**Account:** + +- `ACCOUNT_CREATION` +- `ACCOUNT_DELETION` +- `ACCOUNT_EDITION` + +**Addon:** + +- `ADDON_CREATION` +- `ADDON_DELETION` + +**Application:** + +- `APPLICATION_CREATION` +- `APPLICATION_DELETION` +- `APPLICATION_EDITION` +- `APPLICATION_REDEPLOY` +- `APPLICATION_STOP` + +**Deployment:** + +- `DEPLOYMENT_ACTION_BEGIN` +- `DEPLOYMENT_ACTION_END` +- `DEPLOYMENT_FAIL` +- `DEPLOYMENT_SUCCESS` +- `GIT_PUSH` + +**Organisation:** + +- `ORGANISATION_CREATION` +- `ORGANISATION_DELETION` +- `ORGANISATION_EDITION` +- `ORGANISATION_USER_ADDITION` + +**Meta:** + +- `META_SERVICE_LIFECYCLE` = APPLICATION_STOP, DEPLOYMENT_ACTION_BEGIN, DEPLOYMENT_FAIL, DEPLOYMENT_SUCCESS +- `META_DEPLOYMENT_RESULT` = DEPLOYMENT_FAIL, DEPLOYMENT_SUCCESS +- `META_SERVICE_MANAGEMENT` = ADDON_CREATION, ADDON_DELETION APPLICATION_CREATION, APPLICATION_EDITION, APPLICATION_DELETION` +- `META_CREDITS` = CREDITS_ADDED + +**Others:** + +- `CLEVER_TOOLS_REQUEST` +- `CREDITS_ADDED` + +##### Examples + +Get a message in a Slack channel when the deployment for an application failed: + +```shell +clever webhooks add "The application failed to deploy" https://hooks.slack.com/services/xxxxxx/ --format slack --event DEPLOYMENT_FAIL +``` + +Notify your accounting service when credits are added: + +```shell +clever webhooks add "credits added" https://hooks.slack.com/services/xxxxxx/yyyyyy/zzzzzzzzzzzzz --format raw --event META_CREDITS +``` + +All done! You can now push your application (`clever deploy`) or restart it +(`clever restart`) and you will see the result of the deployment in your Slack +channel. diff --git a/drafts/postgresql.md b/drafts/postgresql.md new file mode 100644 index 000000000..19310c859 --- /dev/null +++ b/drafts/postgresql.md @@ -0,0 +1,23 @@ +--- +type: docs +title: PostgreSQL +description: Configure and manage your PostgreSQL add-ons +tags: +- addons +keywords: +- balancing +- connection +- limit +- load +- pgpool +- pool +- postgres +- proxy +- sql +comments: false +draft: true +--- + +{{< cards >}} + {{< card link="/developers/guides/pgpool" title="Pgpool-II" subtitle= "How to configure and use Pgpool-II for PostgreSQL add-ons" icon="pg" >}} +{{< /cards >}} diff --git a/drafts/pricing.md b/drafts/pricing.md new file mode 100644 index 000000000..8c685075d --- /dev/null +++ b/drafts/pricing.md @@ -0,0 +1,15 @@ +--- +type: docs +title: Pricing +draft: true +description: Pricing table of Clever Cloud's runtimes +tags: +- billing +keywords: +- pricing +type: docs +aliases: + - /clever-cloud-overview/pricing/ +--- + +Our up-to-date prices (as well as a pricing calculator) is available on the [pricing page](https://www.clever-cloud.com/pricing). diff --git a/drafts/shortcodes.md b/drafts/shortcodes.md new file mode 100644 index 000000000..db240dd4f --- /dev/null +++ b/drafts/shortcodes.md @@ -0,0 +1,89 @@ +--- +type: docs +weight: 150 +title: Shortcode +description: Learn about the available shortcodes to write new documentation. +tags: +- contribute +keywords: +- contribution +- shortcode +- writing +draft: true +--- + +To call a shortcode you need to write `{{}}`. + +## Alert shortcode + +Use the `alert` shortcode when you want to outline something in particular. The first parameter is the level of the alert, the second is an optional title. Everything inside the shortcode will be the message. The list of alert level is available on [Bootstrap documentation](https://getbootstrap.com/docs/4.0/components/alerts/). + +Here's an example for a warning alert: + +```go +{{}} +This is the message of the warning. +{{}}. +``` + +This will render: + +{{< callout type="warning" >}} +This is the message of the warning. +{{< /callout >}}. + +## image shortcode + +Use the `image` shortcode if you want to embed an image. The first parameter is the link to the image. The second is the title/caption of the image. + +```go +{{}} +``` + +## readfile shortcode + +Use the `readfile` shortcode to include a partial document in your content. It acts as a templating solution to enable reuse of common content. + +```go +{{}} +``` + +It's possible to search and replace variable during templating. Make sure you have a dictionary called `str_replace_dict` in the frontmatter section of the page. + +```go +str_replace_dict: + "@application-type@": "Go" +``` + +## githubReadme shortcode + +Use the `githubReadme` shortcode to embed the Readme of an existing Github project in a page. The first parameter is the group and name of the repository. + +This shortcode will embed the clever-tools readme. + +```go +{{}} +``` + +## tooltip shortcode + +Use the `tooltip` shortcode to provide a definition of the a term in a tooltip. All terms definitions are fetched from the glossary under `/data/glossary.json`. +the `title` parameter is the identifier of the object from `glossary.json`. + +This tooltip + +```go +{{}}PaaS{{}} +``` + +will produce {{< tooltip title="paas" >}}PaaS{{< /tooltip >}} + +## ref shortcode + +This is a default Hugo shortcode to link to another content page. + +This will output the relative link to the common configuration page: `reference/common-configuration/#private-ssh-key` + +```go +{{}} +``` diff --git a/drafts/ssh-access.md b/drafts/ssh-access.md new file mode 100644 index 000000000..65b31e04f --- /dev/null +++ b/drafts/ssh-access.md @@ -0,0 +1,86 @@ +--- +type: docs +title: SSH access +weight: 5 +description: SSH access to running instances +tags: +- cli +- reference +keywords: +- ssh +- shell +- console +aliases: +- /doc/administrate/clever-tools/ssh-access +draft: true +--- + +While direct SSH access to instances is not recommended in an [immutable infrastructure](https://boxfuse.com/blog/no-ssh.html) setup, it can be useful for debugging purposes. Clever Cloud allows you to connect to running instances via SSH. + +{{< callout type="warning" >}} +Clever Cloud instances are to be seen as *read-only* resources. Any change made on an instance **will not be persisted**. You can use SSH access for quick tests, but if you want to persist changes, you need to commit them in your repository. Changes made on instances are not kept across deployments. +{{< /callout >}} + +{{< callout type="info" >}} +SSH on docker instances will attach to the running container. You must have `/bin/bash` installed (usually from the `bash` package) otherwise attaching to the container will fail. +{{< /callout >}} + +## Requirements + +You need to have the Clever Tools CLI installed locally. + +[//]: # (ref "/doc/quickstartclever-tools-intro") + +### Make sure you have a properly configured SSH key + +To use SSH access, you need to have an SSH key properly configured in your Clever Cloud account. Please refer to [the SSH keys section of the documentation](/developers/doc/account/ssh-keys-management) to know how to set up your SSH keys. + +## Accessing your machine with Clever Tools CLI + +In order to access the machine via SSH using the Clever Tools CLI + +[//]: # (ref "/doc/quickstartclever-tools-intro) + +you need to have an application running on Clever Cloud and have linked it with your local repository using the Clever Tools CLI with `clever link --org ` + +### Accessing your machine + +You can access running instances of a linked application with `$ clever ssh` in the linked application's repository locally. + +```shell +$ clever ssh +> Opening an ssh shell +> bas@67fbf787-3518-47bb-abd9-2c2575844edd ~ $ +``` + +If multiple instances are running, you will be asked which one to use: + +```shell +$ clever ssh +> 1) Sleepy Ponita - Instance 0 - UP (11281f38-31ff-43a7-8595-a2d82630c32b) +> 2) Tense Caterpie - Instance 1 - UP (b10d19d9-5238-408b-b038-3e32c7a301c2) +> Your choice: 1 +> Opening an ssh shell +> bas@11281f38-31ff-43a7-8595-a2d82630c32b ~ $ +``` + +You are now connected to the machine. + +### Note for Windows users + +`$ clever ssh` command will fail on PowerShell or cmd.exe if there is no `ssh.exe` in your path. +The most straightforward solution is to start `$ clever ssh` from `git-bash` but you can also add `ssh.exe` in your path.. + +## Access your application's folder + +No matter wich way you've decided to use to SSH to the machine, your application's folder is located at: `/home/bas/`. + +## Show your application's logs + +If you want to show your application's logs while you debug: + +```shell +journalctl -efa -u bas-deploy.service +``` + +You can also use `journalctl` [with other options](https://www.commandlinux.com/man-page/man1/journalctl.1.html) if you need to. diff --git a/go.mod b/go.mod new file mode 100644 index 000000000..323e04025 --- /dev/null +++ b/go.mod @@ -0,0 +1,5 @@ +module github.com/CleverCloud/documentation + +go 1.24.0 + +require github.com/imfing/hextra v0.9.7 // indirect diff --git a/go.sum b/go.sum new file mode 100644 index 000000000..8501da6f6 --- /dev/null +++ b/go.sum @@ -0,0 +1,2 @@ +github.com/imfing/hextra v0.9.7 h1:Zg5n24us36Bn/S/5mEUPkRW6uwE6vHHEqWSgN0bPXaM= +github.com/imfing/hextra v0.9.7/go.mod h1:cEfel3lU/bSx7lTE/+uuR4GJaphyOyiwNR3PTqFTXpI= diff --git a/hugo.yaml b/hugo.yaml new file mode 100644 index 000000000..4270afec3 --- /dev/null +++ b/hugo.yaml @@ -0,0 +1,196 @@ +baseURL: https://www.clever.cloud/developers +title: Clever Cloud Documentation +publishDir: public/developers + +module: + imports: + - path: github.com/imfing/hextra + hugoVersion: + extended: true + min: 0.146.0 + +enableEmoji: true +enableGitInfo: true +enableInlineShortcodes: true +hasCJKLanguage: true + +languageCode: en-US + +markup: + highlight: + noClasses: false + goldmark: + renderer: + unsafe: true + extensions: + passthrough: + delimiters: + block: [['\[', '\]'], ['$$', '$$']] + inline: [['\(', '\)']] + enable: true + +menu: + main: + - identifier: documentation + name: Documentation + pageRef: /doc/ + weight: 1 + - identifier: tutorials + name: Guides + pageRef: /guides/ + weight: 2 + - identifier: api + name: API + pageRef: /api/ + weight: 3 + - identifier: changelog + name: Changelog + pageRef: /changelog/ + weight: 4 + - identifier: components + name: Web Components + url: https://www.clever.cloud/developers/clever-components/ + weight: 5 + - name: Search + weight: 6 + params: + type: search + - name: GitHub + weight: 7 + url: https://github.com/CleverCloud/documentation/ + params: + icon: github + - name: Website + weight: 8 + url: https://clever-cloud.com/ + params: + icon: globe-alt + + sidebar: + - identifier: more + name: References + params: + type: separator + weight: 1 + - identifier: tips_and_tricks + name: Tips & Tricks + url: /doc/best-practices/tips_and_tricks/ + weight: 2 + - identifier: cli + name: Clever Tools CLI + url: /doc/reference/cli/ + weight: 3 + - identifier: envar + name: Environment Variables + pageRef: /doc/reference/reference-environment-variables + weight: 4 + - identifier: common + name: Common Configuration + pageRef: /doc/develop/common-configuration/ + weight: 5 + - identifier: postmortem + name: Postmortem + pageRef: /postmortem/ + weight: 6 + +outputs: + home: [HTML, LLMS] + page: [HTML, Markdown] + section: [HTML, Markdown, RSS] + +outputFormats: + LLMS: + mediaType: text/plain + baseName: llms + isPlainText: true + + Markdown: + baseName: index.html + +pagination: + pagerSize: 21 # Number of entries in Changelog section before pagination + +params: + blog: + list: + displayTags: true + # date | lastmod | publishDate | title | weight + sortBy: date + sortOrder: desc # or "asc" + + article: + displayPagination: true + + comments: + enable: false + type: giscus + # https://giscus.app/ + giscus: + repo: cnivolle/doc.clever-cloud.com + repoId: R_kgDOJ9fJag + category: General + categoryId: DIC_kwDOJ9fJas4CY7gW + mapping: pathname + # strict: 0 + # reactionsEnabled: 1 + # emitMetadata: 0 + # inputPosition: top + # lang: en + + description: Clever Cloud is a Platform-as-a-Service (PaaS) cloud provider, an automated hosting platform for developers. Deploy your app easily and launch dependencies without having to worry about the infrastructure set up. + + displayUpdatedDate: true + dateFormat: January 2, 2006 + + editURL: + enable: true + base: https://github.com/CleverCloud/documentation/edit/main/content/ + + footer: + enable: false + displayCopyright: false + displayPoweredBy: false + width: normal + + highlight: + copy: + enable: true + # hover | always + display: hover + + images: + - images/feature.png + + navbar: + displayTitle: false + displayLogo: true + logo: + path: images/logo.svg + dark: images/logo-dark.svg + link: /developers + width: 175 + + page: + # full (100%), wide (90rem), normal (1280px) + width: full + + search: + enable: true + type: flexsearch + + docsearch: + appId: RCNP6XZZWS + apiKey: 6909e93402b6d4522a90f43ad144e233 + indexName: documentation clever + + toc: + displayTags: true + + theme: + # light | dark | system + default: system + displayToggle: true + +privacy: + youtube: + privacyEnhanced: true \ No newline at end of file diff --git a/layouts/404.html b/layouts/404.html new file mode 100644 index 000000000..d56665df9 --- /dev/null +++ b/layouts/404.html @@ -0,0 +1,35 @@ +{{ define "main" }} +
+
+
+
+ Clever Cloud 404 Logo +

+ 404 +

+

+ The page you are looking for doesn't exist +

+ + Go to the documentation home page + +
+ {{ partial "components/pager.html" . }} + {{ partial "components/comments.html" . }} +
+
+ +
+ +{{ end }} diff --git a/layouts/_default/list.md b/layouts/_default/list.md new file mode 100644 index 000000000..71828b22e --- /dev/null +++ b/layouts/_default/list.md @@ -0,0 +1 @@ +{{ partial "markdown/include_entrypoint.md" .RawContent | htmlUnescape }} diff --git a/layouts/_default/single.md b/layouts/_default/single.md new file mode 100644 index 000000000..71828b22e --- /dev/null +++ b/layouts/_default/single.md @@ -0,0 +1 @@ +{{ partial "markdown/include_entrypoint.md" .RawContent | htmlUnescape }} diff --git a/layouts/changelog/list.html b/layouts/changelog/list.html new file mode 100644 index 000000000..f0719889d --- /dev/null +++ b/layouts/changelog/list.html @@ -0,0 +1,84 @@ +{{ define "main" }} + {{- $newFeature := (T "newFeature") | default "New" -}} {{/* i18n for strings */}} + {{- $nextPage := (T "nextPage") | default "Next" -}} + {{- $previousPage := (T "previousPage") | default "Previous" -}} +
+ {{ partial "sidebar.html" (dict "context" . "disableSidebar" true "displayPlaceholder" true) }} +
+
+
+

+ {{ .Title }} +

+
+ {{ .Content }} +
+ {{ $paginator := .Paginate (where .Data.Pages "Type" "changelog") }} + {{ range $paginator.Pages.GroupByDate "January, 2006" }} +

+ + {{- partial "utils/icon.html" (dict "name" "clock" "attributes" "height=24") -}} + + {{ .Key }} +

+ {{ range .Pages }} +
+

+ + + {{ .Title }} + {{ if in .Params.categories "new" }} {{/* Show a label "new" if category is set to "new"*/}} + + {{- $newFeature -}} + + {{- end -}} + +

+ {{/* Show date */}} + {{ .Date | time.Format "2006-01-02" }} + + {{- if site.Params.blog.list.displayTags -}} {{/* Show tags */}} + {{ with .Params.tags }} + + {{- range . }}#{{ . }}{{ end -}} + + {{ end -}} + {{- end -}} +
+ {{ end }} + {{ end }} + {{/* pagination system */}} +
{{/* Hides pagnination separator if no pages */}} + {{ if $paginator.HasPrev }} + + + {{- partial "utils/icon.html" (dict "name" "chevron-right" "attributes" "class=\"hx-inline hx-h-5 hx-shrink-0 ltr:hx-rotate-180\"") -}} + {{- $previousPage -}} + + + {{ end }} + {{ if $paginator.HasNext }} + + + {{- $nextPage -}} + {{- partial "utils/icon.html" (dict "name" "chevron-right" "attributes" "class=\"hx-inline hx-h-5 hx-shrink-0\"") -}} + + {{ end }} +
+
+
+
+
+{{ end }} + diff --git a/layouts/changelog/single.html b/layouts/changelog/single.html new file mode 100644 index 000000000..4524ef72f --- /dev/null +++ b/layouts/changelog/single.html @@ -0,0 +1,49 @@ +{{ define "main" }} + {{- $effectiveOn := (T "effectiveOn") | default "Effective on " -}} {{/* i18n for strings */}} +
+ {{ partial "sidebar.html" (dict "context" . "disableSidebar" true "displayPlaceholder" false) }} + {{ partial "toc.html" . }} +
+
+ {{ partial "breadcrumb.html" . }} +

{{ .Title }}

+
+ {{- with $date := .Date }}{{ $effectiveOn }}{{ partial "utils/format-date" $date}}{{ end -}} + {{- $lazyLoading := site.Params.enableImageLazyLoading | default true -}} + {{ if and .Date .Params.authors }}·{{ end -}} + {{- with $.Params.authors -}} + {{- range $i, $author := . -}} + {{- if reflect.IsMap $author -}} + {{- if and $i (not $author.image) }},{{ end -}} + + {{- with $image := $author.image }} + {{- $isLocal := not (urls.Parse $image).Scheme -}} + {{- $startsWithSlash := hasPrefix $image "/" -}} + {{- if and $isLocal $startsWithSlash }} + {{- $image = (relURL (strings.TrimPrefix "/" $image)) -}} + {{ end -}} + {{ $author.name }} + {{ end -}} +
{{ $author.name }}
+ + {{- else -}} + {{- if $i }},{{ end -}}{{ $author }} + {{- end -}} + {{- end -}} + {{- end -}} +
+
+ {{ .Content }} +
+ {{ partial "components/last-updated.html" . }} + {{ .Scratch.Set "reversePagination" true }} + {{ partial "components/pager.html" . }} + {{ partial "components/comments.html" . }} +
+
+
+{{ end }} \ No newline at end of file diff --git a/layouts/docs/single.html b/layouts/docs/single.html new file mode 100644 index 000000000..0037a7c38 --- /dev/null +++ b/layouts/docs/single.html @@ -0,0 +1,19 @@ +{{ define "main" }} +
+ {{ partial "sidebar.html" (dict "context" .) }} + {{ partial "toc.html" . }} +
+
+ {{ partial "breadcrumb.html" . }} +
+

{{ .Title }}

+ {{ .Content }} +
+ {{ partial "components/last-updated.html" . }} + {{ partial "components/feedback.html" . }} + {{ partial "components/pager.html" . }} + {{ partial "components/comments.html" . }} +
+
+
+{{ end }} \ No newline at end of file diff --git a/layouts/hextra-home.llms.txt b/layouts/hextra-home.llms.txt new file mode 100644 index 000000000..532a59554 --- /dev/null +++ b/layouts/hextra-home.llms.txt @@ -0,0 +1,52 @@ +{{- if eq .Kind "home" -}} +# {{ .Site.Title }} + +> {{ .Site.Params.description }} + +{{- $mainSections := where .Site.Sections "Type" "docs" -}} +{{- $sortedSections := sort $mainSections "Title" }} +{{- range $sortedSections }} +{{- if and (not .Params.llmsTxtOptional) (gt (len .Pages) 0) }} +{{- $allSections := slice . -}} +{{- range .Sections -}} +{{- if not .Params.llmsTxtOptional -}} +{{- $allSections = $allSections | append . -}} +{{- end -}} +{{- end -}} +{{- $sortedAllSections := sort $allSections "Title" -}} +{{- range $sortedAllSections }} + +{{- if and (gt (len .Pages) 0) (not (strings.Contains .Title "Postmortem" )) }} + +## {{ .Title }} +{{- $pages := sort .Pages "Title" "asc" }} +{{- range $pages }} +{{- if not (strings.Contains .RelPermalink "/api/v2") }} +- [{{ .Title }}](https://www.clever-cloud.com{{ .RelPermalink }}index.html.md){{ with .Description }}: {{ . }}{{ end }} +{{- end }} +{{- end }} +{{- end }} +{{- end }} +{{- end }} +{{- end }} + +## Optional +{{- range $mainSections }} +{{- if .Params.llmsTxtOptional }} +{{- $pages := sort .Pages "Title" "asc" }} +{{- range $pages }} +- [{{ .Title }}](https://www.clever-cloud.com{{ .RelPermalink }}index.html.md){{ with .Description }}: {{ . }}{{ end }} +{{- end }} +{{- end }} +{{- range .Sections }} +{{- if .Params.llmsTxtOptional }} +{{- $pages := sort .Pages "Title" "asc" }} +{{- range $pages }} +- [{{ .Title }}]({{ .RelPermalink }}index.html.md){{ with .Description }}: {{ . }}{{ end }} +{{- end }} +{{- end }} +{{- end }} +{{- end }} +{{- else -}} +{{- .RawContent | .Page.RenderString -}} +{{- end -}} diff --git a/layouts/openapi/baseof.html b/layouts/openapi/baseof.html new file mode 100644 index 000000000..1e29abff9 --- /dev/null +++ b/layouts/openapi/baseof.html @@ -0,0 +1,12 @@ + + + {{- partial "openapi/head_openapi" . -}} + + {{- partial "navbar.html" . -}} + {{- block "main" . }}{{ end -}} + {{- if or (eq .Site.Params.footer.enable nil) (.Site.Params.footer.enable) }} + {{ partial "footer.html" . }} + {{ end }} + + {{ partial "scripts.html" . }} + \ No newline at end of file diff --git a/layouts/openapi/single.html b/layouts/openapi/single.html new file mode 100644 index 000000000..2830ebcc8 --- /dev/null +++ b/layouts/openapi/single.html @@ -0,0 +1,55 @@ +{{ define "main" }} +
+ {{ partial "sidebar.html" (dict "context" . "disableSidebar" true "displayPlaceholder" false) }} +
+
+
+ {{ .Content }} +
+ + + +
+
+
+{{ end }} diff --git a/layouts/partials/components/feedback.html b/layouts/partials/components/feedback.html new file mode 100644 index 000000000..a34aa3e38 --- /dev/null +++ b/layouts/partials/components/feedback.html @@ -0,0 +1,42 @@ +
+

Did this documentation help you ?

+
+

+ + +

+

+ + + + \ No newline at end of file diff --git a/layouts/partials/custom/head-end.html b/layouts/partials/custom/head-end.html new file mode 100644 index 000000000..c19b462ff --- /dev/null +++ b/layouts/partials/custom/head-end.html @@ -0,0 +1,2 @@ +{{/* Load Algolia DocSearch (project-level partial) */}} +{{ partial "docsearch.html" . }} diff --git a/layouts/partials/docsearch.html b/layouts/partials/docsearch.html new file mode 100644 index 000000000..05813b376 --- /dev/null +++ b/layouts/partials/docsearch.html @@ -0,0 +1,28 @@ + + + +{{ $docSearchCSS := resources.Get "css/docsearch.css" }} +{{ if $docSearchCSS }} + {{ $docSearchCSS = $docSearchCSS | minify }} + +{{ end }} + + + + + + + + + +{{ $docSearchJS := resources.Get "js/docsearch.js" }} +{{ if $docSearchJS }} + {{ $docSearchJS = $docSearchJS | minify }} + +{{ end }} diff --git a/layouts/partials/markdown/include_entrypoint.md b/layouts/partials/markdown/include_entrypoint.md new file mode 100644 index 000000000..c109cc548 --- /dev/null +++ b/layouts/partials/markdown/include_entrypoint.md @@ -0,0 +1,5 @@ +{{- $content := . -}} +{{- $content = partial "markdown/include_shortcode_content.md" $content -}} +{{- $content = partial "markdown/include_runtimes_versions.md" $content -}} +{{- $content = partial "markdown/include_software_versions_shared_dedicated.md" $content -}} +{{ $content }} diff --git a/layouts/partials/markdown/include_runtimes_versions.md b/layouts/partials/markdown/include_runtimes_versions.md new file mode 100644 index 000000000..eb6097c26 --- /dev/null +++ b/layouts/partials/markdown/include_runtimes_versions.md @@ -0,0 +1,32 @@ +{{- $content := . -}} +{{- $runtimesPattern := "\\{\\{<\\s*runtimes_versions\\s+([^>]+)\\s*>\\}\\}" -}} + +{{- range $runtimeFound := findRE $runtimesPattern $content -}} + {{- $runtime := replaceRE $runtimesPattern "$1" $runtimeFound -}} + {{- $runtime = trim $runtime " " -}} + {{- $versions := index site.Data.runtime_versions $runtime -}} + {{- $output := "" -}} + {{- with $versions -}} + {{- if .default -}} + {{- $output = printf "%s### Default version\n" $output -}} + {{- range .default -}} + {{- $output = printf "%s- %s\n" $output . -}} + {{- end -}} + {{- end -}} + + {{- if .accepted -}} + {{- $output = printf "%s\n### Accepted version(s)\n" $output -}} + {{- range .accepted -}} + {{- $output = printf "%s- %s\n" $output . -}} + {{- end -}} + {{- end -}} + + {{- if .eol_source -}} + {{- $output = printf "%s\nCheck the [end-of-life (EOL)](%s) status of these versions." $output .eol_source -}} + {{- end -}} + {{- end -}} + + {{- $content = replace $content $runtimeFound $output -}} +{{- end -}} + +{{- return $content -}} diff --git a/layouts/partials/markdown/include_shortcode_content.md b/layouts/partials/markdown/include_shortcode_content.md new file mode 100644 index 000000000..4b92b0877 --- /dev/null +++ b/layouts/partials/markdown/include_shortcode_content.md @@ -0,0 +1,12 @@ +{{- $content := . -}} +{{- $pattern := "\\{\\{%\\s*content\\s+\"(?P[^\"]+)\"\\s*%\\}\\}" -}} + +{{- range $shortcodeFound := findRE $pattern $content -}} + {{- $name := replaceRE $pattern "${name}" $shortcodeFound -}} + {{- $filepath := printf "layouts/shortcodes/content/%s.md" $name -}} + {{- with os.ReadFile $filepath -}} + {{- $content = replace $content $shortcodeFound . -}} + {{- end -}} +{{- end -}} + +{{- return $content -}} diff --git a/layouts/partials/markdown/include_software_versions_shared_dedicated.md b/layouts/partials/markdown/include_software_versions_shared_dedicated.md new file mode 100644 index 000000000..2c7f7a415 --- /dev/null +++ b/layouts/partials/markdown/include_software_versions_shared_dedicated.md @@ -0,0 +1,23 @@ +{{- $content := . -}} +{{- $versionsPattern := "\\{\\{<\\s*software_versions_shared_dedicated\\s+([^>]+)\\s*>\\}\\}" -}} + +{{- range $versionFound := findRE $versionsPattern $content -}} + {{- $dbname := replaceRE $versionsPattern "$1" $versionFound -}} + {{- $versions := index site.Data.software_versions_shared_dedicated $dbname -}} + {{- $output := "### Regular versions\n" -}} + {{- with $versions.dedicated -}} + {{- range . -}} + {{- $output = printf "%s- %s\n" $output . -}} + {{- end -}} + {{- end -}} + {{- if $versions.dev -}} + {{- $output = printf "%s\n### DEV plan\n" $output -}} + {{- range $versions.dev -}} + {{- $output = printf "%s- %s\n" $output . -}} + {{- end -}} + {{- $output = printf "%s\n%s" $output site.Data.software_versions_shared_dedicated.dev_message -}} + {{- end -}} + {{- $content = replace $content $versionFound $output -}} +{{- end -}} + +{{- return $content -}} diff --git a/layouts/partials/openapi/head_openapi.html b/layouts/partials/openapi/head_openapi.html new file mode 100644 index 000000000..a05538d66 --- /dev/null +++ b/layouts/partials/openapi/head_openapi.html @@ -0,0 +1,60 @@ + + + + {{ if hugo.IsProduction -}} + + {{ else -}} + + {{ end -}} + {{ partialCached "favicons.html" . }} + + {{- if .IsHome -}} + {{ .Site.Title -}} + {{ else -}} + {{ with .Title }}{{ . }} – {{ end -}} + {{ .Site.Title -}} + {{ end -}} + + + + {{ partial "opengraph.html" . }} + {{ template "_internal/schema.html" . -}} + {{ template "_internal/twitter_cards.html" . -}} + + {{ partialCached "head-css.html" . }} + + + + {{- if and .Site.Config.Services.GoogleAnalytics.ID (eq hugo.Environment "production") }} + + {{ partial "google-analytics.html" . }} + {{- end }} + + + + {{ partial "custom/head-end.html" . }} + + + diff --git a/layouts/postmortem/list.html b/layouts/postmortem/list.html new file mode 100644 index 000000000..fec603566 --- /dev/null +++ b/layouts/postmortem/list.html @@ -0,0 +1,78 @@ +{{ define "main" }} + {{- $nextPage := (T "nextPage") | default "Next" -}} + {{- $previousPage := (T "previousPage") | default "Previous" -}} +
+ {{ partial "sidebar.html" (dict "context" . "disableSidebar" false "displayPlaceholder" false) }} +
+
+ {{ partial "breadcrumb.html" . }} +

+ {{ .Title }} +

+
+ {{ .Content }} +
+ {{ $paginator := .Paginate (where .Data.Pages "Type" "postmortem") }} + {{ range $paginator.Pages.GroupByDate "January, 2006" }} +

+ + {{- partial "utils/icon.html" (dict "name" "clock" "attributes" "height=24") -}} + + {{ .Key }} +

+ {{ range .Pages }} +
+

+ + + {{ .Title }} + +

+ {{/* Show date */}} + {{ .Date | time.Format "2006-01-02" }} + + {{- if site.Params.blog.list.displayTags -}} {{/* Show tags */}} + {{ with .Params.tags }} + + {{- range . }}#{{ . }}{{ end -}} + + {{ end -}} + {{- end -}} +
+ {{ end }} + {{ end }} + {{/* pagination system */}} +
{{/* Hides pagnination separator if no pages */}} + {{ if $paginator.HasPrev }} + + + {{- partial "utils/icon.html" (dict "name" "chevron-right" "attributes" "class=\"hx-inline hx-h-5 hx-shrink-0 ltr:hx-rotate-180\"") -}} + {{- $previousPage -}} + + + {{ end }} + {{ if $paginator.HasNext }} + + + {{- $nextPage -}} + {{- partial "utils/icon.html" (dict "name" "chevron-right" "attributes" "class=\"hx-inline hx-h-5 hx-shrink-0\"") -}} + + {{ end }} +
+
+
+
+
+{{ end }} + diff --git a/layouts/postmortem/single.html b/layouts/postmortem/single.html new file mode 100644 index 000000000..0037a7c38 --- /dev/null +++ b/layouts/postmortem/single.html @@ -0,0 +1,19 @@ +{{ define "main" }} +
+ {{ partial "sidebar.html" (dict "context" .) }} + {{ partial "toc.html" . }} +
+
+ {{ partial "breadcrumb.html" . }} +
+

{{ .Title }}

+ {{ .Content }} +
+ {{ partial "components/last-updated.html" . }} + {{ partial "components/feedback.html" . }} + {{ partial "components/pager.html" . }} + {{ partial "components/comments.html" . }} +
+
+
+{{ end }} \ No newline at end of file diff --git a/layouts/shortcodes/callout.html b/layouts/shortcodes/callout.html new file mode 100644 index 000000000..ade650198 --- /dev/null +++ b/layouts/shortcodes/callout.html @@ -0,0 +1,37 @@ +{{ $calloutEmojiDict := dict "info" "ℹ️" "warning" "⚠️" "error" "🚫" }} +{{ $type := .Get "type" | default "default" }} +{{/* If emoji is not set, use the emoji from dict */}} +{{ $emoji := .Get "emoji" }} +{{ if eq $emoji "" }} + {{ $emoji = index $calloutEmojiDict $type }} +{{ end }} +{{/* Also allow using "icon" */}} +{{ $icon := .Get "icon" }} + +{{ $defaultClass := "callout hx-bg-gray-100 hxtext-gray-800 dark:hx-border-blue-200/30 dark:hx-bg-neutral-800 dark:hx-text-blue-200"}} +{{ $infoClass := "hx-border-blue-200 hx-bg-blue-100 hx-text-blue-900 dark:hx-border-blue-200/30 dark:hx-bg-blue-900/30 dark:hx-text-blue-200" }} +{{ $warningClass := "hx-border-yellow-100 hx-bg-yellow-50 hx-text-yellow-900 dark:hx-border-yellow-200/30 dark:hx-bg-yellow-700/30 dark:hx-text-yellow-200" }} +{{ $errorClass := "hx-border-red-200 hx-bg-red-100 hx-text-red-900 dark:hx-border-red-200/30 dark:hx-bg-red-900/30 dark:hx-text-red-200" }} + +{{ $class := cond (eq $type "info") $infoClass (cond (eq $type "warning") $warningClass (cond (eq $type "error") $errorClass $defaultClass)) }} + + +
+
+ {{- with $emoji -}} +
+ {{ . }} +
+ {{- else -}} + {{- with $icon }} + {{ partial "utils/icon.html" (dict "name" . "attributes" `height=1.2em class="hx-inline-block hx-align-middle"`) -}} + {{- end -}} + {{- end -}} +
+ +
+
+ {{ .InnerDeindent | markdownify }} +
+
+
\ No newline at end of file diff --git a/layouts/shortcodes/content-raw.html b/layouts/shortcodes/content-raw.html new file mode 100644 index 000000000..578bea842 --- /dev/null +++ b/layouts/shortcodes/content-raw.html @@ -0,0 +1,9 @@ +{{- $file := .Get 0 -}} +{{- if $file -}} + {{- $content := readFile (printf "shared/%s.md" $file) | safeHTML -}} + {{- if $content -}} + {{- .Page.RenderString $content -}} + {{- else -}} + {{- warnf "Content not found: %s" $file -}} + {{- end -}} +{{- end -}} diff --git a/layouts/shortcodes/content.html b/layouts/shortcodes/content.html new file mode 100644 index 000000000..4600ad743 --- /dev/null +++ b/layouts/shortcodes/content.html @@ -0,0 +1,9 @@ +{{- $file := .Get 0 -}} +{{- if $file -}} + {{- $content := readFile (printf "shared/%s.md" $file) | safeHTML -}} + {{- if $content -}} + {{- $content -}} + {{- else -}} + {{- warnf "Content not found: %s" $file -}} + {{- end -}} +{{- end -}} diff --git a/layouts/shortcodes/hero-button-primary.html b/layouts/shortcodes/hero-button-primary.html new file mode 100644 index 000000000..87ace330c --- /dev/null +++ b/layouts/shortcodes/hero-button-primary.html @@ -0,0 +1,15 @@ +{{- $link := .Get "link" -}} +{{- $text := .Get "text" -}} +{{- $style := .Get "style" -}} + +{{- $external := hasPrefix $link "http" -}} +{{- $href := cond (hasPrefix $link "/") ($link | relURL) $link -}} + + + {{- $text -}} + \ No newline at end of file diff --git a/layouts/shortcodes/hero-button-secondary.html b/layouts/shortcodes/hero-button-secondary.html new file mode 100644 index 000000000..3ba48ec68 --- /dev/null +++ b/layouts/shortcodes/hero-button-secondary.html @@ -0,0 +1,15 @@ +{{- $link := .Get "link" -}} +{{- $text := .Get "text" -}} +{{- $style := .Get "style" -}} + +{{- $external := hasPrefix $link "http" -}} +{{- $href := cond (hasPrefix $link "/") ($link | relURL) $link -}} + + + {{- $text -}} + \ No newline at end of file diff --git a/layouts/shortcodes/imgproc.html b/layouts/shortcodes/imgproc.html new file mode 100644 index 000000000..b5233ade1 --- /dev/null +++ b/layouts/shortcodes/imgproc.html @@ -0,0 +1,60 @@ +{{- $context := . -}} +{{- $caption := .Get "caption" -}} +{{- $image := .Get "image" -}} +{{- $width := 0 -}} +{{- $height := 0 -}} +{{- $imageStyle := .Get "imageStyle" -}} + +{{/* Image processing options */}} +{{- $method := .Get "method" | default "Resize" | humanize -}} +{{- $options := .Get "options" | default "900x webp q95" -}} + +{{- if and $image (not (urls.Parse $image).Scheme) -}} + {{/* Process images in assets */}} + {{- with resources.Get $image -}} + {{- $processed := "" -}} + {{- if eq $method "Resize" -}} + {{- $processed = (.Resize $options) -}} + {{- else if eq $method "Fit" -}} + {{- $processed = (.Fit $options) -}} + {{- else if eq $method "Fill" -}} + {{- $processed = (.Fill $options) -}} + {{- else if eq $method "Crop" -}} + {{- $processed = (.Crop $options) -}} + {{- else -}} + {{- errorf "Invalid image processing command: Must be one of Crop, Fit, Fill or Resize." -}} + {{- end -}} + {{- $width = $processed.Width -}} + {{- $height = $processed.Height -}} + {{- $image = $processed.RelPermalink -}} + {{- else -}} + {{/* Otherwise, use relative link of the image */}} + {{- if hasPrefix $image "/" -}} + {{- $image = relURL (strings.TrimPrefix "/" $image) -}} + {{- end -}} + {{- end -}} +{{- end -}} + + + + +{{- $padding := "p-4" -}} +{{- with $caption -}} + {{- $padding = "pt-4 px-4" -}} +{{- end -}} + +{{- with $caption -}} +
{{- $caption | markdownify -}}
+{{- end -}} + + \ No newline at end of file diff --git a/layouts/shortcodes/runtimes_versions.html b/layouts/shortcodes/runtimes_versions.html new file mode 100644 index 000000000..beea16c45 --- /dev/null +++ b/layouts/shortcodes/runtimes_versions.html @@ -0,0 +1,50 @@ +{{ $software := or (.Get 0) }} +{{ $version_list := .Site.Data.runtime_versions }} + +{{ with index $version_list $software }} + {{ $default := .default | default (slice) }} + {{ $accepted := .accepted | default (slice) }} + {{ $default_len := len $default }} + {{ $accepted_len := len $accepted }} + {{ $max_len := $default_len }} + {{ if gt $accepted_len $default_len }} + {{ $max_len = $accepted_len }} + {{ end }} + + + + + {{ if $default_len }} + + {{ end }} + {{ if $accepted_len }} + + {{ end }} + + + + {{ range $i := seq 0 (sub $max_len 1) }} + + {{ if $default_len }} + + {{ end }} + {{ if $accepted_len }} + + {{ end }} + + {{ end }} + +
Default VersionAccepted Versions
+ {{ with index $default $i }} + {{ . }} + {{ else }} + {{ end }} + + {{ with index $accepted $i }} + {{ . }} + {{ else }} + + {{ end }} +
+

The end-of-life (EOL) versions are marked as such.

+{{ end }} diff --git a/layouts/shortcodes/software_versions_shared_dedicated.html b/layouts/shortcodes/software_versions_shared_dedicated.html new file mode 100644 index 000000000..bc603414e --- /dev/null +++ b/layouts/shortcodes/software_versions_shared_dedicated.html @@ -0,0 +1,38 @@ +{{ $software := or (.Get 0) }} +{{ $version_list := .Site.Data.software_versions_shared_dedicated }} +{{ $software_versions := index $version_list $software }} +{{ $has_dev := false }} + +{{ if $software_versions.dev }} + {{ $has_dev = true }} +{{ end }} + + + + + {{ if $has_dev }} + + {{ end }} + + + + {{ range $index, $dedicated_version := $software_versions.dedicated }} + + + {{ if $has_dev }} + + {{ end }} + + {{ end }} + +
DedicatedDev
{{ $dedicated_version }} + {{ with index $software_versions.dev $index }} + {{ . }} + {{ else }} + + {{ end }} +
+{{ if $has_dev }} + {{ $.Page.RenderString "{{< callout type=\"warning\">}} Important: DEV plan is free, for testing purposes only. It has lower performances and no SLA. You can find more info [in the FAQ](/developers/doc/find-help/faq/) {{< /callout >}}" | safeHTML }} +{{ end }} + diff --git a/layouts/shortcodes/tooltip.html b/layouts/shortcodes/tooltip.html new file mode 100644 index 000000000..807e5e763 --- /dev/null +++ b/layouts/shortcodes/tooltip.html @@ -0,0 +1,21 @@ +{{$title := .Get "title" }} +{{- if not $title -}} +{{- errorf "missing tooltip title" -}} +{{- end -}} +{{ .Scratch.Set "title" $title }} +{{ $def := index .Site.Data.tooltips (.Scratch.Get "title") }} + +{{- if not $def -}} +{{- errorf "%s not in tooltips" $title -}} +{{- end -}} + + +{{ if $.Site.Params.Debug }} +
+ {{ < tooltip title="{{$title}}" > }}{{ .Inner }}{{ < /tooltip > }} +
+{{ end }} +{{ .Inner }} +{{ if $.Site.Params.Debug }} +
+{{ end }} diff --git a/layouts/sitemap.xml b/layouts/sitemap.xml new file mode 100644 index 000000000..d2524f37e --- /dev/null +++ b/layouts/sitemap.xml @@ -0,0 +1,28 @@ +{{ printf "" | safeHTML }} + + {{ range .Data.Pages }} + {{- if not (or + (hasPrefix .RelPermalink "/tags") + (hasPrefix .RelPermalink "/categories") + (hasPrefix .RelPermalink "/readme")) + -}} + + {{ .Permalink }}{{ if not .Lastmod.IsZero }} + {{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}{{ end }}{{ with .Sitemap.ChangeFreq }} + {{ . }}{{ end }}{{ if ge .Sitemap.Priority 0.0 }} + {{ .Sitemap.Priority }}{{ end }}{{ if .IsTranslated }}{{ range .Translations }} + {{ end }} + {{ end }} + + {{- end -}} + {{ end }} + diff --git a/runtimes/docker/docker.md b/runtimes/docker/docker.md deleted file mode 100644 index 635b1975e..000000000 --- a/runtimes/docker/docker.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: Deploy Docker images -shortdesc: Docker is an easy, lightweight virtualized environment for portable applications. -tags: -- docker ---- - -## Deploy Docker images - -Clever Cloud allows you to deploy any application running inside a -Docker container. This page will explain how to set up your application -to run it on our service. - -
-
Note for Beta Version
-
-Docker support is still in beta. It does not yet support FS -Buckets, validation of your Dockerfile, or other advanced features. -
-
- -### Overview - -Docker is an easy, lightweight virtualized environment for portable -applications. - -Docker containers can encapsulate any payload, and will run consistently -on and between virtually any server. The same container that a developer -builds and tests on a laptop will run at scale, in production*, on VMs, -bare-metal servers, public instances, or combinations of the above. - -### Create an application - -1. Create a new app by clicking on the **Add an Application** button, in the sidebar. -2. Select a brand new instance (or a repository from GitHub if your account is linked). -3. Then select Docker in the platforms list. -4. Configure your scaling options. -5. Enter your application's name and description and click "Next". You can also select the region you want (North America or Europe). -
- -
- - -### Requirements - -Clever Cloud does not have a lot of requirements, here is what you *need* -to do to ensure that your application will run: - -* Push on the **master branch**. - -* Commit a file named **Dockerfile**, [Here is what it will look like](http://docs.docker.io/introduction/working-with-docker/#working-with-the-dockerfile "Dockerfile") - -* Listen on **port 8080**. - -### Dockerfile contents - -You can virtually put everything you want in your Dockerfile. The only -mandatory (for us) instruction to put in it is: - -```bash -CMD -``` - - * **command to run**: this is the command that starts your - application. Your application **must** listen on port 8080. It can be - easier for you to put a script in your docker image and call it with - the CMD instruction. - - -### Sample apps - -We provide a few examples of dockerized applications on Clever Cloud. - -[Elixir App](https://github.com/CleverCloud/demo-docker-elixir/blob/master/Dockerfile) -[Haskell App](https://github.com/CleverCloud/demo-haskell) -[Hack / HHVM App](https://github.com/CleverCloud/demo-hhvm) -[Seaside / Smalltalk App](https://github.com/CleverCloud/demo-seaside) -[Rust App](https://github.com/CleverCloud/demo-rust) - -### Deploying a Rust application - -To make your dockerized application run on clever Cloud, you need to: - - - expose port 8080 in your docker file - - run the application with `CMD` or `ENTRYPOINT` - -For instance, here is the `Dockerfile` used for the Rust application. - -```bash -# rust tooling is provided by `archlinux-rust` -FROM geal/archlinux-rust -MAINTAINER Geoffroy Couprie, contact@geoffroycouprie.com - -# needed by rust -ENV LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib - -# relevant files are in `./source` -ADD . /source -WORKDIR /source - -# Clever Cloud expects your app to listen on port 8080 -EXPOSE 8080 -RUN rustc -V - -# Build your application -RUN cargo build - -# Run the application with `CMD` -CMD cargo run -``` - -#### Deploying a HHVM application - -Deploying a HHVM application is a bit trickier as it needs to have both HHVM -and nginx running as daemons. To be able to have them running both, we need to -put them in a start script: - -```bash -#!/bin/sh - -hhvm --mode server -vServer.Type=fastcgi -vServer.Port=9000& - -service nginx start - -composer install - -echo "App running on port 8080" - -tail -f /var/log/hhvm/error.log -``` - -Since the two servers are running as daemons, we need to start a long-running -process. In this case we use `tail -f` - -We then add `start.sh` as the `CMD` in the `Dockerfile` - -```bash -# We need HHVM -FROM jolicode/hhvm - -# We need nginx -RUN sudo apt-get update \ - && sudo apt-get install -y nginx - -ADD . /root -RUN sudo chmod +x /root/start.sh - -# Nginx configuration -ADD hhvm.hdf /etc/hhvm/server.hdf -ADD nginx.conf /etc/nginx/sites-available/hack.conf -RUN sudo ln -s /etc/nginx/sites-available/hack.conf /etc/nginx/sites-enabled/hack.conf -# Checking nginx config -RUN sudo nginx -t - -RUN sudo chown -R www-data:www-data /root -WORKDIR /root - -# The app needs to listen on port 8080 -EXPOSE 8080 - -# Launch the start script -CMD ["sudo","/root/start.sh"] -``` diff --git a/runtimes/go/go.md b/runtimes/go/go.md deleted file mode 100644 index 9edaa3a5a..000000000 --- a/runtimes/go/go.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: Deploy Go apps -shortdesc: Go, otherwise known as Golang, is an open source, compiled, garbage-collected, concurrent system programming language. -tags: -- go ---- - -# Deploy Go applications - -Clever Cloud allows you to deploy any Go application. This page will -explain you how to set up your application to run it on our service. - -You do not need to change a lot in your application, the *requirements* will help you configure your applications with some mandatory files to add, and properties to setup. - -## Overview - -Go, otherwise known as Golang, is an open source, compiled, garbage-collected, concurrent system programming language. It was first designed and developed at Google Inc. beginning in September 2007 by Robert Griesemer, Rob Pike, and Ken Thompson. - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Necessary information - -Be sure that: - -* you push in master branch - -* your application listens to the wild network 0.0.0.0, - not only localhost or 127.0.0.1 - -* your application listens on port 8080 - -## Requirements - -Apart from listening on port 8080, there is nothing to -change on your application. - -We automatically build and run your application, as `go get myapp` would -build it. The executable is run with the application's root as its -current path. So if your application has a "static" folder at its root, it will be -accessible via "./static" in your application. - -We currently support single module applications only. That means that -your sources files just need to be at the project's root, and you can't -have multiple modules running. - -Also, the go tool requires that you put your main code in a file named `main.go`. If you -do not do that, go will generate a library and not an executable. So if you get a `Nothing -listening on port 8080`, please check that your main file is named `main.go`. - -## More configuration - -By default, we consider that your repository contains a single -application. We put your application in ${GOPATH}/src/{app_id} and then -run `go get {app_id}`. - -If you want to configure more precisely your dependencies (e.g. have -private libraries, or specific versions of some libraries), the -following will explain you how to do it: - -1. Make your repository have a GOPATH structure: - -``` haskell -./ - src/ - myapp/ - foo/ - module1/ - module2/ - module3/ -``` -
- -Here you have the modules `myapp`, `foo/module1`, `foo/module2` and `module3`. - -2. Create a *clevercloud/go.json* file at the top of your repository: - -``` haskell -./ - clevercloud/ - go.json - src/ - myapp/ - ... -``` - - -3. In the go.json file, put the following: - -```javascript -{ - "deploy": { - "appIsGoPath": true, - "main": "myapp" - } -} -``` -
- -If `appIsGoPath` is present and equals `true`, then we consider that -your repo root is the *GOPATH*. the `main` field then becomes mandatory -and must be the name of the module you want to run. e.g. if you want -to run `module1`, `main` must be `foo/module1`. - -4. (Optional) Add a "execDir" field to the "deploy" object: - -```javascript -{ - "deploy": { - "appIsGoPath": true, - "main": "myapp" - "execDir": "src/myapp" - } -} - ``` -
- - -The `execDir` value must be relative to the root of your repo. In the -example above, we will run the application in the src/myapp directory. - -## Environment injection - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -To access your variable in your application, nothing simpler! Just get -it from your environment, like you would with `PATH`: -`os.Getenv("MY_VARIABLE")`. - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via Git. Follow [these steps](/doc/clever-cloud-overview/add-application/) to deploy your application. diff --git a/runtimes/java/java-gradle.md b/runtimes/java/java-gradle.md deleted file mode 100644 index d17a17bbb..000000000 --- a/runtimes/java/java-gradle.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Gradle deployment -position: 3 -shortdesc: Gradle is a project automation tool that builds… -tags: -- java ---- - -# Deploy Gradle projects - -Clever Cloud offers you to run your Gradle projects. You can deploy this kind of project -without changing your code, but running it on Clever Cloud needs some configuration files, -to add parameters like your gradle task for example. - -## Overview - -Gradle is a project automation tool that builds upon the concepts of -Apache Ant and Apache Maven and introduces a Groovy-based -domain-specific language (DSL) instead of the more traditional XML form -of declaring the project configuration. - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Necessary information - -You *must* provide a `clevercloud/gradle.json` file (gradle.json file in -clevercloud folder which is at the root of you application) that -contains at least the following: - -```javascript -{ - "deploy": { - "goal": "grails:run" - } -} -``` - -That is the only option you really need to supply. - -## Optional configuration - -The full configuration can look like the following: - -```haskell -{ - "build": { - "type": "", - "goal": "" - }, - "deploy": { - "goal": "" - }, - "hooks": { - "postDeploy": "" - } -} -``` -You can use the following properties: - -* ``build`` - * ``"type"`` can be ``"maven"``, ``"gradle"`` or ``"ant"``. - * ``"goal"`` is the target you want to use to build your project. -* ``deploy`` - * ``"goal"`` the goal/target and options you want to execute to - deploy/run you project. (This one is mandatory.) -* ``hooks`` - * ``postDeploy`` execute a custom script after the deployment. Some frameworks or custom applications might require bootstrapping before the application may run. -You can achieve this by creating a custom script with your commands and adding the associated file name. - -## The Gradle Wrapper - -Since Gradle can come in many versions, Clever Cloud automatically support the -[Gradle Wrapper|http://www.gradle.org/docs/current/userguide/gradle_wrapper.html]: -Just create and commit the `gradlew` file and the wrapper `jar` and -`properties` files: - -```haskell -./ - clevercloud/ - gradle.json - gradlew - gradle/wrapper/ - gradle-wrapper.jar - gradle-wrapper.properties - src/ -``` - - -## Environment injection - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -For Java applications, the environment is injected in the -`System.getProperties()` object. So, to use a variable, you just do -`System.getProperties().getProperty("MY_VARIABLE")`. - -For Groovy applications, just use the `System.getProperty("MY_VARIABLE")`. - diff --git a/runtimes/java/java-jar.md b/runtimes/java/java-jar.md deleted file mode 100644 index 335b7badb..000000000 --- a/runtimes/java/java-jar.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Jar deployment -position: 3 -shortdesc: Deploy a jar on Clever Cloud... -tags: -- java ---- - -# Deploy Jar files - -Clever Cloud offers you to run any Java ARchive file. You do not -need to change your code, but running it on Clever Cloud needs some -configuration files, here is what you can do: - - * Commit and push a single jar file with all dependencies embedded; - * Commit and push your sources, let Clever Cloud build them with maven or gradle, and run the resulting jar; - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Necessary information - -You *must* provide a `clevercloud/jar.json` file (jar.json file in -clevercloud folder which is at the root of you application) that -contains at least the following: - -```javascript -{ - "deploy": { - "jarName": "path/to/jar" - } -} -``` - -That is the least you need to do. Note that `path/to/jar` *must not* -start with a `/` and that the path should be relative to your -repository's root. - -## Build options - -You do not need to build and commit a jar. Instead you can push your -sources and build them with either gradle, ant or maven. Here is the -configuration you need to provide in the `clevercloud/jar.json` file: - -```javascript -{ - "build": { - "type": "maven"|"gradle"|"ant", - "goal": "package" - } -} -``` - -The `goal` field is what will be asked to the build command, like `mvn -package` for a `maven` build with the `package` goal. - -An configuration example with a maven build that generates a jar with -embedded dependencies is: - -```javascript -{ - "build": { - "type": "maven", - "goal": "package" - }, - "deploy": { - "jarName": "target/myproject-1.0-jar-with-dependencies.jar" - } -} -``` -## More configuration - -The full configuration can look like the following: - -```haskell -{ - "build": { - "type": "", - "goal": "" - }, - "deploy": { - "jarName": "" - }, - "hooks": { - "postDeploy": "" - } -} -``` -You can use the following properties: - -* ``build`` - * ``"type"`` can be ``"maven"``, ``"gradle"`` or ``"ant"``. - * ``"goal"`` is the target you want to use to build your project. -* ``deploy`` - * ``"goal"`` the goal/target and options you want to execute to deploy/run you project. -* ``hooks`` - * ``postDeploy`` execute a custom script after the deployment. Some frameworks or custom applications might require bootstrapping before the application may run. -You can achieve this by creating a custom script with your commands and adding the associated file name. - -## Environment injection - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -For Java applications, the environment is injected in the -`System.getProperties()` object. So, to use a variable, you just do -`System.getProperties().getProperty("MY_VARIABLE")`. - -For Groovy applications, just use the `System.getProperty("MY_VARIABLE")`. diff --git a/runtimes/java/java-maven.md b/runtimes/java/java-maven.md deleted file mode 100644 index d73b4f4c4..000000000 --- a/runtimes/java/java-maven.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Java Maven -position: 3 -shortdesc: Maven is essentially a project management and comprehension tool... -tags: -- java ---- - -# Deploy Java Maven projects - -Clever Cloud offers you to run your Java Maven projects. You can deploy this kind of project without changing your code, but running it on Clever Cloud needs some configuration files, to add parameters like your targeted container for instance. - - -## Overview -Maven is essentially a project management and comprehension tool and as such provides a way to help with managing: - -* Builds -* Documentation -* Reporting -* Dependencies -* SCMs -* Releases -* Distribution - - -## About Cargo -To run your app, you can, for example, use plugins like cargo -(Find it here). -Your application must be set to listen on the port 8080. - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Necessary information - -The `clevercloud/maven.json` (maven.json file in clevercloud folder which is at the root of you application) file must contain the _goal_ field to indicate how to start your application: - -```javascript - { - "deploy": { - "goal": "yourgoal" - } - } -``` - -An example of what can be found as a goal value is: - -```haskell -"-Dtest.active=false -Dexec.mainClass=\"com.example.Main\" assembly:jar-with-dependencies exec:java" -``` - -## Optional configuration - -The full configuration can look like the following: - -```haskell -{ - "build": { - "type": "", - "goal": "" - }, - "deploy": { - "goal": "" - }, - "hooks": { - "postDeploy": "" - } -} -``` -You can use the following properties: - -* ``build`` - * ``"type"`` can be ``"maven"``, ``"gradle"`` or ``"ant"``. - * ``"goal"`` is the target you want to use to build your project. -* ``deploy`` - * ``"goal"`` the goal/target and options you want to execute to - deploy/run you project. (This one is mandatory.) -* ``hooks`` - * ``postDeploy`` execute a custom script after the deployment. Some frameworks or custom applications might require bootstrapping before the application may run. -You can achieve this by creating a custom script with your commands and adding the associated file name. - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via Git. Follow [these steps](/doc/clever-cloud-overview/add-application/) to deploy your application. diff --git a/runtimes/java/java-war.md b/runtimes/java/java-war.md deleted file mode 100644 index 0272be0a7..000000000 --- a/runtimes/java/java-war.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -title: Java War/Ear -position: 4 -shortdesc: In J2EE applications modules are packaged as EAR and WAR based on their functionality. -tags: -- java ---- - -# Deploy WAR/EAR projects - -Clever Cloud allows you to run WAR or EAR applications. You can deploy these projects without changing your code. We just need a configuration file with your targeted container. - -## Overview - -In J2EE application modules are packaged as EAR and WAR based on their functionality. - -* WAR: Web modules which contains Servlet class files, JSP FIles, supporting files, GIF and HTML files are packaged as JAR file with *.war* extension. - -* EAR: *.war* and *.jar* files are packaged as JAR file with .ear extension and deployed into Application Server. EAR file contains configuration such as application security role mapping, EJB reference mapping and context root url mapping of web modules. - -## Available containers - -The Clever Cloud supports many servlet containers. -The supported containers are listed below: - - - - - - - - - - - - - - - - - - -
ApacheJettyJbossGlassfishResin
Apache Tomcat 4.1Jetty 6.1Jboss 6.1Glassfish 3.1Resin 3.1
Apache Tomcat 5.5Jetty 7.6Jboss AS 7.1Glassfish 4.1 
Apache Tomcat 6.0Jetty 8.1   
Apache Tomcat 7.0Jetty 9.0   
Apache Tomcat 8.8    
- - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Configure your application - -
-

**Warning!**

-You **must** provide a `clevercloud/war.json` file in your application repository. -
- -### Full configuration example. - -Here's what your configuration file can look like: - -```javascript -{ - "build": { - "type": "maven", - "goal": "package" - }, - "deploy": { - "container": "TOMCAT8", - "war": [ - { - "file": "target/my-app-1.0-SNAPSHOT.war", - "context": "/app1", - "checkMe": "/app1/ping" - }, - { - "file": "my-second-app.war", - "context": "/app2", - "checkMe": "/app2/web/foobar" - } - ] - } -} -``` - -### Ok, but what does all this configuration mean? - -#### Let's start with the mandatory part: - -```javascript -{ - "deploy":{ - "container":"", - "war" : [ - { - "file":"", - "context":"/", - "checkMe":"/" - } - ] - } -} -``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
UsageFieldDescription
Required**container**Name of the container to use. Should contain one of the values in the left column of the [containers table](#available-containers) (in uppercase and all).
Required**file**Should contain the path of the war/ear file relative to your application root.
Optional**context** -
    -
  • Must start with a slash (/), can be "/".
    • -
  • Defines the base path you want your app to be under. If your app has a /foobar endpoint, it will be available under the `/{my-context}/foobar` path.
    • -
  • Not needed for an `ear` file.
    • -
  • The default value for a war is the name of the war without the extensions: helloworld-1.0.war will be deployed under the `/helloworld-1.0` context.
    • -
-
Optional**checkMe** -
    -
  • This field is recommended
    • -
  • A path to GET in order to test if the application is really running.
    • -
  • By default we will consider that the application is up if the container is up.
    • -
  • With this option, we will try to `GET /{checkMe}` for each one of your wars and consider the app down until every single checkMe path that replies a 200.
    • -
-
- -#### Build your application on Clever Cloud - -The mandatory part alone is enough… if you directly push a dry war file to deploy. You -might want to just push your code to Clever Cloud and let us build the app and generate -the war. - -That you can do, by setting the "build" field object in the `war.json` file: - -```javascript -{ - "build": { - "type": "", - "goal": "" - } -} -``` - - - - - - - - - - - - - - - - - - - - - -
UsageFieldDescription
Required**type** -
    -
  • The tool you want to use to build your app
    • -
  • Can be "maven" or "ant"
    • -
-
Required**goal** -
    -
  • -The goal you want the tool to execute. -
    • -
  • Basically, for maven, you want to put "package" in here.
    • -
-
- -#### More configuration - -Need more configuration? To run a script at the end of your deployment? To add your -private SSH key to access private dependencies? Go check the [Common configuration page](/doc/clever-cloud-overview/common-application-configuration/). - -## Available containers - -Here's the list of the configuration values for the "container" field in `war.json`: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueDescription
GLASSFISH3Use Glassfish 3.x -(see http://glassfish.java.net/)
GLASSFISH4Use Glassfish 4.x -(see http://glassfish.java.net/)
JBOSS6Use JBoss AS 6.x -(see http://www.jboss.org/jbossas)
JBOSS7Use JBoss AS 7.x -(see http://www.jboss.org/jbossas)
RESIN3Use Resin AS 3.x (see http://www.caucho.com/resin-3.1/doc/)
RESIN4Use Resin AS 4.x (see http://www.caucho.com/resin-4/doc/)
JETTY6Use Jetty servlet container 6.x (see http://jetty.codehaus.org/jetty/)
JETTY7Use Jetty servlet container 7.x (see https://www.eclipse.org/jetty/)
JETTY8Use Jetty servlet container 8.x (see https://www.eclipse.org/jetty/)
JETTY9Use Jetty servlet container 9.x (see http://www.eclipse.org/jetty/documentation/current/)
TOMCAT4Use Tomcat servlet container 4.x (see https://tomcat.apache.org/)
TOMCAT5Use Tomcat servlet container 5.x (see https://tomcat.apache.org/)
TOMCAT6Use Tomcat servlet container 6.x (see https://tomcat.apache.org/)
TOMCAT7Use Tomcat servlet container 7.x (see https://tomcat.apache.org/)
TOMCAT8Use Tomcat servlet container 8.x (see https://tomcat.apache.org/)
- -## Environment injection - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -For WAR/EAR applications, the environment is injected in the -`System.getProperties()` object. So, to use a variable, you just do -`System.getProperties().getProperty("MY_VARIABLE")`. - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via Git. Follow [these steps](/doc/clever-cloud-overview/add-application/) to deploy your application. diff --git a/runtimes/java/play-framework-1.md b/runtimes/java/play-framework-1.md deleted file mode 100644 index e5f89044d..000000000 --- a/runtimes/java/play-framework-1.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Play Framework 1 -position: 1 -shortdesc: Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller (MVC) architectural pattern. -tags: -- java ---- - -# Deploy Play Framework 1.x - -Clever Cloud supports Play 1.x applications natively. The present guide explains how to set up your application to run -on Clever Cloud. - -## Overview - -Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller -(MVC) architectural pattern. It aims to optimize developer productivity by using convention over configuration, hot code -reloading and display of errors in the browser. - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Necessary information - -* The application must be located at the **root** of the git repository. - -## Select Play! version - -Clever Cloud supports Play! **1.2** and **1.3**. You can select the Play! version for your application by creating a -`play1_version` file in the `/clevercloud` folder. - -The `play1_version` file can contain one of the following values: - -* `1.2` or `12` for **Play! 1.2**. -* `1.3` or `12` for **Play! 1.3**. - - -## Play! configuration - -By default, your application will run on Clever Cloud with the option `--%clevercloud`. -It means that you can define special keys in your `application.conf` file that will be used only on Clever Cloud. - -You can for example: - -* set production mode so the files are compiled at startup time and the errors are logged in a file: - - ```bash - %clevercloud.application.mode=prod - ``` - -* set up a mysql database - - ```bash - %clevercloud.db.url=jdbc:mysql://{yourcleverdbhost}/{dbname} - %clevercloud.db.driver=com.mysql.jdbc.Driver - %clevercloud.db.user={yourcleveruser} - %clevercloud.db.pass={yourcleverpass} - ``` - -More information on [playframework.com](http://www.playframework.com). - -## Configuration file - -You can configure your application start command by adding a `./clevercloud/play.json` file with the following fields: - -```javascript -{ - "hooks": { - "postDeploy": "pathtoyourscript" - } -} -``` - -**postDeploy**: execute a custom script after the deploy. Some frameworks or custom applications might require -bootstrapping before the application may run. You can achieve this by creating a custom script with your commands and -adding the associated file name in `clevercloud/play.json`. - -## Environment injection - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -To access the environment variables from your application, you need to -reference them in your application.conf file: -you just have to put `my.option=${MY_VARIABLE}` in your application.conf file, and then use -the configuration item `my.option` in your application. - -So for an application using the MySQL add-on, you can set: - -```bash -%clevercloud.db.url="jdbc:mysql://"${MYSQL_ADDON_HOST}"/"${MYSQL_ADDON_DB} -%clevercloud.db.driver=com.mysql.jdbc.Driver -%clevercloud.db.user=${MYSQL_ADDON_USER} -%clevercloud.db.pass=${MYSQL_ADDON_PASSWORD} -``` - -## HTTPS support - -HTTPS is handled by Clever Cloud ahead of your application, your application -retrieves the traffic in plain http. To be able to use `request.secure`, you -have to add `XForwardedSupport=all` in `application.conf`. - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via Git. Follow [these steps](/doc/clever-cloud-overview/add-application/) to -deploy your application. diff --git a/runtimes/java/play-framework-2.md b/runtimes/java/play-framework-2.md deleted file mode 100644 index a6c3fc542..000000000 --- a/runtimes/java/play-framework-2.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Play Framework 2 -position: 2 -shortdesc: Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller (MVC) architectural pattern. -tags: -- java ---- - -# Deploy Play Framework 2 Java - -Clever Cloud supports Play! 2 applications natively. The following guide explains how to set up your application to run the Clever Cloud. - -## Overview - -Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller (MVC) architectural pattern. It aims to optimize developer productivity by using convention over configuration, hot code reloading and display of errors in the browser. - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Necessary information - -* The application must be located at the **root** of the git repository. -* Starting from **Play 2.4**, your application needs **Java 8** to run. Please read [select java version](https://www.clever-cloud.com/doc/java/select-java-version/) for more information. - -## Configuration file - -You can configure your application start command by adding a -`./clevercloud/sbt.json` file with the following fields: - -```javascript -{ - "deploy":{ - "goal": "yourgoal" - }, - "hooks": { - "postDeploy": "pathtoyourscript" - } -} -``` - -**goal**: can for example contain additional configuration like -`"-Dconfig.resource=clevercloud.conf"` or `"-Dplay.version=2.0.4"`. - - -**postDeploy**: execute a custom script after the deploy. Some frameworks or custom applications might require bootstrapping before the application may run. -You can achieve this by creating a custom script with your commands and -adding the associated file name in `clevercloud/sbt.json`. - -## Environment injection - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -There are two way to access the environment variables from your application: - - * you can reference them in your application.conf file: - you just have to put `my.option=${MY_VARIABLE}` in your application.conf file, and then use - the configuration item `my.option` in your application. - - * you can also use the `System.getenv("MY_VARIABLE")` method. Be aware that it can return null. - - So for an application using the MySQL add-on, you can set: - -```bash -db.default.driver=org.postgresql.Driver -db.default.url="jdbc:postgresql://"${POSTGRESQL_ADDON_HOST}"/"${POSTGRESQL_ADDON_DB} -db.default.user=${POSTGRESQL_ADDON_USER} -db.default.password=${POSTGRESQL_ADDON_PASSWORD} -``` - -## Known problems with Play! 2 - -Please read the following if your project fails with this error: - -`sbt.ResolveException: unresolved dependency: play#sbt-plugin;2.0: not found` - -Some versions of Play2 try to retrieve a nonexistent version of -"sbt-plugin" which is required by the framework to work. -You have two options to fix this problem: - -You can set the "play.version" environment variable in the -`clevercloud/sbt.json` file. -For example, for Play 2.0.4: - -``` javascript -{ - "deploy": { - "goal": "-Dplay.version=2.0.4" - } -} -``` - -Otherwise, you can modify `plugins.sbt` in the project folder of your -app like the following: - -``` scala -// Comment to get more information during initialization -logLevel := Level.Warn - -// The Typesafe repository -resolvers += "Typesafe repository" at "http://repo.typesafe.com/typesafe/releases/" - -// Use the Play sbt plugin for Play projects -addSbtPlugin("play" % "sbt-plugin" % "2.0.4") // The important part of the configuration -``` - -The two solutions do the job, you can pick your favorite. - -## HTTPS support - -HTTPS is handled by Clever Cloud ahead of your application, your application -retrieves the traffic in plain http. To be able to use `request.secure`, you -have to add `trustxforwarded=true` in `application.conf`. - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via Git. Follow [these steps](/doc/clever-cloud-overview/add-application/) to deploy your application. diff --git a/runtimes/java/select-java-version.md b/runtimes/java/select-java-version.md deleted file mode 100644 index 02f396a1d..000000000 --- a/runtimes/java/select-java-version.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Selecting the java version -shortdesc: This section provides information for selecting the appropriate java version for your application -tags: -- java ---- - -## Selecting your java version - -Simply set the environment variable **JAVA_VERSION** to the version you want - -Accepted values are `6`, `7` and `8` - -## Retrocompatibility with the old configuration system - -The configuration of the JAVA_VERSION through the **clevercloud/java_version** file still works. This is totally backward compatible. diff --git a/runtimes/nodejs/nodejs-mongodb-sample-app.md b/runtimes/nodejs/nodejs-mongodb-sample-app.md deleted file mode 100644 index 1fff789ef..000000000 --- a/runtimes/nodejs/nodejs-mongodb-sample-app.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Node.js + MongoDB sample application -shortdesc: The goal of this article is to show you how to deploy a Node.js + MongoDB application on Clever Cloud. -tags: -- nodejs ---- - -# Node.js + MongoDB sample application - -The goal of this article is to show you how to deploy a Node.js + MongoDB application on Clever Cloud. - -The application is a very simple list. You can add and delete values. More information about the application: - -* [Github repo](https://github.com/CleverCloud/demo-nodejs-mongodb) -* [Clever Cloud demo](http://nodejs-demo.cleverapps.io/) - - -
-If you want to test our platform and deploy this application, just follow these simple steps: - -1. Fork the [Github repo](https://github.com/CleverCloud/demo-nodejs-mongodb). -2. Create an application from your github repo. -3. Create a [MongoDB add-on](/doc/addons/clever-cloud-addons/) and link it to your application. -4. That's all the application will use the environment variables to connect to MongoDB. - - -

If you need further information, feel free to send an email to . - diff --git a/runtimes/nodejs/nodejs.md b/runtimes/nodejs/nodejs.md deleted file mode 100644 index 2680dcf7a..000000000 --- a/runtimes/nodejs/nodejs.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -title: Deploy Node.js apps -shortdesc: Node.js is a platform built on Chrome's JavaScript runtime for building fast, scalable network applications. -tags: -- nodejs ---- - -# Deploy Node.js apps - -Clever Cloud allows you to deploy any Node.js application. This page will -explain you how to set up your application to run it on our service. - -You do not need to change a lot in your application, the *requirements* will help you to configure your apps with some -mandatory files to add, and properties to setup. - -## Overview - -Node.js is a platform built on Chrome's JavaScript runtime for building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, pretty good for data-intensive real-time applications that run across distributed devices. - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Necessary information - -Be sure that: - -* you have pushed in master branch -* you listen on port 8080 -* you have added application name in package.json -* you have added application version in package.json -* you have added application start script in package.json - -## Requirements - -First, your application must be set to listen on the 8080 port, for worldwide -connections. The following code describes a Hello world application listening on -that port: - -```javascript -// Load the http module to create an http server. -var http = require('http'); - -// Configure our HTTP server to respond with Hello World to all requests. -var server = http.createServer(function (request, response) { - response.writeHead(200, {"Content-Type": "text/plain"}); - response.end("Hello World\n"); -}); - -// Last, but not least, listen on port 8080 -server.listen(8080); -``` -Then, a *package.json* file is mandatory to initiate your app deployment on Clever Cloud. The next section will detail this point. - -### Describing package.json - -Even if you have no dependencies, you have to provide a `package.json` file at the root of your project’s directory. - -
-
About dependencies:
-
    -
  • For every Node.js project you **HAVE TO** provide a package.json file at the root of your project’s -directory.
    • -
  • Additionally, make sure that the folder "/node_modules" is in your .gitignore file before pushing your app.
    • -
-
- -If you already are a Node.js guru, you probably won’t have to change anything to that -file. Just check the required fields below. - -The `package.json` file should look like the following: - -```javascript -{ - "name" : "myapp", - "version" : "0.1.0", - "main" : "myapp.js", - "scripts" : { - "start" : "node myapp.js" - }, - "engines" : { - "node" : "~4.0" - } -} -``` - -### The json fields - -The following table describes each of the fields formerly mentioned. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
UsageFieldDescription
RequirednameName of your application. You need to fill this field.
RequiredversionVersion of you application. You need to fill this field.
At least onemainThis field allows you to specify the file you want to run. It should -be the relative path of the file starting at the project's root. It's used prior to the next one.
scripts.startThis field provides a command line to run. It is required if the main one is missing. You need one -of scripts.start and main. If both exist, we use the main one.
Optionalengines.nodeSets the node engine version you app runs with. Any "A.B.x" or "^A.B.C" or "~A.B" version will lead -to run the application with le latest "A.B" local version. If this field is -missing, we use the greatest default local version (0.10 until 2015-10-11). If you want to use iojs, put either "iojs", "iojs-v1.0.3", or any truncated -version number (e.g. "iojs-1" will work).
If you want to ensure that your app will always run, please put something of the form "^A.B.C" and avoid setting only ">=A.B.C".
- -### NPM modules dependencies - -If you need some modules you can easily add some with the *dependencies* field. - -Here is an example : - -```javascript -{ - "name" : "myapp", - "version" : "0.1.0", - "main" : "myapp.js", - "scripts" : { - "start" : "node myapp.js" - }, - "engines": { - "node": "0.8.15" - }, -"dependencies": { - "express": "3.x", - "socket.io": "0.9.x", - "underscore": "1.4.3" - } -} -``` - -## Node.js supported versions - -The Clever Cloud can virtually run any version of node >= 0.6 and any -module. Lesser (pre-npm) versions are not officially supported. Unstable -versions are not supported either. We support the io.js runtime. - -### Pre-installed modules - -We currently host the following Node.js versions, with these modules already installed: - -**You can use any version of node you need and any modules you need. Preinstall version is only for faster deployment process.** - -
-
- - - - - - - - - - - - - -
Pre-installed modules
socket.io
express
async
mysql
pg
-
-
- - -New versions will be added as they are released. - -### Defining *pre-installed* - -The above table describes the modules pre-installed. -These modules are available at deploy time, without the need to download and -install them. - -If you use modules that are not pre-installed, we will just get them with npm -(provided they are in the npm repository), and install it before we start your -application. The deploy will then be a little longer, due to probable -compilation of some of these modules. - -Some modules require system dependencies to build, require to rebuild node… so -we installed the most used ones. - -If you think more modules are commonly used and should be pre-installed, do not -hesitate to contact us at - -## Environment injection - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -To access your variable in your application, nothing simpler! Just get -it from your environment, like you would with `PATH`: -`process.env["MY_VARIABLE"]`. - -You can, for example, inject the NODE_ENV variable to define it at "production". It is not -currently set on our machines, because we need to build the project first. Beware, -devDependencies do not get fetched if NODE_ENV=production. - -### Special env NPM_TOKEN - -Since April 2015, npmjs.com allows you to have private repositories. The bad news is, -you have to write a specific line in your `.npmrc` for that. The good news is, on Clever -Cloud, you only need to provide the *token* part, and we set up everything for you! - -So to register your npm auth token, you need to add to your application the `NPM_TOKEN` -environment variable. - -``` javascript -Example: -NPM_TOKEN=00000000-0000-0000-0000-000000000000 -``` - -As you can see, only the `authToken` value is needed, not the full url you can find in -your .npmrc. - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via Git. Follow [these steps](/doc/clever-cloud-overview/add-application/) to deploy your application. - -## Deployment video - -More info on nodejs.org. diff --git a/runtimes/php/php-apps.md b/runtimes/php/php-apps.md deleted file mode 100644 index 9e48e4cab..000000000 --- a/runtimes/php/php-apps.md +++ /dev/null @@ -1,356 +0,0 @@ ---- -title: Deploy PHP applications -shortdesc: PHP is a widely-used general-purpose scripting language that is especially suited for Web development and can be embedded into HTML. -tags: -- php ---- - -# Deploy PHP apps - -PHP is available on our platform with the branches 5.4 and 5.5. You can use FTP or Git to deploy your applications. - -The HTTP server is [Apache 2](https://httpd.apache.org/), and the PHP code is executed by [PHP-FPM](http://php-fpm.org/). - -## Overview - -PHP is a widely-used general-purpose scripting language that is especially suited for Web development and can be embedded -into HTML. - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -
-

Warning:

-

An FTP application is automatically started once the application is created, even if no code has been sent.

-

- When you create a FTP application, a free [FS Bucket](/doc/addons/fs_buckets/) add-on is - provisioned, named after the application. You will find the FTP - credentials in the configuration tab of this add-on. -

-
- -## Choose your PHP version - -Since January 2016, choosing a PHP version has gotten easier: just set the PHP_VERSION environment -variable to one of the following values: - -- 5.4 -- 5.5 -- 5.6 -- 7.0 - -By default, all new PHP applications are created with a default PHP_VERSION, set to 5.6. -You can of course change it whenever you want then redeploy your application to use the -version you want. - -## Configuration files for PHP applications - -The configuration file for your PHP application must be `/clevercloud/php.json`, that is a *php.json* file in a -`/clevercloud` folder at the root of your application. - -### 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*). - -To change the webroot, just set the key `webroot` in the `deploy` part -of the configuration file *clevercloud/php.json* with the absolute path (*from the root of your application*) of your new public folder. - -In the following example we want to set the webroot to the folder `/public`: - -```javascript - { - "deploy": { - "webroot": "/public" - } - } -``` - -Please note the absolute path style: `/public`. - -
-

Warning:

-

The change of the webroot will be rejected during the deployment if the target directory does not exist or is not a directory.

-
- -### Change PHP settings - -Most of PHP settings can be changed using a `.user.ini` file. Please refer to the -[official documentation](http://www.php.net/manual/en/configuration.file.per-user.php) for more information. - -Other settings can be changed by adding the following line in `clevercloud/php.json`: - -```javascript - { - "configuration": { - "mbstring.func_overload": 2, - "another.setting": "value" - } - } -``` - -Here is the list of available settings: - -* `mbstring.func_overload` - -**Note**: You can send a request to the support if you need to change a setting which is not in this list. - -#### Maximum PHP Children per instance - -You can fix the maximum number of PHP running processes per instance by adding the following line in `clevercloud/php.json`: - -```javascript - { - "configuration": { - "pm.max_children": 32 - } - } -``` - -This setting is usefull if you need to limit the number of running processes according to the maximum connections limit -of your MySQL or PostgreSQL database. - -By default, `pm.max_children` is set to **10**. - -### 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. - -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. - -#### Define a custom HTTP timeout - -You can define the timeout of an HTTP request in Apache using the `HTTP_TIMEOUT` -[environment variable](/doc/admin-console/environment-variables/). - -By default, the HTTP timeout is se to 3 minutes (180 seconds). - -#### 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. - -eg. 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: - -```apache -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 issuying 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`. - -### 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` for you. - -The PHP instances embed the latest release of Composer. You can check it on the following pages: - -* [php54info.cleverapps.io/composer](https://php54info.cleverapps.io/composer) for PHP 5.4 -* [php55info.cleverapps.io/composer](https://php55info.cleverapps.io/composer) for PHP 5.5 - -
-

Note:

-

Add your own `composer.phar` file in the root of your repository if you need to override our version for the build phase.

-
- -Example of a `composer.json` file: - -```javascript -{ - "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" -} -``` - -#### GitHub rate limit - -Sometimes, you can encounter the following error when downloading dependencies: - -``` -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. - -First, add a file `ccbuild.sh` at the root of your project with these lines: - -```bash -#!/bin/bash - -php artisan migrate -``` - -Then add these lines in `clevercloud/php.json`: - -```javascript - { - "hooks": { - "postDeploy": "ccbuild.sh" - } - } -``` - -Note: You must add the _execute_ permission to your file (`chmod u+x yourfile`) before pushing it. - -## Environment injection - -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 - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WordpressPrestashop
DokuwikiJoomla
SugarCRMDrupal
MagentoStatus.net
SymfonyThelia
-
- -## Available extensions and modules - -You can check enabled extensions and versions by viewing our `phpinfo()` example for -[PHP 5.4](https://php54info.cleverapps.io) and [PHP 5.5](https://php55info.cleverapps.io). - -**Warning**: some extensions (OPcache, Mysqlnd and IonCube) need to be enabled explicitly. Please read below to know -how to enable them. - -If you have a request about modules, feel free to contact our support at . - -### Enable specific extensions - -Some extensions need to be enabled explicitly. To enable this extensions, you'll need to set the corresponding -[environment variable](/doc/admin-console/environment-variables/): - -* OPcache: set `ENABLE_OPCACHE` to `true`. - - OPcache is a cache system who store PHP' compiled bytecode in shared memory to improve PHP performances. - -* mysqlnd_ms: set `ENABLE_MYSQLND_MS` to `true`. - - mysqlnd_ms is a load balancing and replication plugin for mysqlnd (MySQLnative driver for PHP). It can be used with - a master/slave database system. - -* IonCube: set `ENABLE_IONCUBE` to `true`. - - IonCube is a tool to obfuscate PHP code. It's often used by paying Prestashop and Wordpress plugins. - -* Redis: set `ENABLE_REDIS` to `true`. - - Redis is an in-memory datastructure store. This extension allows to use it from PHP. - -
-

Warning:

-

This extensions are only available for PHP >= 5.5.

-
- -## Use Redis to store PHP Sessions - -We provide the possibility to store the PHP sessions in a [Redis database](/doc/addons/redis/) to improve the performances of -your application. - -To enable this feature, you need to: - - - enable Redis support on the application (create an [environment variable](/doc/admin-console/environment-variables/) named `ENABLE_REDIS` with the value `true`.) - - create and link a Redis add-on - - create an [environment variable](/doc/admin-console/environment-variables/) named `SESSION_TYPE` with the value `redis`. - -
-

Warning:

-

You must have a Redis add-on - linked with your application - to enable PHP session storage in Redis.
- If no Redis add-on is linked with your application, the deployment will fail.

-
- -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via **Git or FTP**. Follow -[these steps](/doc/clever-cloud-overview/add-application/) to deploy your application. diff --git a/runtimes/php/tutorial-drupal.md b/runtimes/php/tutorial-drupal.md deleted file mode 100644 index e7762fe21..000000000 --- a/runtimes/php/tutorial-drupal.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Deploy a Drupal website -shortdesc: This article shows you how to deploy a Drupal-based website on the Clever Cloud. -tags: -- php ---- - -# Deploy a Drupal website - -## Create an application - -You can find in [this article](/doc/clever-cloud-overview/add-application/#create-an-application) the process to create an application. - -## Two choices for deployment - -During the creation of a PHP application, it is asked if you want to deploy it via FTP or via Git. These two techniques have their own pros and cons but have the same end result. - -## Deploy via FTP - -1. Download the Drupal source files on [drupal.org](http://drupal.org) -2. [Add a MySQL database add-on](/doc/addons/clever-cloud-addons/) -3. [Send these Drupal files via FTP](/doc/clever-cloud-overview/add-application/#ftp-deployment) using the FTP credentials you received by email when you created the application. -4. When finished, launch the application with the url that you can find in the *domains* panel in the left sidebar. -5. Follow the Drupal installation steps -6. When asked for database informations, fill them with the ones you received by email: - * database name - * database username - * database password - * database host, for example `bj79c949bvl2deb6.mysql.clvrcld.net` - * database port - - -## Deploy via Git - -1. Download the Drupal source files on [drupal.org](http://drupal.org) -2. [Add a MySQL database add-on](/doc/addons/clever-cloud-addons/) -3. Open `.gitignore` file and delete `sites/*/settings*.php` line -4. Copy the file `sites/default/default.settings.php` to `sites/default/settings.php` -5. Open `sites/default/settings.php` and line 213, replace - - ```php - $databases = array(); - ``` - -
- by - - ```php - $databases = array ( - 'default' => - array ( - 'default' => - array ( - 'database' => 'yourDatabaseName', - 'username' => 'yourDatabaseUsername', - 'password' => 'yourDatabasePassword', - 'host' => 'yourDatabaseHost(beh2n9c2pai0f98k.mysql.clvrcld.net)', - 'port' => '', - 'driver' => 'mysql', - 'prefix' => '', - ), - ), - ); - ``` -6. Replace the line `$drupal_hash_salt = ''` with `$drupal_hash_salt = 'yoursalt'`. You can generate salts with -[this link](http://www.passwordtool.hu/). -5. As mentioned in this [article](/doc/addons/fs_buckets/), with Git deployments, files that are uploaded by users must be -persisted in a File System Bucket. In order to do so, [add a File Bucket](/doc/addons/fs_buckets/) via the console. -You will then receive your bucket id. -6. At the root of your application, create a `clevercloud/buckets.json` file (create a `clevercloud` -folder in which you create a `buckets.json` file). -7. Add the following lines in this file. Do not forget to replace bucketId by the bucketId you received by email: - - ```javascript - [ - { - "bucket" : "bucketId", - "folder" : "/sites/default/files" - } - ] - ``` - -5. Send these Drupal files via Git. Read this [article](/doc/clever-cloud-overview/add-application/#git-deployment) if you need more information about it. -6. When finished, get the url that you can find in the *domains* panel in the left sidebar. Then open the following link: - -`http://yourapplication.cleverapps.io/install.php` - -Do not forget the **/install.php** page otherwise installation will not happen. -Follow the steps and you're done! diff --git a/runtimes/php/tutorial-wordpress.md b/runtimes/php/tutorial-wordpress.md deleted file mode 100644 index 7d5c00b32..000000000 --- a/runtimes/php/tutorial-wordpress.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Deploy a Wordpress website -shortdesc: This article shows you how to deploy a Wordpress-based website on the Clever Cloud. -tags: -- php ---- - -# Deploy a Wordpress website - -## Create an application - -You can find in [this article](/doc/clever-cloud-overview/add-application/#create-an-application) the process to create an -application. - - -## Two choices for deployment - -During the creation of a PHP application, it is asked if you want to deploy it via FTP or via Git. These two techniques -have their own pros and cons but have the same end result. - -## Deploy via FTP - -1. Download the Wordpress source files on [wordpress.org](http://wordpress.org). - -2. [Add a MySQL database add-on](/doc/addons/clever-cloud-addons/). - -3. Rename the file `wp-config-sample.php` to `wp-config.php`. - -4. Replace in `wp-config.php` the host (for example: bj79c949bvl2deb6.mysql.clvrcld.net), database name, username and -password using the [environment variables](/doc/admin-console/environment-variables/) of the add-on. - -3. [Send these Wordpress files via FTP](/doc/clever-cloud-overview/add-application/#ftp-deployment) using the FTP -credentials displayed in the application' information page. - -6. When finished, you can launch the application with the url that you can find in the *domains* panel in the left sidebar. - - -## Deploy via Git - -1. Download the Wordpress source files on [wordpress.org](http://wordpress.org). - -2. [Add a MySQL database add-on](/doc/addons/clever-cloud-addons/). - -3. Rename the file `wp-config-sample.php` to `wp-config.php`. - -4. Replace in `wp-config.php` the host (for example: bj79c949bvl2deb6.mysql.clvrcld.net), database name, username and -password using the [environment variables](/doc/admin-console/environment-variables/) of the add-on. - -5. As mentioned in this [article](/doc/addons/fs_buckets/), with Git deployments, files that are uploaded by users must -be persisted in a File System Bucket. In order to do so, [add a FS Bucket](/doc/addons/fs_buckets/) via the console. -You will find the bucketId in the [information](/doc/addons/clever-cloud-addons/) section of the FS Bucket add-on. - -6. At the root of your application, create a `clevercloud/buckets.json` file (create a `clevercloud` folder in which -you create a `buckets.json` file). - -7. Add the following lines in this file. Do not forget to replace `bucketId` by the bucketId displayed in the -[information](/doc/addons/clever-cloud-addons/) section of the FS Bucket add-on. - ```javascript - [ - { - "bucket" : "bucketId", - "folder" : "/wp-content/uploads" - } - ] - ``` - -8. Send these Wordpress files via Git. Read this [article](/doc/clever-cloud-overview/add-application/#git-deployment) -if you need more information about it. - -9. When finished, you can launch the application with the url that you can find in the *domains* panel in the left sidebar. - - -### Install a Wordpress plugin with Git - -Wordpress plugins can be installed from the administration panel, to help the user. However, this way doesn't work with -git. Indeed, as explained above, deploying with git prevents to keep files uploaded by the user and the plugin installed -on the admin panel will be lost at the next deployment, because the code of the plugin isn't tracked by git. - -To solve this problem, we recommend to install the plugin manually by copying the content of the plugin to the -`/wp-content/plugins/` folder, add the new files to git and then deploy your application. - -The plugin will then be available in the **Extensions** section of your admin panel and you will be able to manage it -as others Wordpress plugins. To uninstall the plugin, the procedure is the same as before except that you have to delete -the folder corresponding to the plugin you want to delete. The extension will be automatically disabled, but we recommend -you to delete it from you admin panel before removing the file, in order to clean your database and all files that the -plugin could have created. - - -## Optimise and speed-up your Wordpress - -There are multiple ways to optimise your Wordpress and speed-up its response time. -We provide different tools and software to help you in this task as [Varnish](/doc/php/varnish/) for the HTTP cache, -and [Redis](/doc/addons/redis/) for the object caching. - - -### Performance plugins - -
-

Warning:

-

We recommend you to not use performance plugins like W3 Total Cache or JetPack as they are - intended to be used on a shared hosting server.
- We noticed performances problems when performance plugins are enabled and we recommend to use Varnish and Redis - if you need performance optimisations on Clever Cloud.

-
- - -### HTTP Cache with Varnish - -Enabling [Varnish](/doc/tools/varnish/) for your application is very simple. All instances of PHP provide -[Varnish](/doc/tools/varnish/), you just have to configure your application to use it. - -1. To use Varnish in your application, you have to create a `varnish.vcl` file in the `clevercloud` folder of -your application. If this folder doesn't exist, create it in the **root** of your project. - -2. Copy [this code](https://raw.githubusercontent.com/CleverCloud/varnish-examples/master/wordpress.vcl) into the -`varnish.vcl` file you just created. It'll configure Varnish to work with your Wordpress. - -3. To properly purge the Varnish cache of your application when a post is created/updated, a comment is posted, ... -we recommend you to install the [Varnish HTTP Purge](https://wordpress.org/plugins/varnish-http-purge/) plugin to -your Wordpress. It'll purge the Varnish cache for you and give you the possibility to purge it manually. - -If you need to manually purge the Varnish cache, the plugin provides a **Purge Varnish cache** button on the top bar -of your website. - - -### Object cache with Redis - -[Redis](/doc/addons/redis/) offers you a good way to speed-up your application by caching some of the objects of your -application, as the result of SQL queries of your application, improving the response time. - -To enable [Redis](/doc/addons/redis/) for your Wordpress, you need to disable other Object Cache and Data Cache of your -application (as those provided by *W3 Total Cache* for example). Make sure they aren't enabled to avoid conflicts and -performance problems. - -1. [Create a Redis add-on](/doc/addons/clever-cloud-addons/) for your application. - -2. Add the following lines to your `wp-config.php` file. Make sure they are **before** the -`require_once(ABSPATH . 'wp-settings.php');` line, otherwise the Redis connexion will not work for your application and -your application will return only white pages! -```php -define('WP_CACHE_KEY_SALT', 'tvm_'); -define('WP_REDIS_CLIENT', 'pecl'); -define('WP_REDIS_HOST', getenv('REDIS_HOST')); -define('WP_REDIS_PORT', getenv('REDIS_PORT')); -define('WP_REDIS_PASSWORD', getenv('REDIS_PASSWORD')); -``` - -3. Download [this file](http://plugins.svn.wordpress.org/redis-cache/trunk/includes/object-cache.php) -who manages the connexion with Redis and Wordpress and moves it to your `/wp-content` folder. The file **must** be named -`object-cache.php`. - -4. Redis should now work with your Wordpress. diff --git a/runtimes/python/python-django-sample.md b/runtimes/python/python-django-sample.md deleted file mode 100644 index fde4b19db..000000000 --- a/runtimes/python/python-django-sample.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Sample Django application -shortdesc: The goal of this article is to show you how to deploy a Django application on Clever Cloud. -tags: -- python ---- - -# Django sample application - -The goal of this article is to show you how to deploy a Django application on Clever Cloud. - -The application is a very basic one. More information about the application: - -* [Github repo](https://github.com/CleverCloud/django-example) -* [Clever Cloud demo](http://django.cleverapps.io/) - -
-If you want to test our platform and deploy this application, just follow these simple steps: - -1. Clone the [Github repo](https://github.com/CleverCloud/django-example) -2. Git push (deploy) your application. - -

-
-
Reminder
-

Do not forget to add the [clevercloud/python.json](https://github.com/CleverCloud/django-example/blob/master/clevercloud/python.json) in any Python project so that we get your required modules. -

-
- - -

If you need further information, feel free to send an email to . - diff --git a/runtimes/python/python-flask-sample-app.md b/runtimes/python/python-flask-sample-app.md deleted file mode 100644 index 2355d37e3..000000000 --- a/runtimes/python/python-flask-sample-app.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Sample Python application -shortdesc: The goal of this article is to show you how configure and deploy a simple Flask application on Clever Cloud. -tags: -- python ---- - -# Flask Demo - -This is a small Flask app that replies with a header dump to any request. - -You can deploy this application as-is on Clever Cloud: - -```bash -git clone https://github.com/CleverCloud/demo-flask -git remote add clevercloud {your-clever-cloud-endpoint} -git push clevercloud master -``` - -And it will do the trick. - -We demonstrate several Clever Cloud possibilities in this application: - -## Choose python version - -We have a `python_version` file in the `/clevercloud` folder that contains **3**. -This will select the latest *Python 3* version installed (at the time of this writing, 3.4). - -Documentation: [Use Python 3](https://www.clever-cloud.com/doc/python/python_apps/#use-python-3) - -## Build app in a subfolder - -In the `/clevercloud/python.json` file, we have the `"build"."folder"` field that points to the `app` folder. -We will build & run the app from this `app` folder. - - -## Static files - -We set up in `/clevercloud/python.json` a "static" folder: everything in that folder will be served statically. -Note that the static folder will be the root of static files requests. In this example, to get to Cat.svg which is in -the "s" folder in the `/clevercloud/static folder`, you need to request "http://{yourdomain}/s/Cat.svg". - -You can also see that "s" is a link to the static folder at the root of the app. It's just to show that you can do symlinks. - -Documentation: [Manage your static files](https://www.clever-cloud.com/doc/python/python_apps/#manage-your-static-files) - -## Run the app - -As explained in [Select your module](https://www.clever-cloud.com/doc/python/python_apps/#select-your-module) -we ask Clever Cloud to run the "app" Flask application defined in the `hello.py` file. So the "module" field is `hello:app`. \ No newline at end of file diff --git a/runtimes/python/python_apps.md b/runtimes/python/python_apps.md deleted file mode 100644 index 5c0ef8469..000000000 --- a/runtimes/python/python_apps.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Deploy Your App -position: 1 -shortdesc: Python 2.7.8 and 3.4.1 are available on our platform. You can use Git to deploy your application. -tags: -- python ---- - -# Deploy Python apps - -Python is a programming language that lets you work more quickly and integrate your systems more effectively. -You can learn how to use Python and see almost immediate gains in productivity and lower maintenance costs. - - -## Overview - -Python 2.7 and 3.4 are available on our platform. You can use Git to deploy your application. - - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Available extensions and modules - -You are granted to install external libs. As you can do on your workstation you can easily use **pip** and **requirements.txt**. - -For example to install *Flask* and various libs you have to create a file `/requirements.txt` : - -```javascript -SQLAlchemy==0.7.8 -Flask==0.9 -Flask-Admin==1.0.2 -Flask-Assets==0.8 -Flask-DebugToolbar==0.7.1 -Flask-KVSession==0.3.2 -Flask-Mail==0.8.2 -Flask-SQLAlchemy==0.16 -Flask-Script==0.5.3 -Flask-WTF==0.8.3 -webassets==0.8 -pytz==2012d -psycopg2==2.4.5 -``` - -If you have any question, feel free to [contact our support](https://www.clever-cloud.com/doc/get-help/support/). - - -## Configuration file - -The configuration file for your Python application must be `/clevercloud/python.json`. - -You can find a [example of Flask application](/doc/python/python-flask-sample-app/) who use concept detailed below. - - -### Select your module - -To select which module you want to start, use the key `module` in `deploy` like the following: - -```haskell - { - "deploy": { - "module": "mymodule:app" - } - } -``` - -The module (without .py) must be importable, i.e. be in `PYTHONPATH`. For example with *Flask*, it's gonna be the name of -your main server file followed by your Flask object: `server:app` for example if you have a `server.py` file at the root -of your project with a Flask `app` object inside. - -Basically, you should just point to a WSGI capable object. - - -### Manage your static files - -To enable Nginx to serve your static resources you must set your public folder in -`clevercloud/python.json` like below: - -```haskell - { - "deploy": { - "static": "/mypublicfolder" - } - } -``` - -Also, you are able to use a Filesystem Bucket to store your static files. Please refer to the -[File System Buckets](/doc/addons/clever-cloud-addons/#fs-buckets-file-system-with-persistance/) section. - -**Note**: the path of your folder must be absolute regarding the root of your application. - - -### Use Python 3 - -The default version of python on Clever Cloud is **2.7**, if you want to use python **3.4** instead, use the file -`/clevercloud/python_version` and put `3` in it. - -**Note**: the version is an integer, do not use quotes. values allowed are `2` and `3`. - - -## Environment injection - -Clever Cloud can inject environment variables that are defined in the dashboard and by add-ons linked to your application. - -The access to these variables is simple: just get them as you would with any environment variable: - -```python -import os -os.getenv("MY_VARIABLE") -``` - - -## Git Deployment - -*You will need git on your computer to deploy via this tool. Here is the official website of Git to get more -information: [git-scm.com](http://git-scm.com)* - -After you created an app in the [console](https://console.clever-cloud.com), the console prompt you the following message: - -
- -
- - -### Setting up your remotes - -1. The "Information" page of your app gives you your git deployment URL. It looks like this: -``git+ssh://git@push.clever-cloud.com/.git``. Copy it in your clipboard. - -2. On your computer, go into your application repository. -If you didn't already track your app with **git**, start by typing: - - ```bash - $ git init - ``` - -3. Then, use the `git remote` command to add the deploy URL: - - ```bash - $ git remote add - ``` - -4. The last step is to push your application: - - ```bash - $ git push master - ``` - -
-

Warning:

-

The remote branch on Clever Cloud is ALWAYS master. If your local branch is not "master", use this syntax:

- 
git push < name > yourbranch:master
-
diff --git a/runtimes/ruby/ruby.md b/runtimes/ruby/ruby.md deleted file mode 100644 index eb22ba575..000000000 --- a/runtimes/ruby/ruby.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Deploy Ruby on Rails apps -shortdesc: Ruby on Rails is an open source web application framework which runs on the Ruby programming language. -tags: -- ruby ---- - -# Deploy Ruby on Rails applications - -Clever Cloud allows you to deploy any Ruby on Rails application. This page will -explain you how to set up your application to run it on our service. - -You do not need to change a lot in your application, the *requirements* will help you configure your applications with some mandatory files to add, and properties to setup. - -## Overview - -Ruby on Rails is an open source web application framework which runs on the Ruby programming language. It is a full-stack framework: it allows creating pages and applications that gather information from the web server, talk to or query the database, and render templates out of the box. As a result, Rails features a routing system that is independent of the web server. - - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Necessary information - -Be sure that: - -* you push to the master branch - -* you commit your Gemfile.lock file - -* you have a config.ru file (This one is most of the time generated by rails) - -## Requirements - -First, your application must use rack. This implies that a config.ru -file is present. - -Then, you need to provide a Gemfile.lock. To do that, please run: - -```bash -.../myapp $ bundle install ## That will generate Gemfile.lock -.../myapp $ git add Gemfile.lock -.../myapp $ git commit -m "Add production dependency file" -``` - -## Choose ruby version - -Simply add this to your Gemfile - -``` -ruby '2.1' -``` - -`rubyversion` must be a string. The given string is tested against the -available versions by using the /^/ regexp. - - * "2" will select the greatest "2.X.Y" version available. - * "2.0" will select the greatest "2.0.Y" version available. - * "2.0.0-p481" will select the "2.0.0-p481" version. - -If given `rubyversion` does not match any available version, your -deployment will fail. - -If you need a version that is not yet installed, please contact the -support to ask for the version to be added. We try to follow the -releases, but, hey, we're human! - -Due to current landscape in ruby applications, the default version is the -greatest 2.1.Y. We provide also the latest 2.2.Y version and the latest -1.9.Y too, but prefer the current stable: 2.1. - -## Configuration secret key production - -You need to use environment injection for `secret_key_base` in file `./config/secret.yml` : - -```yml - # You can use `rake secret` to generate a secure secret key. - # Do not keep production secrets in the repository, - # instead read values from the environment. - production: - secret_key_base: <%= ENV["SECRET_KEY_BASE"] %> -``` - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -To access your variable in your application, nothing simpler! Just get -it from your environment, like you would with `PATH`: -`ENV["MY_VARIABLE"]`. - - -## More configuration - -You can configure your deployment via the `clevercloud/ruby.json` -configuration file. This file is optional. - -### Set deployment RUBY_ENV and rake goals to execute - -```javascript -{ - "deploy" : { - "env": "", - "rakegoals": [], - "sidekiq": true - } -} -``` - -The following table describes each field: - - - - - - - - - - - - - - - - - - - - - - - - - - - -
UsageFieldDescription
Optionaldeploy.envThis field is only used for overriding the default "production" RAILS_ENV value.
Optionaldeploy.rakegoals -Specify a list of rake goals to execute. -They will be executed in the order of the list:
-
bundle exec rake "goal1"

-
bundle exec rake "goal2"
…
-We do not execute any rake goals by default. -
Optionaldeploy.sidekiq -Run a sidekiq process in background. Beware, you will need a redis instance to use this -feature. -
- - -The sidekiq field can also be an array of strings instead of a boolean, like this: - -```javascript -"sidekiq": [ - "./config/sidekiq_1.yml", - "./config/sidekiq_2.yml", - "./config/sidekiq_3.yml" -] -``` - -Each string is the path *from the root of the repository* to a sidekiq configuration file. -Each file might contain something like the following: - -```yaml ---- -:concurrency: 4 -:pidfile: tmp/pids/sidekiq_1.pid -:queues: - - [critical, 2] - - default - -production: - :logfile: ./log/sidekiq.log -``` - -It's a standard sidekiq.yml configuration file. - -### Manage your static files - -To make Nginx serve your static resources you must set your public folder in `clevercloud/ruby.json` like below: - -```haskell - { - "deploy": { - "static": "/mypublicfolder" - } - } -``` - -*Note: the path of your folder must be absolute regarding the root of your application.* - -### Update wsgi buffer size - -The default buffer size for headers is 4096. This is enough for most people. But you might -need to increase that value if your application uses very long query string or headers. - -To change the buffer size, set the `WSGI_BUFFER_SIZE` [environment variable](admin-console/environment-variables) in the Clever Cloud console. - -Example: - -``` -WSGI_BUFFER_SIZE=8192 -``` - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via Git. Follow [these steps](/doc/clever-cloud-overview/add-application/) to deploy your application. diff --git a/runtimes/ruby/tutorial-ruby.md b/runtimes/ruby/tutorial-ruby.md deleted file mode 100644 index af07dd9a3..000000000 --- a/runtimes/ruby/tutorial-ruby.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Hello world tutorial -shortdesc: How to write a hello world web application using Rack and deploy it on the Clever Cloud. -tags: -- ruby ---- -# Hello World tutorial for Rack-based application - -## Introduction - -Currently, the Clever Cloud supports Rack-based applications. -Created in 2007, Rack has become the de-facto standard for ruby -web applications. - - -## Dependencies - -To follow this tutorial, you will need: - -* Ruby >= 1.9.2 (w/ Rubygems) - -* Bundler (`gem install bundler` and you're good to go!) - -* Your preferred editor - -* Git (for the deploy part) - -
-To manage your gems and ruby versions, we recommend rbenv. -If you use a system-wide installation of ruby, You will have to use `sudo` with the `gem` and `bundle` commands, -or use arguments that will make gem and bundle install the gem in directories you have write-permissions in. -
- - -## Create and write your application - -```bash -$ mkdir helloworld-rack -$ cd !$ # or 'helloworld-rack'. -$ touch hello.rb config.ru Gemfile -``` - -Inside `hello.rb` put the following: - -```ruby -class HelloWorld - def call(env) - [200, {"Content-Type" => "text/plain"}, ["Hello world!"]] - end -end -``` - -Inside the `config.ru` (That is, the main Rack entry-point) put: - -```ruby -require './hello' -run HelloWorld.new -``` - -The `Gemfile` file will contain our dependencies: - -```ruby -source 'https://rubygems.org' - -gem 'rack', '~>1.5.1' -``` - -We don't need any more dependencies. The Gemfile is mandatory to deploy -on the Clever Cloud. - - -## Test your application - -To test your application, just fetch the dependencies using bundler: - -```bash -$ bundle -Fetching gem metadata from https://rubygems.org/.......... -Resolving dependencies... -Using rack (1.5.2) -Using bundler (1.3.5) -Your bundle is complete! -Use `bundle show [gemname]` to see where a bundled gem is installed. -$ rackup # That will start your application -[2013-09-16 17:35:26] INFO WEBrick 1.3.1 -[2013-09-16 17:35:26] INFO ruby 2.0.0 (2013-06-27) [x86_64-linux] -[2013-09-16 17:35:26] INFO WEBrick::HTTPServer#start: pid=5656 port=9292 -``` - -You can now test with your browser at localhost:9292. - - - -## Deploy your application - -1. Using the Clever Cloud console, create a new Ruby application (https://console.clever-cloud.com/users/me/applications/new). -2. Initialize and set up a the git repository for your application: - -```bash -$ git init -Initialized empty Git repository in /*******/helloworld-rack/.git/ -$ git add config.ru Gemfile Gemfile.lock hello.rb -$ git commit -m "Initial commit, ready for clever push" -[master (root-commit) eaadcfc] Initial commit, ready for clever push - 4 files changed, 20 insertions(+) - create mode 100644 Gemfile - create mode 100644 Gemfile.lock - create mode 100644 config.ru - create mode 100644 hello.rb -$ git remote add cleverapps git+ssh://git@push.clever-cloud.com/app_xxxxx-xxxxx-xxxxx-xxxxx-xxxxxx.git -$ git push cleverapps master -Counting objects: 6, done. -Delta compression using up to 2 threads. -Compressing objects: 100% (5/5), done. -Writing objects: 100% (6/6), 641 bytes | 0 bytes/s, done. -Total 6 (delta 0), reused 0 (delta 0) -remote: {"id":320,"message":"The application has successfully been queued for redeploy.","type":"success"} -To git+ssh://git@push.clever-cloud.com/app_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.git - * [new branch] master -> master -``` - - -And now, wait till the end of the deployment. You can check the logs in the console. -Our demo for this tutorial is here: https://helloworld-rack-demo.cleverapps.io/. diff --git a/runtimes/scala/play-framework-1.md b/runtimes/scala/play-framework-1.md deleted file mode 100644 index b68fd5184..000000000 --- a/runtimes/scala/play-framework-1.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Play Framework 1 -position: 1 -shortdesc: Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller (MVC) architectural pattern. -tags: -- scala ---- - -# Deploy Play Framework 1.x - -Clever Cloud supports Play 1.x applications natively. The present guide explains how to set up your application to run -on Clever Cloud. - -## Overview - -Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller -(MVC) architectural pattern. It aims to optimize developer productivity by using convention over configuration, hot code -reloading and display of errors in the browser. - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Necessary information - -* The application must be located at the **root** of the git repository. - -## Select Play! version - -Clever Cloud supports Play! **1.2** and **1.3**. You can select the Play! version for your application by creating a -`play1_version` file in the `/clevercloud` folder. - -The `play1_version` file can contain one of the following values: - -* `1.2` or `12` for **Play! 1.2**. -* `1.3` or `12` for **Play! 1.3**. - - -## Play! configuration - -By default, your application will run on Clever Cloud with the option `--%clevercloud`. -It means that you can define special keys in your `application.conf` file that will be used only on Clever Cloud. - -You can for example: - -* set production mode so the files are compiled at startup time and the errors are logged in a file: - - ```bash - %clevercloud.application.mode=prod - ``` - -* set up a mysql database - - ```bash - %clevercloud.db.url=jdbc:mysql://{yourcleverdbhost}/{dbname} - %clevercloud.db.driver=com.mysql.jdbc.Driver - %clevercloud.db.user={yourcleveruser} - %clevercloud.db.pass={yourcleverpass} - ``` - -More information on [playframework.com](http://www.playframework.com). - -## Configuration file - -You can configure your application start command by adding a `./clevercloud/play.json` file with the following fields: - -```javascript -{ - "hooks": { - "postDeploy": "pathtoyourscript" - } -} -``` - -**postDeploy**: execute a custom script after the deploy. Some frameworks or custom applications might require -bootstrapping before the application may run. You can achieve this by creating a custom script with your commands and -adding the associated file name in `clevercloud/play.json`. - -## Environment injection - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -To access the environment variables from your application, you need to -reference them in your application.conf file: -you just have to put `my.option=${MY_VARIABLE}` in your application.conf file, and then use -the configuration item `my.option` in your application. - -So for an application using the MySQL add-on, you can set: - -```bash -%clevercloud.db.url="jdbc:mysql://"${MYSQL_ADDON_HOST}"/"${MYSQL_ADDON_DB} -%clevercloud.db.driver=com.mysql.jdbc.Driver -%clevercloud.db.user=${MYSQL_ADDON_USER} -%clevercloud.db.pass=${MYSQL_ADDON_PASSWORD} -``` - -## HTTPS support - -HTTPS is handled by Clever Cloud ahead of your application, your application -retrieves the traffic in plain http. To be able to use `request.secure`, you -have to add `XForwardedSupport=all` in `application.conf`. - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via Git. Follow [these steps](/doc/clever-cloud-overview/add-application/) to -deploy your application. diff --git a/runtimes/scala/play-framework-2.md b/runtimes/scala/play-framework-2.md deleted file mode 100644 index 82279793e..000000000 --- a/runtimes/scala/play-framework-2.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Play Framework 2 -position: 2 -shortdesc: Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller (MVC) architectural pattern. -tags: -- scala ---- - -# Deploy Play Framework 2 Scala - -Clever Cloud supports Play! 2 applications natively. The following guide explains how to set up your application to run the Clever Cloud. -To support the Play! 2 framework, we use SBT. - -## Overview - -Play is an open source web application framework, written in Scala and Java, which follows the model–view–controller (MVC) architectural pattern. It aims to optimize developer productivity by using convention over configuration, hot code reloading and display of errors in the browser. - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Necessary information - -* The application must be located at the **root** of the git repository. -* Starting from **Play 2.4**, your application needs **Java 8** to run. Please read [select java version](https://www.clever-cloud.com/doc/java/select-java-version/) for more information. - -## Configuration file - -You can configure your application start command by adding a `./clevercloud/sbt.json` file with the following fields: - -```javascript -{ - "deploy":{ - "goal": "yourgoal" - }, - "hooks": { - "postDeploy": "pathtoyourscript" - } -} -``` - -**goal**: can for example contain additional configuration like -`"-Dconfig.resource=clevercloud.conf"` or `"-Dplay.version=2.0.4"`. - - -**postDeploy**: execute a custom script after the deploy. Some frameworks or custom applications might require bootstrapping before the application may run. -You can achieve this by creating a custom script with your commands and -adding the associated file name in `clevercloud/sbt.json`. - -## Environment injection - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -There are two way to access the environment variables from your application: - - * you can reference them in your application.conf file: - you just have to put `my.option=${MY_VARIABLE}` in your application.conf file, and then use - the configuration item `my.option` in your application. - - * you can also use the `System.getenv("MY_VARIABLE")` method. Be aware that it can return null. - -So for an application using the MySQL add-on, you can set: - -```bash -db.default.driver=org.postgresql.Driver -db.default.url="jdbc:postgresql://"${POSTGRESQL_ADDON_HOST}"/"${POSTGRESQL_ADDON_DB} -db.default.user=${POSTGRESQL_ADDON_USER} -db.default.password=${POSTGRESQL_ADDON_PASSWORD} -``` - -## Known problems with Play! 2 - -Please read the following if your project fails with this error: - -`sbt.ResolveException: unresolved dependency: play#sbt-plugin;2.0: not found` - -Some versions of Play2 try to retrieve a nonexistent version of -"sbt-plugin" which is required by the framework to work. -You have two options to fix this problem: - -You can set the "play.version" environment variable in the -`/clevercloud/sbt.json` file. -For example, for Play 2.0.4: - -``` javascript -{ - "deploy": { - "goal": "-Dplay.version=2.0.4" - } -} -``` - -Otherwise, you can modify `plugins.sbt` in the project folder of your -app like the following: - -``` scala -// Comment to get more information during initialization -logLevel := Level.Warn - -// The Typesafe repository -resolvers += "Typesafe repository" at "http://repo.typesafe.com/typesafe/releases/" - -// Use the Play sbt plugin for Play projects -addSbtPlugin("play" % "sbt-plugin" % "2.0.4") // The important part of the configuration -``` - -The two solutions do the job, you can pick your favorite. - -## Failed to acquire connection: Too many connections - -You may run into this error during deployments: - -``` scala -[error] c.j.b.h.AbstractConnectionHook - Failed to acquire connection to jdbc:
Sleeping for 1000ms and trying again. Attempts left: 10. Exception: null.Message:FATAL: too many connections for role "" -``` - -By default, Play! opens a pool of 10 connections, which is more than the -connection limit allowed by DEV database plans. During a no-downtime -deployment, there are at least two instances of the application running in -parallel, so it's 20 connections. - -To avoid connection exhaustion, you should limit your pool at half the number -of available connections (if you have horizontal scaling enabled, adjust -accordingly). - -``` scala -# conf/application.conf - -db.default.partitionCount=2 -db.default.maxConnectionsPerPartition=5 -db.default.minConnectionsPerPartition=5 -``` - - -## HTTPS support - -HTTPS is handled by Clever Cloud ahead of your application, your application -retrieves the traffic in plain http. To be able to use `request.secure`, you -have to add `trustxforwarded=true` in `application.conf`. - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via Git. Follow [these steps](/doc/clever-cloud-overview/add-application/) to deploy your application. - - -More info on playframework.com. diff --git a/runtimes/scala/scala.md b/runtimes/scala/scala.md deleted file mode 100644 index b42b54a75..000000000 --- a/runtimes/scala/scala.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Scala with SBT -shortdesc: Scala is an object-functional programming and scripting language that runs on the Java platform… -tags: -- scala ---- - -# Deploy Scala apps - -The Clever Cloud allows you to deploy Scala and Java applications built with SBT. -This document will explain you how to set up your app to run on our service. - -## Overview - -Scala is an object-functional programming and scripting language that runs on the Java platform for general software -applications, statically typed, designed to concisely express solutions in an elegant, type-safe and lightweight manner. -Scala includes full support for functional programming (including currying, pattern matching, algebraic data types, lazy -evaluation, tail recursion, immutability, etc.). - -## Create an application - -Refer to the page [Deploy an application on Clever Cloud](/doc/clever-cloud-overview/add-application/). - -## Requirements - -First, your application must be set to listen on the 8080 port, for worldwide -connections. - -We currently support both sbt-native-packager and sbt-start-script. So -you need to add one of them to your project. (Please use sbt-native-packager if you can, -sbt-start-script has some bugs involving environment variables) - -These plugins will add the "stage" goal that we will use to create a -start script we will execute. - -In project/plugins.sbt: - -```scala -addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "0.8.0") -``` - -or - -```scala -addSbtPlugin("com.typesafe.sbt" % "sbt-start-script" % "0.10.0") -// Or 0.9.0 if you use sbt ≤0.12 -``` - - -You can also use newer (or older) versions of the plugin. - -Prepend to build.sbt: - -```scala -packageArchetype.java_application -``` - -or - -```scala -import com.typesafe.sbt.SbtStartScript - -seq(SbtStartScript.startScriptForClassesSettings: _*) -``` - -That should be enough for a project with a main method. - -Please note that the sbt-start-script plugin is going toward deprecation. Also, please -note that sbt-start-script fails to handle environment variables in a correct way. - -For more configuration, please go to https://github.com/sbt/sbt-start-script. - -## Environment injection - -Clever Cloud can inject environment variables that are defined in the -dashboard and by add-ons linked to your application. - -To get an env variable from your code, you can use the `System.getenv("MY_VARIABLE")` method. Be aware that it can return null. - -## Deploy on Clever Cloud - -Application deployment on Clever Cloud is via Git. Follow [these steps](/doc/clever-cloud-overview/add-application/) to deploy your application. diff --git a/shared/blackfire.md b/shared/blackfire.md new file mode 100644 index 000000000..bce8e0a1a --- /dev/null +++ b/shared/blackfire.md @@ -0,0 +1,5 @@ +### Monitor your application with Blackfire + +You can use [Blackfire](https://www.blackfire.io/) to monitor your application on Clever Cloud. + +Please refer to our [Blackfire documentation](/developers/doc/metrics/blackfire) to configure it for your application. diff --git a/shared/cached-dependencies.md b/shared/cached-dependencies.md new file mode 100644 index 000000000..4477905f9 --- /dev/null +++ b/shared/cached-dependencies.md @@ -0,0 +1,15 @@ +### Cached dependencies + +#### Enabling dependencies caching + +You can enable dependencies caching by adding the `CC_CACHE_DEPENDENCIES=true` [environment variable](#setting-up-environment-variables-on-clever-cloud) in your application. It is enabled by default only for rust and haskell applications. + +#### Disabling dependencies caching + +You can disable dependencies caching completely by removing the `CC_CACHE_DEPENDENCIES` environment variable from the Clever Cloud console, in the **Environment variables** menu of your application. + +Or by setting it to `CC_CACHE_DEPENDENCIES=false` + +To fully remove cached dependencies, you have to rebuild your application from scratch. + +You can select "rebuild and restart" from the Clever Cloud console or launch `clever restart --without-cache` with the Clever Tools CLI. diff --git a/shared/ci-cd-configuration.md b/shared/ci-cd-configuration.md new file mode 100644 index 000000000..5acccf88c --- /dev/null +++ b/shared/ci-cd-configuration.md @@ -0,0 +1,11 @@ + +### Mandatory configuration + +Your repository must contain at least the following variables to use the CLI: + +- `CLEVER_TOKEN` +- `CLEVER_SECRET` + +Find it in your machine, usually in `~/.config/clever-cloud/clever-tools.json`, after installing [Clever Tools](https://github.com/CleverCloud/clever-tools/). + +⚠️ `CLEVER_TOKEN` and `CLEVER_SECRET` expire after one year. Make sure to set a reminder to inject the new ones to avoid breaking your pipelines. diff --git a/shared/create-application.md b/shared/create-application.md new file mode 100644 index 000000000..94014b89b --- /dev/null +++ b/shared/create-application.md @@ -0,0 +1,17 @@ + +## Create an application on Clever Cloud + +### With the web console + +Refer to [Quickstart](/developers/doc/quickstart) for more details on application creation via the console. + +### With the Clever Tools CLI + +1. Make sure you have clever-tools installed locally or follow our [CLI getting started](/developers/doc/cli/) guide. +2. In your code folder, do `clever create --type --region --org ` where : + 1. `type` is the type of technology you rely on + 2. `app-name` the name you want for your application, + 3. `zone` deployment zone (`par` for Paris and `mtl` for Montreal) + 4. `org` the organisation ID the application will be created under. + +Refer to [clever create](/developers/doc/cli/applications/) for more details on application creation with Clever Tools. diff --git a/shared/db-backup.md b/shared/db-backup.md new file mode 100644 index 000000000..367e169de --- /dev/null +++ b/shared/db-backup.md @@ -0,0 +1,5 @@ +## Database Daily Backup and Retention + +By default, Clever Cloud performs a free backup every day, with a retention of seven days. Retention and frequency can be customized for Premium customers. + +Each backup can be found in the add-on dashboard in the web console, along with the credentials. diff --git a/shared/db-migration.md b/shared/db-migration.md new file mode 100644 index 000000000..dc7d8c540 --- /dev/null +++ b/shared/db-migration.md @@ -0,0 +1,10 @@ +## Migrate your database + +Clever Cloud provides an add-on Migration/Upgrade tool. You can access it from the [Console](https://console.clever-cloud.com), in the left menu when an add-on is selected. It allows to choose a higher plan, a new version or another deployment zone. + +A migration process creates new instances, moves your data into it and stops the old ones if the process ended correctly. In case of a failure during migration, new instances are deleted and you go back to the original ones. +The duration may vary depending on how much data your add-on has. Your database becomes read only for the entire duration. + +If you want to restart your add-on or update to the last supported version of the current branch, migrate it to the same plan, version, zone. + +- [More Clever Cloud Tips and Tricks](/developers/doc/best-practices/tips_and_tricks/) diff --git a/shared/deploy-ftp.md b/shared/deploy-ftp.md new file mode 100644 index 000000000..8843ff3a4 --- /dev/null +++ b/shared/deploy-ftp.md @@ -0,0 +1,13 @@ +## FTP Deployment + +Make sure you have [Filezilla](https://filezilla-project.org/) or an other FTP software installed in your machine. + +When you chose to deploy your application via FTP at the application creation, the system creates a free [FS Bucket](/developers/doc/addons/fs-bucket) with an ID matching your application's ID. + +Find the FTP credentials in the configuration tab of this particular FS Bucket. + +Just follow the instructions of your FTP Software to send code to Clever Cloud. + +⚠️ **An FTP application automatically starts once you create the application, even if you don't send any code yet.** + +Refer to [Quick Start - FTP deployment](/developers/doc/quickstart#ftp-deployment) for more details. diff --git a/shared/deploy-git.md b/shared/deploy-git.md new file mode 100644 index 000000000..2ad620f24 --- /dev/null +++ b/shared/deploy-git.md @@ -0,0 +1,19 @@ +## Git Deployment on Clever Cloud + +*You need Git on your computer to deploy via this tool. Here is the official website of Git to get more information: [git-scm.com](https://git-scm.com)* + +### Setting up your remotes + +1. The "Information" page of your app gives you your Git deployment URL, it looks like this: + 1. `git+ssh://git@push.clever-cloud.com/.git` + 2. Copy it in your clipboard + +2. Locally, under your code folder, type in `git init` to set up a new git repository or skip this step if you already have one + +3. Add the deploy URL with `git remote add ` + +4. Add your files via `git add ` and commit them via `git commit -m ` + +5. Now push your application on Clever Cloud with `git push master` + +Refer to [git deployments](/developers/doc/quickstart) for more details. diff --git a/shared/env-injection.md b/shared/env-injection.md new file mode 100644 index 000000000..9faa39539 --- /dev/null +++ b/shared/env-injection.md @@ -0,0 +1,8 @@ +## Environment injection + +Clever Cloud injects environment variables from your application settings as mentioned in [setting up environment variables](#setting-up-environment-variables-on-clever-cloud) and is also injecting in your application production environment, those from your [linked add-ons](#linking-a-database-or-any-other-add-on-to-your-application). + +### Custom build configurations + +On Clever Cloud you can define some build configuration: like the app folder to deploy or the path to validate your application deployment is ready +To do that follow the [documentation here](/developers/doc/reference/reference-environment-variables/#variables-you-can-define) and add the environment variable you need. diff --git a/shared/git-push.md b/shared/git-push.md new file mode 100644 index 000000000..bba67c947 --- /dev/null +++ b/shared/git-push.md @@ -0,0 +1,21 @@ +## Push your code + +Once you complete these steps, commit your content to the local repository and deploy it: + +```bash +git add . +git commit -m "First deploy" +clever deploy +clever open +``` + +You can display your website's URL or add a custom domain to it (you'll need to configure DNS): + +```bash +clever domain +clever domain add your.website.tld +``` + +## 404 page location + +If you need to use a specific page for 404 errors, define its location with `SERVER_ERROR_PAGE_404` environment variable from Static Web Server, used as default in `static` runtime. For example : `SERVER_ERROR_PAGE_404=404.html`. diff --git a/shared/java-versions.md b/shared/java-versions.md new file mode 100644 index 000000000..de51a9958 --- /dev/null +++ b/shared/java-versions.md @@ -0,0 +1,9 @@ +## Available Java versions + +Set the environment variable `CC_JAVA_VERSION` to the version you want. + +We follow the official Java [roadmap](https://www.oracle.com/java/technologies/java-se-support-roadmap.html) by supporting both LTS and latest non-LTS versions. + +We are using OpenJDK distribution for mentioned Java versions. + +Every non-LTS versions where _Premier support_ ends will be removed without warning as you should be able to switch to the next available non-LTS version without any trouble. diff --git a/shared/kv-explorer.md b/shared/kv-explorer.md new file mode 100644 index 000000000..29ce77bec --- /dev/null +++ b/shared/kv-explorer.md @@ -0,0 +1,21 @@ +## Clever Cloud KV Explorer + +Access and edit your Key-Value databases with the **KV Explorer** tool, it's part of Clever Cloud's all included experience. + +### Supported data types + +Hash, list, set and string types are supported. For Materia KV, only string type is currently available, with other types coming soon. + +### An intuitive, useful interface + +The interface lets you filter keys by type and perform wildcard searches (for example: `*value_to_search*`). Value fields are multi-line for convenience, and you can copy/paste values directly from the interface. Special attention has been paid to accessibility and keyboard navigation with shortcuts to optimize your experience. + +### KV Explorer Terminal + +At the bottom of the page, you'll find an integrated terminal that works like a traditional CLI client. Type your commands and press Enter to execute them. All commands are supported, including `FLUSHDB` and `FLUSHALL`. Be careful with these as they erase data! + +KV Explorer is in Beta testing phase and we'll improve it over the coming months, thanks to your feedback and suggestions. + +- [ Share your feedback on KV Explorer](https://github.com/CleverCloud/Community/discussions/categories/kv-explorer) + +![KV Explorer](/images/kv-explorer.webp "The KV Explorer tool in the Console") diff --git a/shared/link-addon.md b/shared/link-addon.md new file mode 100644 index 000000000..a48f5581c --- /dev/null +++ b/shared/link-addon.md @@ -0,0 +1,15 @@ +## Linking a database or any other add-on to your application + +By linking an application to an add-on, the application has the add-on environment variables in its own environment by default. + +### On add-on creation + +Many add-ons do exist on Clever Cloud: refer to [the full list](/developers/doc/addons) and check add-ons dedicated pages for full instructions. + +During add-on creation, an **Applications** screen appears, with a list of your applications. You can toggle the button to *Link* and click *next*. If you finish the process of add-on creation, the application is automatically linked to it. + +### Add-on already exists + +In the Clever Cloud console, under the **Service Dependencies** menu of your application, you can use the *Link add-ons* dropdown menu to select the name of the add-on you want to link and use the *add* button to finish the process. + +You can also link another application from the same page in the Clever Cloud console, using the *Link applications* dropdown menu. diff --git a/shared/mise.md b/shared/mise.md new file mode 100644 index 000000000..25d285479 --- /dev/null +++ b/shared/mise.md @@ -0,0 +1,7 @@ +### Install tools with Mise package manager + +Mise package manager is a powerful tool to install and manage dependencies on Clever Cloud. Just add a `mise.toml` file at the root of your project or set the `CC_MISE_FILE_PATH` environment variable. All tools will be installed at the defined version before the build phase and available for your scripts. You can also use Mise to define [environment variables](https://mise.jdx.dev/environments/) and alias ([tasks](https://mise.jdx.dev/tasks/)) in a declarative way. + +To disable Mise, set `CC_DISABLE_MISE` environment variable to `true`. + +- [Learn more about Mise package manager](https://mise.jdx.dev/configuration.html) diff --git a/shared/more-config.md b/shared/more-config.md new file mode 100644 index 000000000..039bc3255 --- /dev/null +++ b/shared/more-config.md @@ -0,0 +1,9 @@ +## More configuration + +Need more configuration? To run a script at the end of your deployment? To add your private SSH key to access private dependencies? + +Go check the [Common configuration page](/developers/doc/reference/common-configuration). + +You may want to have an advanced usage of your application, in which case we recommend you to read the **Administrate** documentation section. + +If you can't find something or have a specific need like using a non supported version of a particular software, please reach out to the [support](/developers/doc/find-help/support). diff --git a/shared/new-relic.md b/shared/new-relic.md new file mode 100644 index 000000000..b0fcd57f9 --- /dev/null +++ b/shared/new-relic.md @@ -0,0 +1,5 @@ +### Monitor your application with New Relic + +You can use [New Relic](https://www.newrelic.com/) to monitor your application on Clever Cloud. + +Please refer to our [New Relic documentation](/developers/doc/metrics/new-relic) to configure it for your application. diff --git a/shared/pgpool.md b/shared/pgpool.md new file mode 100644 index 000000000..8b67df536 --- /dev/null +++ b/shared/pgpool.md @@ -0,0 +1,3 @@ +Pgpool-II is a proxy software that sits between PostgreSQL servers and a PostgreSQL database client. + +You can read the [official project page](https://www.pgpool.net/docs/latest/en/html/intro-whatis.html) for more information. diff --git a/shared/proxysql.md b/shared/proxysql.md new file mode 100644 index 000000000..7ac47b6e0 --- /dev/null +++ b/shared/proxysql.md @@ -0,0 +1,4 @@ +ProxySQL is a tool that acts like a proxy between your application and your MySQL add-on. Instead of connecting to your MySQL add-on, you can connect +to the local ProxySQL and it will forward all your requests to your MySQL add-on. + +This allows you to let ProxySQL take care of some interesting features like connection pooling or leader / follower setup. diff --git a/shared/redirectionio.md b/shared/redirectionio.md new file mode 100644 index 000000000..b362b7d7d --- /dev/null +++ b/shared/redirectionio.md @@ -0,0 +1,13 @@ +## Use Redirection.io as a proxy + +[Redirection.io](https://redirection.io) can help reduce HTTP traffic issues on your website. It gives a complete control on how HTTP requests are handled, which helps make it SEO-friendly. It can perform redirections and comes with lots of features. You can link any application to a Redirection.io project easily, setting up the proxy mode with following environment variables: + +| Name | Description | Default value | +|-----------------------|------------------------------|--------------------------------| +| `CC_REDIRECTIONIO_PROJECT_KEY` | The Redirection.io project key | | +| `CC_REDIRECTIONIO_FORWARD_PORT` | The listening port of your application (optional) | | +| `CC_REDIRECTIONIO_INSTANCE_NAME` | The name of your application (optional) | | + +The Redirection.io agent will start as a service, listen to `8080` port and forward the traffic to your application port. + +- [Learn more about Redirection.io](https://redirection.io/) diff --git a/shared/ruby.md b/shared/ruby.md new file mode 100644 index 000000000..b71827dd1 --- /dev/null +++ b/shared/ruby.md @@ -0,0 +1,195 @@ +## Configure your Ruby on Rails application + +### Mandatory configuration + +Be sure that: + +* you push to the **master branch** +* you commit your `gems.locked` or `Gemfile.lock` file +* you have a `config.ru` file (this one is most of the time generated by rails) +* you have `gem puma` in your `Gemfile` (`puma` is the default application server from rails, when creating a new ruby application, an [environment variable](#setting-up-environment-variables-on-clever-cloud) is automatically added: `CC_RACKUP_SERVER=puma`) + +You need to provide a `gems.locked` or `Gemfile.lock` file. To do that ensure you have at least once run `bundle install` in your terminal at the root of your rails project. + +### Choose ruby version + +If you specify a ruby version in your `gems.rb` of `Gemfile`, we'll use it, otherwise; keep reading. + +On your Clever Cloud application create an [environment variable](#setting-up-environment-variables-on-clever-cloud) `CC_RUBY_VERSION=rubyversion` where `rubyversion` represents: + +* "3" will select the greatest "3.X.Y" version available. +* "3.3" will select the greatest "3.3.Y" version available. +* "3.3.1" will select the "3.3.1" version. + +Due to current landscape in ruby applications, the default version is the greatest 3.3.Y. We also provide versions 2.3.Y, 2.4.Y, 2.5.Y, 2.6.Y and 2.7.Y. + +If given `rubyversion` does not match any available version, your deployment will fail. + +### Choose your environment + +You can set the `RUBY_ENV` [environment variable](#setting-up-environment-variables-on-clever-cloud) to the value you want. By default it is set to `production`. +Most used values are `production` and `development` but you can use any custom one as long as you have set up of the required variables for this environment in your `./config/` folder files. + +### Secure configuration of secret key + +There are many way to add secret key to your environment and each one is valid. Clever Cloud provides you a secure way so you don't have to commit any file containing it. + +1. generate the secret key locally with `rake secret` +2. add it to your environment in `./config/secret.yml` with: + + ```yaml + production: + secret_key_base: <%= ENV["SECRET_KEY_BASE"] %> + ``` + +### Configure Rake goals + +You can specify a list of rake goals to execute before the deployment of your application by using the `CC_RAKEGOALS` environment variable. + +The value of this variable must be a comma-separated list of goals, for instance: + +```bash +CC_RAKEGOALS="db:migrate, assets:precompile" +``` + +We do not execute any rake goals by default. + +### Configure Sidekiq + +To run a Sidekiq process in background you will need to enable it with the `CC_ENABLE_SIDEKIQ=true` environment variable. + +Please note you will need a Redis instance to use this feature. + +You can specify multiple Sidekiq configuration files with the `CC_SIDEKIQ_FILES` environment variable. + +The value of this variable must be a comma-separated list of files: + +```bash +CC_SIDEKIQ_FILES="./config/sidekiq_1.yml,./config/sidekiq_2.yml,./config/sidekiq_3.yml" +``` + +**Note:** `CC_SIDEKIQ_FILES` have precedence over `CC_ENABLE_SIDEKIQ` which means that even if `CC_SIDEKIQ_FILES` is defined and `CC_ENABLE_SIDEKIQ` is set to `false`, Sidekiq will still be enabled. + +Each path is the path *from the root of the repository* to a sidekiq configuration file. + +Each file might contain something like this standard sidekiq.yml file: + +```yaml +--- +:concurrency: 4 +:pidfile: tmp/pids/sidekiq_1.pid +:queues: + - [critical, 2] + - default + +production: + :logfile: ./log/sidekiq.log +--- +``` + +### Manage your static files and assets + +Static files are configured with [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 (for example `/public/`) + +**Note**: the path of your folder must be absolute regarding the root of your application. + +**Note**: setting the `STATIC_URL_PREFIX` to `/` will make the deployment to fail. + +If you use the asset pipeline, make sure to include the `assets:precompile` task in the `CC_RAKEGOALS` environment variable value. + +```bash +CC_RAKEGOALS="db:migrate, assets:precompile" +``` + +**Note**: if your project uses `webpacker`, make sure to enable the dedicated build instance option in the **Information** menu of your application in the Clever Cloud console because `webpacker` needs a lot a resources when starting. + +### Using Active Storage and Cellar S3 + +Only for Rails >= 5.2. + +* Enable Active Storage for your application: `$ rails active_storage:install` then `$ rake db:migrate` +* Add `gem "aws-sdk-s3", require: false` to your Gemfile, run `$ bundle install` +* Add `config.active_storage.service = :clevercloud` in `config/environments/production.yml` +* Add in `config/storage.yml`: + + ```yaml + clevercloud: + service: S3 + access_key_id: <%= ENV['CELLAR_ADDON_KEY_ID'] %> + secret_access_key: <%= ENV['CELLAR_ADDON_KEY_SECRET'] %> + region: us-east-1 + bucket: <%= ENV['CELLAR_ADDON_BUCKET_NAME'] %> + endpoint: <%= ENV['CELLAR_ADDON_ENDPOINT'] %> + force_path_style: true + ``` + +* In the clever cloud console create a Cellar S3 storage add-on, name it, link it to your rails application and create a bucket. +* In the environment variables section of your Ruby on Rails application on Clever Cloud add the following environment variables: + + ```bash + CELLAR_ADDON_BUCKET_NAME="" + CELLAR_ADDON_ENDPOINT="https://cellar-c2.services.clever-cloud.com" + ``` + +You can now commit and push your changes. + +Also, you are able to use a Filesystem Bucket to store your static files. Please refer to the +[File System Buckets](/developers/doc/addons/fs-bucket) section. + +### NGINX configuration + +NGINX settings can be configured with [environment variables](#setting-up-environment-variables-on-clever-cloud): + +* `NGINX_READ_TIMEOUT`: the response timeout in seconds. (Default: 300) + +#### Basic authentication + +If you need basic authentication, you can enable it using [environment variables](/developers/doc/reference/reference-environment-variables/#ruby). 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" +} +``` + +### Puma configuration + +Puma reads its configuration from the `config/puma.rb` file. See [the puma documentation](https://github.com/puma/puma/blob/master/README.md) for more information. + +You can override this configuration with [environment variables](#setting-up-environment-variables-on-clever-cloud). +Each of them, when specified, will be preferred over the setting from `config/puma.rb`. + +* `CC_PUMA_WORKERS` overrides the number of workers (for example, `CC_PUMA_WORKERS=2`) +* `CC_PUMA_THREADS` overrides the number of threads per worker, can be a raw number or a range (for example, `CC_PUMA_THREADS=6` or `CC_PUMA_THREADS=4:8`) + +If they are not defined in the environment nor in `config/puma.rb` we will setup the values depending on the size of the scaler your application is running on. +We also fill the `WEB_CONCURRENCY` and `RAILS_MAX_THREADS` environment variable if they are not present as they may be used by rails' puma configuration. + +## Overriding rackup application server + +You can override the puma default server by setting an [environment variable](#setting-up-environment-variables-on-clever-cloud) `CC_RACKUP_SERVER=yourserver`. We do not recommend you do it. diff --git a/shared/set-env-vars.md b/shared/set-env-vars.md new file mode 100644 index 000000000..705e0b690 --- /dev/null +++ b/shared/set-env-vars.md @@ -0,0 +1,18 @@ +## Setting up environment variables on Clever Cloud + +### With the Clever Cloud console + +1. Go to the Clever Cloud console, and find the app you want to fine tune under it's organisation. +2. Find the **Environment variables** menu and select it. +3. In this menu, you will see a form with *VARIABLE_NAME* and *variable value* fields. +4. Fill them with the desired values then select **Add**. +5. Don't forget to "Update Changes" at the end of the menu. + +### With the Clever Tools CLI + +1. Make sure you have clever-tools installed locally. Refer to our [CLI getting started](/developers/doc/cli/). +2. In your code folder, do `clever env set ` + +Refer to [environment variables reference](/developers/doc/reference/reference-environment-variables) for more details on available environment variables on Clever Cloud. + +You can of course create custom ones with the interface we just demonstrated, they will be available for your application. diff --git a/shared/single-sign-on.md b/shared/single-sign-on.md new file mode 100644 index 000000000..2a4c2c4ac --- /dev/null +++ b/shared/single-sign-on.md @@ -0,0 +1,10 @@ + +Clever Cloud has its own SSO (Single Sign-On) authentication to authenticate to various services. All members of your organisation will be able to authenticate to the services in the same organisation, using their Clever Cloud account. When a service needs to authenticate you, it redirects to a login form. Enter your Clever Cloud credentials as well as your 2FA Authentication code if needed. + +![SSO Needed Rights](/images/sso-needed-rights.png) + +If it's the first time you use the Clever Cloud SSO, accept all the tokens permissions listed, otherwise the backend service might not work correctly. If you mistakenly disabled some rights at some point, you have to revoke all tokens generated by this OAuth consumer: + +1. First, go to your user's OAuth token in the [Web console](https://console.clever-cloud.com/users/me/oauth-tokens) +2. Then, find all tokens named `Keycloak Consumer` and revoke them +3. Try to log-in again. The rights list should now be displayed. diff --git a/shared/static-create.md b/shared/static-create.md new file mode 100644 index 000000000..c6466c3a6 --- /dev/null +++ b/shared/static-create.md @@ -0,0 +1,29 @@ + +## Deploy a static application + +You can create an application in our [Console](https://console.clever-cloud.com) or through [Clever Tools](/developers/doc/cli). Install them with `npm` or [any supported package manager](/developers/doc/cli/install/): + +```bash +# Install with npm or any supported method +npm i -g clever-tools + +# Login to Clever Cloud and check it worked +clever login +clever profile +``` + +Go to the folder where you want to create your application, and run the following command: + +```bash +cd myStaticApp +clever create -t static + +# If the folder is not a git repository, initialize it: +git init +``` + +To deploy on Clever Cloud, your local folder need to be an initialized git repository linked to an application. If you already have an application on Clever Cloud and want to link it to the current local folder: + +```bash +clever link your_app_name_or_ID +``` diff --git a/shared/static-deploy.md b/shared/static-deploy.md new file mode 100644 index 000000000..d10988497 --- /dev/null +++ b/shared/static-deploy.md @@ -0,0 +1,21 @@ +### Push your code + +Once you complete these steps, commit your content to the local repository and deploy it: + +```bash +git add . +git commit -m "First deploy" +clever deploy +clever open +``` + +You can display your website's URL or add a custom domain to it (you'll need to configure DNS): + +```bash +clever domain +clever domain add your.website.tld +``` + +### 404 page location + +If you need to use a specific page for 404 errors, define its location with `SERVER_ERROR_PAGE_404` environment variable from Static Web Server, used as default in `static` runtime. For example : `SERVER_ERROR_PAGE_404=404.html`. diff --git a/shared/static-guides.md b/shared/static-guides.md new file mode 100644 index 000000000..97e1ce716 --- /dev/null +++ b/shared/static-guides.md @@ -0,0 +1,11 @@ +{{< cards >}} + {{< card link="/developers/guides/astro" title="Astro" subtitle= "Build and deploy a Astro application on Clever Cloud" icon="astro" >}} + {{< card link="/developers/guides/docusaurus" title="Docusaurus" subtitle= "Build and deploy a static Docusaurus based website on Clever Cloud" icon="docusaurus" >}} + {{< card link="/developers/guides/eleventy" title="Eleventy (11ty)" subtitle= "Build and deploy a static Eleventy (11ty) based website on Clever Cloud" icon="11ty" >}} + {{< card link="/developers/guides/hexo" title="Hexo" subtitle= "Build and deploy a static Hexo based website on Clever Cloud" icon="hexo" >}} + {{< card link="/developers/guides/hugo" title="Hugo" subtitle= "Build and deploy a static Hugo based website on Clever Cloud" icon="hugo" >}} + {{< card link="/developers/guides/lume-deno" title="Lume (Deno)" subtitle= "Build and deploy a static Lume (Deno) based website on Clever Cloud" icon="deno" >}} + {{< card link="/developers/guides/mdbook" title="mdBook" subtitle= "Build and deploy a static mbBook based website on Clever Cloud" icon="mdbook" >}} + {{< card link="/developers/guides/mkdocs" title="MkDocs" subtitle= "Build and deploy a static MkDocs based website on Clever Cloud" icon="docs" >}} + {{< card link="/developers/guides/nuxt" title="Nuxt" subtitle= "Build and deploy a Nuxt application on Clever Cloud" icon="nuxt" >}} +{{< /cards >}} diff --git a/shared/url_healthcheck.md b/shared/url_healthcheck.md new file mode 100644 index 000000000..d726de43c --- /dev/null +++ b/shared/url_healthcheck.md @@ -0,0 +1,42 @@ +## Enable health check during deployment + +The healthcheck allows you to limit downtimes. Indeed, you can provide Clever Cloud with paths to check. If these paths return something other than 200, the deployment will fail. + +Add one (or several) environment variable as such: + +```bash +CC_HEALTH_CHECK_PATH=/my/awesome/path +``` + +Or + +```bash +CC_HEALTH_CHECK_PATH_0=/my/awesome/path +CC_HEALTH_CHECK_PATH_1=/my/other/path +``` + +The deployment process checks all paths. All of them must reply with a `200 OK` response code. + +By default, when no [environment variable](/developers/doc/reference/reference-environment-variables) (for ex: `APP_HOME`) is defined, the monitoring checks your repository root path `/`. + +### Example + +Using the path listed above, below are the expected logs: + +```text +Response from GET /my/awesome/path is 200 +Response from GET /my/other/path is 500 +Health check failed: +- GET /my/other/path returned 500. +If the deployment fails after this message, please update your configuration and redeploy. +``` + +In this example, the first path is OK, but the second one failed. This gives you a hint on what failed in your application. + +### Best practice for healthcheck endpoints + +To make the most of a healthcheck endpoint, have it check your critical dependencies. For example: + +- execute `SELECT 1 + 1;` on your database +- retrieve a specific Cellar file +- ping a specific IP through a VPN diff --git a/shared/varnish.md b/shared/varnish.md new file mode 100644 index 000000000..ede56f14f --- /dev/null +++ b/shared/varnish.md @@ -0,0 +1,5 @@ +## Use Varnish as cache + +Varnish is a powerful HTTP accelerator that can be used to cache your web application's responses, improving performance and reducing load. To use it, create a Varnish configuration file in `clevercloud/varnish.vcl` and configure your application to listen on port `8081`. + +- [Learn more about Varnish on Clever Cloud](/developers/doc/administrate/cache/) diff --git a/static/android-chrome-192x192.png b/static/android-chrome-192x192.png new file mode 100644 index 000000000..a5abf4f6d Binary files /dev/null and b/static/android-chrome-192x192.png differ diff --git a/static/android-chrome-512x512.png b/static/android-chrome-512x512.png new file mode 100644 index 000000000..b69345655 Binary files /dev/null and b/static/android-chrome-512x512.png differ diff --git a/static/apple-touch-icon.png b/static/apple-touch-icon.png new file mode 100644 index 000000000..b36e37587 Binary files /dev/null and b/static/apple-touch-icon.png differ diff --git a/static/cloud-synccloud-icon.png b/static/cloud-synccloud-icon.png new file mode 100644 index 000000000..eb8f9f65f Binary files /dev/null and b/static/cloud-synccloud-icon.png differ diff --git a/static/favicon-16x16.png b/static/favicon-16x16.png new file mode 100644 index 000000000..a513d27a2 Binary files /dev/null and b/static/favicon-16x16.png differ diff --git a/static/favicon-32x32.png b/static/favicon-32x32.png new file mode 100644 index 000000000..05cf45886 Binary files /dev/null and b/static/favicon-32x32.png differ diff --git a/static/favicon-dark.svg b/static/favicon-dark.svg new file mode 100644 index 000000000..758cc1846 --- /dev/null +++ b/static/favicon-dark.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/static/favicon.ico b/static/favicon.ico new file mode 100644 index 000000000..a4e2ecf77 Binary files /dev/null and b/static/favicon.ico differ diff --git a/static/favicon.ico.png b/static/favicon.ico.png new file mode 100644 index 000000000..b2ab15563 Binary files /dev/null and b/static/favicon.ico.png differ diff --git a/static/favicon.svg b/static/favicon.svg new file mode 100644 index 000000000..6297feda2 --- /dev/null +++ b/static/favicon.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/static/fonts/plus-jakarta-sans-v8-latin-700.ttf b/static/fonts/plus-jakarta-sans-v8-latin-700.ttf new file mode 100644 index 000000000..dfe9b7bf1 Binary files /dev/null and b/static/fonts/plus-jakarta-sans-v8-latin-700.ttf differ diff --git a/static/fonts/plus-jakarta-sans-v8-latin-700.woff2 b/static/fonts/plus-jakarta-sans-v8-latin-700.woff2 new file mode 100644 index 000000000..18d8d152f Binary files /dev/null and b/static/fonts/plus-jakarta-sans-v8-latin-700.woff2 differ diff --git a/static/images/404.png b/static/images/404.png new file mode 100644 index 000000000..7921d1be5 Binary files /dev/null and b/static/images/404.png differ diff --git a/static/images/TCP_redirection_console.png b/static/images/TCP_redirection_console.png new file mode 100644 index 000000000..9c85f413b Binary files /dev/null and b/static/images/TCP_redirection_console.png differ diff --git a/static/images/activity.png b/static/images/activity.png new file mode 100644 index 000000000..850f2d925 Binary files /dev/null and b/static/images/activity.png differ diff --git a/static/images/addon-dashboard.png b/static/images/addon-dashboard.png new file mode 100644 index 000000000..65cdaed68 Binary files /dev/null and b/static/images/addon-dashboard.png differ diff --git a/static/images/analytics.png b/static/images/analytics.png new file mode 100644 index 000000000..8defce3ce Binary files /dev/null and b/static/images/analytics.png differ diff --git a/static/images/app-management.png b/static/images/app-management.png new file mode 100644 index 000000000..b053a470d Binary files /dev/null and b/static/images/app-management.png differ diff --git a/static/images/application-edit.png b/static/images/application-edit.png new file mode 100644 index 000000000..4e5194064 Binary files /dev/null and b/static/images/application-edit.png differ diff --git a/static/images/billing-infos.png b/static/images/billing-infos.png new file mode 100644 index 000000000..d353232d6 Binary files /dev/null and b/static/images/billing-infos.png differ diff --git a/static/images/brand.png b/static/images/brand.png new file mode 100644 index 000000000..4394fb643 Binary files /dev/null and b/static/images/brand.png differ diff --git a/static/images/ccpm-2024-08-02-image_0.png b/static/images/ccpm-2024-08-02-image_0.png new file mode 100644 index 000000000..322844202 Binary files /dev/null and b/static/images/ccpm-2024-08-02-image_0.png differ diff --git a/static/images/clever-cloud-runners-basic-with-runtimes-alt.svg b/static/images/clever-cloud-runners-basic-with-runtimes-alt.svg new file mode 100644 index 000000000..393bc4900 --- /dev/null +++ b/static/images/clever-cloud-runners-basic-with-runtimes-alt.svg @@ -0,0 +1,5364 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + Franck Bret + + + + + Octobus + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/static/images/clever-tasks.webp b/static/images/clever-tasks.webp new file mode 100644 index 000000000..f15b54484 Binary files /dev/null and b/static/images/clever-tasks.webp differ diff --git a/static/images/clever-tools-metabase-version-check.webp b/static/images/clever-tools-metabase-version-check.webp new file mode 100644 index 000000000..fa774c7e8 Binary files /dev/null and b/static/images/clever-tools-metabase-version-check.webp differ diff --git a/static/images/clever-tools-new-create.webp b/static/images/clever-tools-new-create.webp new file mode 100644 index 000000000..015cadf2c Binary files /dev/null and b/static/images/clever-tools-new-create.webp differ diff --git a/static/images/cloudflare-https-setting.png b/static/images/cloudflare-https-setting.png new file mode 100644 index 000000000..95b7e6fce Binary files /dev/null and b/static/images/cloudflare-https-setting.png differ diff --git a/static/images/cloudflare-page-rule-ssl.png b/static/images/cloudflare-page-rule-ssl.png new file mode 100644 index 000000000..141dc8f07 Binary files /dev/null and b/static/images/cloudflare-page-rule-ssl.png differ diff --git a/static/images/console-api-tokens-tips.webp b/static/images/console-api-tokens-tips.webp new file mode 100644 index 000000000..4604e07cb Binary files /dev/null and b/static/images/console-api-tokens-tips.webp differ diff --git a/static/images/console-api-tokens.webp b/static/images/console-api-tokens.webp new file mode 100644 index 000000000..0addaf091 Binary files /dev/null and b/static/images/console-api-tokens.webp differ diff --git a/static/images/console-new-ip-par.webp b/static/images/console-new-ip-par.webp new file mode 100644 index 000000000..168213e72 Binary files /dev/null and b/static/images/console-new-ip-par.webp differ diff --git a/static/images/console-new-oauth-tokens.webp b/static/images/console-new-oauth-tokens.webp new file mode 100644 index 000000000..e7000691d Binary files /dev/null and b/static/images/console-new-oauth-tokens.webp differ diff --git a/static/images/console-sessions.webp b/static/images/console-sessions.webp new file mode 100644 index 000000000..b6a857b43 Binary files /dev/null and b/static/images/console-sessions.webp differ diff --git a/static/images/doc-link-console.webp b/static/images/doc-link-console.webp new file mode 100644 index 000000000..199eec729 Binary files /dev/null and b/static/images/doc-link-console.webp differ diff --git a/static/images/feature.png b/static/images/feature.png new file mode 100644 index 000000000..5ceef479a Binary files /dev/null and b/static/images/feature.png differ diff --git a/static/images/github-branches.png b/static/images/github-branches.png new file mode 100644 index 000000000..a704c2b06 Binary files /dev/null and b/static/images/github-branches.png differ diff --git a/static/images/github-deployment-branch.png b/static/images/github-deployment-branch.png new file mode 100644 index 000000000..42597ff01 Binary files /dev/null and b/static/images/github-deployment-branch.png differ diff --git a/static/images/grafana-alerts.png b/static/images/grafana-alerts.png new file mode 100644 index 000000000..a46cab5c8 Binary files /dev/null and b/static/images/grafana-alerts.png differ diff --git a/static/images/grafana-from-oveview-pane.png b/static/images/grafana-from-oveview-pane.png new file mode 100644 index 000000000..96b509e2a Binary files /dev/null and b/static/images/grafana-from-oveview-pane.png differ diff --git a/static/images/heptapod-billing.png b/static/images/heptapod-billing.png new file mode 100644 index 000000000..e80194e4d Binary files /dev/null and b/static/images/heptapod-billing.png differ diff --git a/static/images/icons.png b/static/images/icons.png new file mode 100644 index 000000000..452f05323 Binary files /dev/null and b/static/images/icons.png differ diff --git a/static/images/invoice-amount-to-pay.png b/static/images/invoice-amount-to-pay.png new file mode 100644 index 000000000..435bc3765 Binary files /dev/null and b/static/images/invoice-amount-to-pay.png differ diff --git a/static/images/invoice-credits-balance.png b/static/images/invoice-credits-balance.png new file mode 100644 index 000000000..0d2ce8a06 Binary files /dev/null and b/static/images/invoice-credits-balance.png differ diff --git a/static/images/invoice-list.png b/static/images/invoice-list.png new file mode 100644 index 000000000..65642a45c Binary files /dev/null and b/static/images/invoice-list.png differ diff --git a/static/images/invoice-runtime-detail.png b/static/images/invoice-runtime-detail.png new file mode 100644 index 000000000..9ca4db8f3 Binary files /dev/null and b/static/images/invoice-runtime-detail.png differ diff --git a/static/images/jenkins/cloud-configuration.png b/static/images/jenkins/cloud-configuration.png new file mode 100644 index 000000000..1bc18af58 Binary files /dev/null and b/static/images/jenkins/cloud-configuration.png differ diff --git a/static/images/jenkins/full-dashboard.png b/static/images/jenkins/full-dashboard.png new file mode 100644 index 000000000..689f5ad2a Binary files /dev/null and b/static/images/jenkins/full-dashboard.png differ diff --git a/static/images/jenkins/jobs-history.png b/static/images/jenkins/jobs-history.png new file mode 100644 index 000000000..05b8f7955 Binary files /dev/null and b/static/images/jenkins/jobs-history.png differ diff --git a/static/images/jenkins/runner-deploying.png b/static/images/jenkins/runner-deploying.png new file mode 100644 index 000000000..7678e383d Binary files /dev/null and b/static/images/jenkins/runner-deploying.png differ diff --git a/static/images/jenkins/update-available-cc-dashboard.png b/static/images/jenkins/update-available-cc-dashboard.png new file mode 100644 index 000000000..d22b392d8 Binary files /dev/null and b/static/images/jenkins/update-available-cc-dashboard.png differ diff --git a/static/images/jenkins/update-available.png b/static/images/jenkins/update-available.png new file mode 100644 index 000000000..97824cd54 Binary files /dev/null and b/static/images/jenkins/update-available.png differ diff --git a/static/images/kv-explorer.webp b/static/images/kv-explorer.webp new file mode 100644 index 000000000..377886666 Binary files /dev/null and b/static/images/kv-explorer.webp differ diff --git a/static/images/logo-dark.svg b/static/images/logo-dark.svg new file mode 100644 index 000000000..6b03a715e --- /dev/null +++ b/static/images/logo-dark.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/static/images/logo.svg b/static/images/logo.svg new file mode 100644 index 000000000..45829f5b7 --- /dev/null +++ b/static/images/logo.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/static/images/matomo/full-dashboard.png b/static/images/matomo/full-dashboard.png new file mode 100644 index 000000000..7ad95f994 Binary files /dev/null and b/static/images/matomo/full-dashboard.png differ diff --git a/static/images/metrics-home.png b/static/images/metrics-home.png new file mode 100644 index 000000000..22c3d3f52 Binary files /dev/null and b/static/images/metrics-home.png differ diff --git a/static/images/monitoring.png b/static/images/monitoring.png new file mode 100644 index 000000000..a5659d44d Binary files /dev/null and b/static/images/monitoring.png differ diff --git a/static/images/new-logs-update.webp b/static/images/new-logs-update.webp new file mode 100644 index 000000000..083a2fff0 Binary files /dev/null and b/static/images/new-logs-update.webp differ diff --git a/static/images/new-logs.webp b/static/images/new-logs.webp new file mode 100644 index 000000000..c6a0d3d61 Binary files /dev/null and b/static/images/new-logs.webp differ diff --git a/static/images/new-oauth-consumer.webp b/static/images/new-oauth-consumer.webp new file mode 100644 index 000000000..1590c1dc2 Binary files /dev/null and b/static/images/new-oauth-consumer.webp differ diff --git a/static/images/open_the_app_ico.png b/static/images/open_the_app_ico.png new file mode 100644 index 000000000..d300ae966 Binary files /dev/null and b/static/images/open_the_app_ico.png differ diff --git a/static/images/pg-studio.png b/static/images/pg-studio.png new file mode 100644 index 000000000..188a9bfce Binary files /dev/null and b/static/images/pg-studio.png differ diff --git a/static/images/primary-domain-link.webp b/static/images/primary-domain-link.webp new file mode 100644 index 000000000..c181964d7 Binary files /dev/null and b/static/images/primary-domain-link.webp differ diff --git a/static/images/scaling_horizontal_scheme.jpg b/static/images/scaling_horizontal_scheme.jpg new file mode 100644 index 000000000..d98fd8001 Binary files /dev/null and b/static/images/scaling_horizontal_scheme.jpg differ diff --git a/static/images/scaling_vertical_scheme.jpg b/static/images/scaling_vertical_scheme.jpg new file mode 100644 index 000000000..d8dfab6ff Binary files /dev/null and b/static/images/scaling_vertical_scheme.jpg differ diff --git a/static/images/schema-config-provider-01.svg b/static/images/schema-config-provider-01.svg new file mode 100755 index 000000000..86540a08e --- /dev/null +++ b/static/images/schema-config-provider-01.svg @@ -0,0 +1,4094 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + shipping-api + PULSAR_TOPIC=orderUSER_API_HOST=https://user.example.com/apiENABLE_PARTNERS=true + + + + + + + + + + + payment-api + PULSAR_TOPIC=orderUSER_API_HOST=https://user.example.com/apiENABLE_SEPA=false + + + + + + + + + + + + + diff --git a/static/images/schema-config-provider-02.svg b/static/images/schema-config-provider-02.svg new file mode 100755 index 000000000..a201d5380 --- /dev/null +++ b/static/images/schema-config-provider-02.svg @@ -0,0 +1,4087 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + shipping-api + PULSAR_TOPIC=orderUSER_API_HOST=https://user.example.com/apiENABLE_PARTNERS=true + + + + + + + + + + + + + payment-api + PULSAR_TOPIC=orderUSER_API_HOST=https://user.example.com/apiENABLE_SEPA=false + + + + + + + + + + + + +   +   + + + + + + + my-config + PULSAR_TOPIC=orderUSER_API_HOST=https://user.example.com/api + + + + + + + + + + + + shipping-api + ENABLE_PARTNERS=true + + + + + + + + + + + payment-api + ENABLE_SEPA=false + + + + + + + + + + + diff --git a/static/images/schema-config-provider-03.svg b/static/images/schema-config-provider-03.svg new file mode 100755 index 000000000..ff99dd867 --- /dev/null +++ b/static/images/schema-config-provider-03.svg @@ -0,0 +1,4087 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + shipping-api + PULSAR_TOPIC=orderUSER_API_HOST=https://user.example.com/apiENABLE_PARTNERS=true + + + + + + + + + + + + + payment-api + PULSAR_TOPIC=orderUSER_API_HOST=https://user.example.com/apiENABLE_SEPA=false + + + + + + + + + + + + +   +   + + + + + + + my-config + PULSAR_TOPIC=orderUSER_API_HOST=https://user.example.com/api + + + + + + + + + + + + + shipping-api + ENABLE_PARTNERS=true + + + + + + + + + + + + + payment-api + ENABLE_SEPA=false + + + + + + + + + + + +   +   + + + + + + + my-config + PULSAR_TOPIC=orderUSER_API_HOST=https://user.example.com/api + + + + + + + + + + + + shipping-api + PULSAR_TOPIC=order_2ENABLE_PARTNERS=true + + + + + + + + + + + payment-api + ENABLE_SEPA=false + + + + + + + + + + diff --git a/static/images/select-scalab-horizontal.png b/static/images/select-scalab-horizontal.png new file mode 100644 index 000000000..2a4ca0860 Binary files /dev/null and b/static/images/select-scalab-horizontal.png differ diff --git a/static/images/select-scalab.png b/static/images/select-scalab.png new file mode 100644 index 000000000..7ac9d4a5e Binary files /dev/null and b/static/images/select-scalab.png differ diff --git a/static/images/service-dependencies-config-update.png b/static/images/service-dependencies-config-update.png new file mode 100644 index 000000000..ca21aac90 Binary files /dev/null and b/static/images/service-dependencies-config-update.png differ diff --git a/static/images/service-dependencies-example.png b/static/images/service-dependencies-example.png new file mode 100644 index 000000000..839f58947 Binary files /dev/null and b/static/images/service-dependencies-example.png differ diff --git a/static/images/sso-needed-rights.png b/static/images/sso-needed-rights.png new file mode 100644 index 000000000..2e88eb269 Binary files /dev/null and b/static/images/sso-needed-rights.png differ diff --git a/static/site.webmanifest b/static/site.webmanifest new file mode 100644 index 000000000..7ea5524af --- /dev/null +++ b/static/site.webmanifest @@ -0,0 +1,20 @@ +{ + "name": "Clever Cloud Documentation", + "short_name": "Clever Doc", + "start_url": "index.html", + "icons": [ + { + "src": "android-chrome-192x192.png", + "sizes": "192x192", + "type": "image/png" + }, + { + "src": "android-chrome-512x512.png", + "sizes": "512x512", + "type": "image/png" + } + ], + "theme_color": "#000000", + "background_color": "#000000", + "display": "standalone" +} \ No newline at end of file diff --git a/themes/hugo-docsearch/layouts/partials/docsearch.html b/themes/hugo-docsearch/layouts/partials/docsearch.html new file mode 100644 index 000000000..cd6d3cb41 --- /dev/null +++ b/themes/hugo-docsearch/layouts/partials/docsearch.html @@ -0,0 +1,3 @@ + + +{{ partial "docsearch.html" . }} diff --git a/update-cli-reference.sh b/update-cli-reference.sh new file mode 100755 index 000000000..4a9e95ec1 --- /dev/null +++ b/update-cli-reference.sh @@ -0,0 +1,21 @@ +#!/bin/bash + +FILE="content/doc/reference/cli.md" +URL="https://raw.githubusercontent.com/CleverCloud/clever-tools/refs/heads/davlgd-ai-doc/docs/llms-documentation.md" + +front_matter="""--- +type: docs +linkTitle: CLI reference +title: Clever Tools - CLI commands reference +description: Clever Tools commands reference to create and manage Clever Cloud applications, add-ons and services. Ideal to provide to LLMS and AI assisted IDEs. +comments: false +aliases: +- /doc/reference/clever-tools/configure +- /doc/reference/clever-tools/manage +- /reference/clever-tools +- /reference/clever-tools/getting_started +--- +""" + +echo "${front_matter}" > "${FILE}" +curl -fSL "${URL}" >> "${FILE}"