From 6797ee667fa5da5466a7e1d280c4cff559400886 Mon Sep 17 00:00:00 2001 From: wsoyinka Date: Sat, 4 Oct 2025 16:53:00 -0400 Subject: [PATCH 1/7] This commit introduces a new, comprehensive, multi-part guide for using cloud-init on Rocky Linux --- docs/guides/virtualization/cloud-init/.pages | 11 + .../cloud-init/01_fundamentals.md | 89 +++++++ .../cloud-init/02_first_contact.md | 151 ++++++++++++ .../cloud-init/03_configuration_engine.md | 171 +++++++++++++ .../cloud-init/04_advanced_provisioning.md | 227 ++++++++++++++++++ .../05_image_builders_perspective.md | 130 ++++++++++ .../cloud-init/06_troubleshooting.md | 105 ++++++++ .../cloud-init/07_contributing.md | 132 ++++++++++ .../guides/virtualization/cloud-init/index.md | 34 +++ 9 files changed, 1050 insertions(+) create mode 100644 docs/guides/virtualization/cloud-init/.pages create mode 100644 docs/guides/virtualization/cloud-init/01_fundamentals.md create mode 100644 docs/guides/virtualization/cloud-init/02_first_contact.md create mode 100644 docs/guides/virtualization/cloud-init/03_configuration_engine.md create mode 100644 docs/guides/virtualization/cloud-init/04_advanced_provisioning.md create mode 100644 docs/guides/virtualization/cloud-init/05_image_builders_perspective.md create mode 100644 docs/guides/virtualization/cloud-init/06_troubleshooting.md create mode 100644 docs/guides/virtualization/cloud-init/07_contributing.md create mode 100644 docs/guides/virtualization/cloud-init/index.md diff --git a/docs/guides/virtualization/cloud-init/.pages b/docs/guides/virtualization/cloud-init/.pages new file mode 100644 index 0000000000..3c9bfbb5bf --- /dev/null +++ b/docs/guides/virtualization/cloud-init/.pages @@ -0,0 +1,11 @@ +# Navigation for the cloud-init Guide + +nav: + - ... | index.md + - ... | 01_fundamentals.md + - ... | 02_first_contact.md + - ... | 03_configuration_engine.md + - ... | 04_advanced_provisioning.md + - ... | 05_image_builders_perspective.md + - ... | 06_troubleshooting.md + - ... | 07_contributing.md diff --git a/docs/guides/virtualization/cloud-init/01_fundamentals.md b/docs/guides/virtualization/cloud-init/01_fundamentals.md new file mode 100644 index 0000000000..bf4bb93e08 --- /dev/null +++ b/docs/guides/virtualization/cloud-init/01_fundamentals.md @@ -0,0 +1,89 @@ +--- +Title: I. cloud-init Fundamentals: The Architecture of First Boot +author: Wale Soyinka +contributors: +tags: + - cloud-init + - cloud + - automation +--- + + +# **I. cloud-init Fundamentals: The Architecture of First Boot** + +This guide explores `cloud-init`, the essential tool for automating the initial setup of your Rocky Linux 10 cloud instances. When we talk about deploying servers in the cloud—or even in your local virtualization lab—we often take for granted the almost instantaneous transition from a blank image to a fully functional, network-ready machine. This feat of digital alchemy is performed by a single, tireless utility: cloud-init. + +## **1. The Bootstrapping Conundrum** + +### **The Problem: When a Server Wakes Up Blind** + +Imagine a generic Rocky Linux 10 QCOW2 image. It’s a perfect, pristine copy, unaware of its final destination. It doesn’t know its hostname, which user account should have SSH access, what timezone it’s in, or if it needs Apache or NGINX. + +If you were deploying physical hardware, a system administrator would manually configure all these parameters. But in the cloud, servers are ephemeral, scaled up and down by the thousands. We need a standardized, generic, and reliable mechanism to inject the necessary context into that blank image the very first time it boots. + +This is the problem **cloud-init** solves. + +### **What is cloud-init?** + +Simply put, cloud-init is the industry-standard multi-distribution package that handles early initialization of cloud instances. It is the core service responsible for taking a generic image (like the one we’re using) and performing the required configuration tasks to transform it into a unique, production-ready server. + +It literally sits at the heart of the provisioning process, interpreting **metadata** and **user-defined instructions** to set up the system. Without it, your cloud instance is just a beautifully compiled Linux kernel with an identity crisis. + +### **The cloud-init Ecosystem** + +cloud-init is a consumer, not a creator. It relies on the underlying cloud platform (AWS, Azure, GCP, OpenStack, or local tools like libvirt) to provide it with configuration information. + +* **Cloud Providers** expose data via a specialized *data source* (often a local HTTP endpoint, a specific disk label, or a kernel parameter). +* **cloud-init** detects this data source, reads the configuration, and executes the appropriate configuration steps. + +This decoupling—where the image is generic and the configuration is provided externally—is the fundamental genius of the entire cloud deployment model. + +## **2. Rocky Linux 10 and the Generic Cloud Image** + +For this guide, we'll be using the official [Rocky-10-GenericCloud-Base.latest.x86_64.qcow2](https://dl.rockylinux.org/pub/rocky/10/images/x86_64/Rocky-10-GenericCloud-Base.latest.x86_64.qcow2). + +### **The Target Image: A Pre-Wired Workhorse** + +This image is special because it comes with the cloud-init package pre-installed and enabled. It has been *generalized*, meaning all machine-specific identifiers, SSH host keys, and log files have been stripped out. It’s ready to receive its new identity on first boot. + +!!! warning "Use the Recommended Image" + If you attempt to use cloud-init on a standard Rocky Linux installation (like a minimal ISO install), you’ll find it’s not present by default. Stick to the **Generic Cloud image** to avoid needless complexity and ensure everything works exactly as the doctor prescribed. Attempting the exercises in this guide with other images will likely fail and is not supported. + +### **Core Concepts: User-Data vs. Meta-Data** + +The configuration information that cloud-init processes is categorized into two key types. Understanding this distinction is critical to knowing what you can control and what the cloud provider controls. + +Think of it like building a house: **Meta-Data** is the street address assigned by the city, while **User-Data** is the blueprint you provide for the interior design. + +| Data Type | Source & Purpose | Configuration Type | +| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------ | :------------------ | +| **Meta-Data** | Provided by the cloud platform (read-only). Contains system identifiers like instance ID, hostname (if provided by the platform), region, and availability zone. | *System Context* | +| **User-Data** | Provided by the user. This is your instruction set—YAML configuration blocks or shell scripts that customize the server. | *User Instructions* | + +**Meta-Data** tells cloud-init *where* it is. **User-Data** tells cloud-init *what to do*. + +We will focus primarily on crafting effective **User-Data** files, which typically start with the mandatory YAML header: + +```yaml +#cloud-config +``` + +## **3. The Lifecycle: cloud-init's Four Stages of Initialization** + +cloud-init doesn't just run a script and exit; it executes a series of highly structured stages that align with the server's boot process. This methodical approach ensures that dependencies are met (e.g., networking is configured before packages are downloaded). + +Understanding this lifecycle is crucial for debugging and knowing precisely when your custom instructions are executed. + +| Stage | Timing & Description | Key Actions/Modules | +| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | +| **Generator** | Runs very early in the boot process. Sets up internal directories and performs basic configuration checks. | Internal setup, log initialisation. | +| **Local** | Runs before the network is necessarily up. It processes local data sources like CD-ROM or virtual drives (which we'll use in our lab). | Setting hostname from local data, initial disk setup. | +| **Network** | Runs once networking is fully configured and operational. It queries network-based data sources (like the cloud provider's API). | Configure network interfaces, fetch keys from network metadata. | +| **Final** | Runs last. This is where the majority of user-defined configuration takes place, as all prerequisites (users, network, disks) are now ready. | Installing packages, running custom scripts (runcmd), writing files (write_files), system clean-up. | + +!!! tip "Check the Logs" + When troubleshooting, always check `/var/log/cloud-init.log`. This file is the forensic report of the `cloud-init` process, showing exactly when each stage began and finished, and what modules were executed along the way. If your script didn't run, the log will tell you exactly why, and which stage failed. + +## What's Next? + +Now that you understand the fundamental architecture of `cloud-init`—the "what" and "why," the different data types, and the boot stages—you are ready to move from theory to practice. The next chapter will guide you through your first hands-on exercise: booting the Rocky Linux 10 cloud image and performing a simple, real-world customization. \ No newline at end of file diff --git a/docs/guides/virtualization/cloud-init/02_first_contact.md b/docs/guides/virtualization/cloud-init/02_first_contact.md new file mode 100644 index 0000000000..61fef7e629 --- /dev/null +++ b/docs/guides/virtualization/cloud-init/02_first_contact.md @@ -0,0 +1,151 @@ +--- +Title: II. First Contact: Simple Bootstrapping +author: Wale Soyinka +contributors: +tags: + - cloud-init + - cloud + - automation +--- + + +# **II. First Contact: Simple Bootstrapping with the Rocky Linux 10 QCOW2 Image** + +In the previous chapter, we covered the fundamental concepts of `cloud-init`. Now, it’s time to move from theory to practice. This chapter is your first hands-on mission: you will take the official Rocky Linux 10 Generic Cloud image, provide it with a simple set of instructions, and watch it configure itself on first boot. + +## **1. Prepping the Lab Environment** + +Before we can boot our first instance, we need to prepare our local lab environment. For these exercises, we will simulate a cloud environment using standard Linux virtualization tools. + +### **Prerequisites: Host Tools** + +Ensure you have the following tools installed on your host machine. On a Rocky Linux host, you can install them with `dnf`: + +```bash +sudo dnf install -y libvirt qemu-kvm virt-install genisoimage +``` + +* **Virtualization Hypervisor:** A tool like KVM/QEMU or VirtualBox. +* `virt-install`: A command-line utility for provisioning new virtual machines. +* `genisoimage` (or `mkisofs`): A tool to create an ISO9660 filesystem. + +### **The QCOW2 Image** + +If you haven't already, download the official Rocky Linux 10 Generic Cloud image. + +```bash +curl -L -o Rocky-10-GenericCloud.qcow2 \ +https://dl.rockylinux.org/pub/rocky/10/images/x86_64/Rocky-10-GenericCloud-Base.latest.x86_64.qcow2 +``` + +To preserve the original, create a working copy of the image for your VM. + +```bash +cp Rocky-10-GenericCloud.qcow2 first-boot-vm.qcow2 +``` + +!!! tip "Save Disk Space with Backing Files" + A full copy of the image can be large. To save disk space, you can create a *linked clone* that uses the original image as a backing file. This creates a much smaller `qcow2` file that only stores the differences from the original. + + ```bash + qemu-img create -f qcow2 -F qcow2 \ + -b Rocky-10-GenericCloud.qcow2 first-boot-vm.qcow2 + ``` + +## **2. Method 1: The `NoCloud` Datasource (ISO)** + +One of the most common ways to provide data to `cloud-init` in a local environment is the `NoCloud` datasource. This method requires packaging our configuration files into a virtual CD-ROM (an ISO file) that `cloud-init` will automatically detect and read on boot. + +### **Creating the Configuration Files** + +1. **Create a directory for your configuration files:** + ```bash + mkdir cloud-init-data + ``` + +2. **Create the `user-data` file:** This file is your primary instruction set. We will use a `cat` heredoc to create it. + ```bash + cat < cloud-init-data/user-data + #cloud-config + hostname: cloud-rockstar-01 + runcmd: + - [ sh, -c, "echo 'Hello from the cloud-init Final Stage!' > /root/boot_done.txt" ] + EOF + ``` + +3. **Create the `meta-data` file:** This file provides context *about* the instance. The `instance-id` is particularly important, as `cloud-init` uses it to determine if it has run on this instance before. Changing the ID will cause `cloud-init` to run again. + ```bash + cat < cloud-init-data/meta-data + { + "instance-id": "i-first-boot-01", + "local-hostname": "cloud-rockstar-01" + } + EOF + ``` + +4. **Generate the ISO:** Use `genisoimage` to package the files into `config.iso`. The volume label `-V cidata` is the magic key that `cloud-init` looks for. + ```bash + genisoimage -o config.iso -V cidata -r -J cloud-init-data + ``` + +### **Booting and Verification** + +1. **Launch the VM** with `virt-install`, attaching both the VM image and the `config.iso`. + ```bash + virt-install --name rocky10-iso-boot \ + --memory 2048 --vcpus 2 \ + --disk path=first-boot-vm.qcow2,format=qcow2 \ + --disk path=config.iso,device=cdrom \ + --os-variant rockylinux10 \ + --import --noautoconsole + ``` + +2. **Find the IP and connect via SSH.** The default user is `rocky`. + ```bash + virsh domifaddr rocky10-iso-boot + ssh rocky@ + ``` + !!! tip "Secure Logins with SSH Keys" + Connecting with a default user is convenient for a quick lab test, but it is not a secure practice. In the next chapter, we will explore how to use `cloud-init` to automatically inject your SSH public key, allowing for secure, passwordless logins. + +3. **Verify the changes:** Check the hostname and the file created by `runcmd`. + ```bash + hostname + sudo cat /root/boot_done.txt + ``` + +## **3. Method 2: Direct Injection with `virt-install`** + +Creating an ISO is a reliable method, but for users of `libvirt` and `virt-install`, there is a much simpler way. The `--cloud-init` flag allows you to pass `user-data` directly, letting `virt-install` handle the creation of the datasource automatically. + +### **Simplified `user-data`** + +Create a simple `user-data.yml` file. You can even add the SSH key pre-emptively. + +```bash +cat < user-data.yml +#cloud-config +users: + - name: rocky + ssh_authorized_keys: + - +EOF +``` + +### **Booting and Verification** + +1. **Launch the VM** using the `--cloud-init` flag. Notice we can set the hostname here directly. + ```bash + virt-install --name rocky10-direct-boot \ + --memory 2048 --vcpus 2 \ + --disk path=first-boot-vm.qcow2,format=qcow2 \ + --cloud-init user-data=user-data.yml,hostname=cloud-rockstar-02 \ + --os-variant rockylinux10 \ + --import --noautoconsole + ``` + +2. **Find the IP and connect.** If you added your SSH key, you should be able to connect without a password. + +3. **Verify the hostname.** It should be `cloud-rockstar-02`. + +This direct method is often faster and more convenient for local development and testing with `libvirt`. diff --git a/docs/guides/virtualization/cloud-init/03_configuration_engine.md b/docs/guides/virtualization/cloud-init/03_configuration_engine.md new file mode 100644 index 0000000000..b1ddea183d --- /dev/null +++ b/docs/guides/virtualization/cloud-init/03_configuration_engine.md @@ -0,0 +1,171 @@ +--- +title: III. The Configuration Engine: Deep Dive into cloud-init Modules +author: Wale Soyinka +contributors: +tags: + - cloud-init + - rocky linux + - cloud + - automation +--- + +# **III. The Configuration Engine: Deep Dive into cloud-init Modules** + +In the last chapter, you successfully booted a cloud image and performed a simple customization. While effective, the true power, portability, and idempotency of `cloud-init` are unlocked through its module system. These modules are the specialized tools in the `cloud-init` toolkit, designed to handle specific configuration tasks in a declarative and predictable way. + +This chapter dives deep into the module system, explaining what modules are, how they work, and how to use the most essential ones to build a well-configured server. + +## **1. The Anatomy of Configuration** + +### **What are cloud-init Modules?** + +A `cloud-init` module is a specialized Python script designed to handle a single, discrete provisioning task. Think of them as plugins for tasks like managing users, installing packages, or writing files. + +The key advantage of using modules over simple scripts (like `runcmd`) is **idempotency**. An idempotent operation produces the same result whether you run it once or ten times. When you declare that a user should exist, the module ensures that state is met—it will create the user if it doesn't exist, but do nothing if it already does. This makes your configurations reliable and repeatable. + +### **The `#cloud-config` Format Revisited** + +When `cloud-init` sees the `#cloud-config` header, it interprets the file as a YAML-formatted instruction set. The top-level keys in this YAML file map directly to `cloud-init` modules. + +### **Module Execution and Order** + +Modules run at specific stages of the boot process in a sequence defined in `/etc/cloud/cloud.cfg`. A simplified view of this flow looks like this: + +``` +System Boot + | + +--- Stage: Generator (Very early boot) + | `--- cloud_init_modules (e.g., migrator) + | + +--- Stage: Local (Pre-network) + | `--- (Modules for local device setup) + | + +--- Stage: Network (Network is up) + | `--- cloud_config_modules (e.g., users-groups, packages, write_files) + | + `--- Stage: Final (Late boot) + `--- cloud_final_modules (e.g., runcmd, scripts-user) +``` + +The order is critical. For example, the `users-groups` module runs before `runcmd`, ensuring a script can be run by a user who was just created in the same configuration. + +!!! tip "Customizing `cloud-init` Behavior" + While `/etc/cloud/cloud.cfg` defines the default behavior, you should never edit it directly. For persistent, system-wide customizations, place your own `.cfg` files in the `/etc/cloud/cloud.cfg.d/` directory. This is the standard practice for building custom images, which we will explore in a later chapter. + +## **2. High-Utility Modules: The Daily Drivers** + +Let's get hands-on with the most common modules using the direct injection method with `virt-install`. + +### **Module Deep Dive: `users` and `groups`** + +Properly managing user accounts is the cornerstone of securing a new server instance. The `users` module is your primary tool for this, allowing you to create new users, modify existing ones, manage group memberships, and, most importantly, inject SSH keys to facilitate secure, passwordless logins from the very first boot. + +**Example 1: Creating a New Admin User** + +In this example, we will provision a new, dedicated administrative user named `sysadmin`. We will grant this user passwordless `sudo` capabilities by adding them to the `wheel` group and providing a specific `sudo` rule. We will also inject an SSH public key to ensure secure access. + +1. **Create `user-data.yml`:** + ```bash + cat < user-data.yml + #cloud-config + users: + - name: sysadmin + groups: [ wheel ] + sudo: [ "ALL=(ALL) NOPASSWD:ALL" ] + shell: /bin/bash + ssh_authorized_keys: + - + EOF + ``` + +2. **Key Directives Explained:** + * `name`: The username for the new account. + * `groups`: A list of groups to add the user to. On Rocky Linux, membership in the `wheel` group is commonly used to grant administrative rights. + * `sudo`: A list of `sudoers` rules to apply. The rule `ALL=(ALL) NOPASSWD:ALL` grants the user the ability to run any command with `sudo` without being prompted for a password. + * `ssh_authorized_keys`: A list of public SSH keys to add to the user's `~/.ssh/authorized_keys` file. + +3. **Boot and Verify:** Boot the VM with this `user-data`. You should be able to SSH as `sysadmin` and run `sudo` commands. + +**Example 2: Modifying the Default User** + +A more common task is to simply secure the default user provided with the cloud image (`rocky`). Here, we will modify this user to add our SSH key. + +1. **Create `user-data.yml`:** + ```bash + cat < user-data.yml + #cloud-config + users: + - default + - name: rocky + ssh_authorized_keys: + - + EOF + ``` + +2. **Key Directives Explained:** + * `default`: This special entry tells `cloud-init` to perform its default user setup first. + * `name: rocky`: By specifying the name of an existing user, the module will modify that user instead of creating a new one. Here, it merges the provided SSH key into the `rocky` user's account. + +3. **Boot and Verify:** Boot the VM. You can now SSH as the `rocky` user without a password. + +### **Module Deep Dive: `packages`** + +The `packages` module provides a declarative way to manage the software on your instance, ensuring that specific applications are installed at boot time. + +In this example, we will ensure two useful tools, `nginx` (a high-performance web server) and `htop` (an interactive process viewer), are installed. We will also instruct `cloud-init` to update the package repository metadata first to ensure it can find the latest versions. + +1. **Create `user-data.yml`:** + ```bash + cat < user-data.yml + #cloud-config + package_update: true + packages: + - nginx + - htop + EOF + ``` + +2. **Key Directives Explained:** + * `package_update: true`: Instructs the package manager to refresh its local metadata. On Rocky Linux, this is equivalent to running `dnf check-update`. + * `packages`: A list of package names to be installed. + +3. **Boot and Verify:** After booting, SSH in and check that `nginx` is installed with `rpm -q nginx`. + +!!! note "Idempotency in Action" + If you were to reboot this VM with the same `user-data`, the `packages` module would see that `nginx` and `htop` are already installed and do nothing further. It ensures the desired state (packages are present) without taking unnecessary action. That is idempotency. + +### **Module Deep Dive: `write_files`** + +This module is incredibly versatile, allowing you to write any text content to any file on the system. It is the perfect tool for deploying application configuration files, populating web content, or creating helper scripts. + +To demonstrate its power, we will use `write_files` to create a custom homepage for the `nginx` web server that we are also installing in the same run. + +1. **Create `user-data.yml`:** + ```bash + cat < user-data.yml + #cloud-config + packages: [nginx] + write_files: + - path: /usr/share/nginx/html/index.html + content: '

Hello from cloud-init!

' + owner: nginx:nginx + permissions: '0644' + runcmd: + - [ systemctl, enable, --now, nginx ] + EOF + ``` + +2. **Key Directives Explained:** + * `path`: The absolute path on the filesystem where the file will be written. + * `content`: The text content to be written to the file. + * `owner`: Specifies the user and group that should own the file (e.g., `nginx:nginx`). + * `permissions`: The file permissions in octal format (e.g., `0644`). + +3. **Boot and Verify:** After booting, SSH in and use `curl localhost` to see the new homepage. + +!!! tip "Writing Binary Files" + The `write_files` module is not limited to text. By specifying an `encoding`, you can deploy binary files. For example, you can use `encoding: b64` to write base64-encoded data. For advanced use cases, refer to the [official `write_files` documentation](https://cloudinit.readthedocs.io/en/latest/topics/modules.html#write-files). + +## **What's Next?** + +You have now mastered the three most fundamental `cloud-init` modules. By combining them, you can perform a significant amount of automated server configuration. In the next chapter, we will tackle more advanced scenarios, including network configuration and combining different `user-data` formats in a single run. diff --git a/docs/guides/virtualization/cloud-init/04_advanced_provisioning.md b/docs/guides/virtualization/cloud-init/04_advanced_provisioning.md new file mode 100644 index 0000000000..6ea2672ec1 --- /dev/null +++ b/docs/guides/virtualization/cloud-init/04_advanced_provisioning.md @@ -0,0 +1,227 @@ +--- +title: IV. Advanced Provisioning - Networking and Multi-Part Payloads +author: Wale Soyinka +contributors: +tags: + - cloud-init + - rocky linux + - cloud + - automation + - networking +--- + +# **IV. Advanced Provisioning: Networking and Multi-Part Payloads** + +In the previous chapter, you mastered the core `cloud-init` modules for managing users, packages, and files. You can now build a well-configured server declaratively. Now, it's time to explore more advanced techniques that give you even greater control over your instance's configuration. + +This chapter covers two powerful, advanced topics: + +1. **Declarative Network Configuration:** How to move beyond DHCP and define static network configurations for your instances. +2. **Multi-Part MIME Payloads:** How to combine different types of user-data, like shell scripts and `#cloud-config` files, into a single, powerful payload. + +## **1. Declarative Network Configuration** + +By default, most cloud images are configured to acquire an IP address via DHCP. While convenient, many production environments require servers to have predictable, static IP addresses. The `cloud-init` network configuration system provides a platform-agnostic, declarative way to manage this. + +Network configurations are specified in a separate YAML document from your main `#cloud-config`. `cloud-init` processes both from the same file, using the standard YAML document separator (`---`) to distinguish between them. + +!!! note "How `cloud-init` Applies Network State" + On Rocky Linux, `cloud-init` does not directly configure the network interfaces. Instead, it acts as a translator, converting its network configuration into files that **NetworkManager** (the default network service) can understand. It then hands off control to NetworkManager to apply the configuration. You can inspect the resulting connection profiles in `/etc/NetworkManager/system-connections/`. + +### **Example 1: Configuring a Single Static IP** + +In this exercise, we will configure our virtual machine with a static IP address, a default gateway, and custom DNS servers. + +1. **Create `user-data.yml`:** + + This file contains two distinct YAML documents, separated by `---`. The first is our standard `#cloud-config`. The second defines the network state. + + ```bash + cat < user-data.yml + #cloud-config + # We can still include standard modules. + # Let's install a network troubleshooting tool. + packages: + - traceroute + + --- + + # This second document defines the network configuration. + network: + version: 2 + ethernets: + eth0: + dhcp4: no + addresses: + - 192.168.122.100/24 + gateway4: 192.168.122.1 + nameservers: + addresses: [8.8.8.8, 8.8.4.4] + EOF + ``` + +2. **Key Directives Explained:** + * `network:`: The top-level key for network configuration. + * `version: 2`: Specifies that we are using the modern, Netplan-like syntax. + * `ethernets:`: A dictionary of physical network interfaces to configure, keyed by the interface name (e.g., `eth0`). + * `dhcp4: no`: Disables DHCP for IPv4 on this interface. + * `addresses`: A list of static IP addresses to assign, specified in CIDR notation. + * `gateway4`: The default gateway for IPv4 traffic. + * `nameservers`: A dictionary containing a list of IP addresses for DNS resolution. + +3. **Boot and Verify:** + + Verification is different this time, as the VM will not get a dynamic IP address. You must connect to the VM's console directly. + + ```bash + # Use a new disk image for this exercise + qemu-img create -f qcow2 -F qcow2 -b Rocky-10-GenericCloud.qcow2 static-ip-vm.qcow2 + + virt-install --name rocky10-static-ip \ + --memory 2048 --vcpus 2 \ + --disk path=static-ip-vm.qcow2,format=qcow2 \ + --cloud-init user-data=user-data.yml,hostname=network-server \ + --os-variant rockylinux10 \ + --import --noautoconsole + + # Connect to the virtual console + virsh console rocky10-static-ip + + # Once logged in, check the IP address + [rocky@network-server ~]$ ip a show eth0 + ``` + The output should show that `eth0` has the static IP address `192.168.122.100/24`. + +### **Example 2: Multi-Interface Configuration** + +A common real-world scenario is a server with multiple network interfaces. Here, we'll create a VM with two interfaces: `eth0` will use DHCP, and `eth1` will have a static IP. + +1. **Create `user-data.yml` for two interfaces:** + ```bash + cat < user-data.yml + #cloud-config + packages: [iperf3] + + --- + + network: + version: 2 + ethernets: + eth0: + dhcp4: yes + eth1: + dhcp4: no + addresses: [192.168.200.10/24] + EOF + ``` + +2. **Boot a VM with two NICs:** We add a second `--network` flag to the `virt-install` command. + ```bash + virt-install --name rocky10-multi-nic \ + --memory 2048 --vcpus 2 \ + --disk path=... \ + --network network=default,model=virtio \ + --network network=default,model=virtio \ + --cloud-init user-data=user-data.yml,hostname=multi-nic-server \ + --os-variant rockylinux10 --import --noautoconsole + ``` + +3. **Verify:** SSH to the DHCP-assigned address on `eth0` and then check the static IP on `eth1` with `ip a show eth1`. + +## **2. Unifying Payloads with Multi-Part MIME** + +Sometimes, you need to run a setup script *before* the main `#cloud-config` modules execute. MIME multi-part files are the solution, allowing you to bundle different content types into one ordered payload. + +The structure of a MIME file can be visualized as follows: + +``` ++-----------------------------------------+ +| Main Header (multipart/mixed; boundary) | ++-----------------------------------------+ +| +| --boundary | +| +-------------------------------------+ +| | Part 1 Header (e.g., text/x-shellscript) | +| +-------------------------------------+ +| | Part 1 Content (#/bin/sh...) | +| +-------------------------------------+ +| +| --boundary | +| +-------------------------------------+ +| | Part 2 Header (e.g., text/cloud-config) | +| +-------------------------------------+ +| | Part 2 Content (#cloud-config...) | +| +-------------------------------------+ +| +| --boundary-- (closing) | ++-----------------------------------------+ +``` + +### **Hands-On: A Pre-flight Check Script** + +We will create a multi-part file that first runs a shell script and then proceeds to the main `#cloud-config`. + +1. **Create the Multi-Part `user-data.mime` file:** + + This is a specially formatted text file that uses a "boundary" string to separate the parts. + + ```bash + cat < user-data.mime + Content-Type: multipart/mixed; boundary="//" +MIME-Version: 1.0 + +--// +Content-Type: text/x-shellscript; charset="us-ascii" + +#!/bin/sh +echo "Running pre-flight checks..." +# In a real script, you might check disk space or memory. +# If checks failed, you could 'exit 1' to halt cloud-init. +echo "Pre-flight checks passed." > /tmp/pre-flight-status.txt + +--// +Content-Type: text/cloud-config; charset="us-ascii" + +#cloud-config +packages: + - htop +runcmd: + - [ sh, -c, "echo 'Main cloud-config ran successfully' > /tmp/main-config-status.txt" ] + +--//-- + EOF + ``` + !!! note "About the MIME Boundary" + The boundary string (`//` in this case) is an arbitrary string that must not appear in the content of any part. It is used to separate the different sections of the file. + +2. **Boot and Verify:** + + You pass this file to `virt-install` in the same way as a standard `user-data.yml` file. + + ```bash + # Use a new disk image + qemu-img create -f qcow2 -F qcow2 -b Rocky-10-GenericCloud.qcow2 mime-vm.qcow2 + + virt-install --name rocky10-mime-test \ + --memory 2048 --vcpus 2 \ + --disk path=mime-vm.qcow2,format=qcow2 \ + --cloud-init user-data=user-data.mime,hostname=mime-server \ + --os-variant rockylinux10 \ + --import --noautoconsole + ``` + + After booting, SSH into the VM and check that both parts ran by looking for the files they created: + + ```bash + cat /tmp/pre-flight-status.txt + cat /tmp/main-config-status.txt + ``` + +!!! tip "Other Multi-Part Content Types" + `cloud-init` supports other content types for advanced use cases, such as `text/cloud-boothook` for very early boot scripts or `text/part-handler` for running custom Python code. Refer to the official documentation for more details. + +## **What's Next?** + +You have now learned two powerful, advanced `cloud-init` techniques. You can now define static networks and orchestrate complex provisioning workflows with multi-part user-data. + +In the next chapter, we will shift our perspective from *consuming* `cloud-init` on a per-instance basis to *customizing its default behavior* for creating your own pre-configured "golden images". diff --git a/docs/guides/virtualization/cloud-init/05_image_builders_perspective.md b/docs/guides/virtualization/cloud-init/05_image_builders_perspective.md new file mode 100644 index 0000000000..2b7157a437 --- /dev/null +++ b/docs/guides/virtualization/cloud-init/05_image_builders_perspective.md @@ -0,0 +1,130 @@ +--- +title: V. The Image Builder's Perspective +author: Wale Soyinka +contributors: +tags: + - cloud-init + - rocky linux + - cloud + - automation + - image-building +--- + +# **V. The Image Builder's Perspective: Defaults and Generalization** + +So far, our journey has focused on configuring individual instances at boot time using `user-data`. In this chapter, we will shift our perspective to that of an **image builder**—someone who creates and maintains the "golden images" that serve as templates for other virtual machines. + +Our goal is to create a new, custom image with our own baked-in policies and defaults. This involves two key processes: + +1. **Customizing System-Wide Defaults:** Modifying the `cloud-init` configuration *within the image itself*. +2. **Generalizing the Image:** Using tools like `cloud-init clean` and `virt-sysprep` to strip all machine-specific data, preparing the image for cloning. + +## **1. The Customization Lab Setup** + +To begin, we need a running instance of the base cloud image that we can modify. We will boot this VM *without* providing any `user-data` to get a clean system. + +```bash +# Create a disk image for our new template +qemu-img create -f qcow2 -o size=10G golden-image-template.qcow2 + +# Boot the base image using virt-install +virt-install --name golden-image-builder \ +--memory 2048 --vcpus 2 \ +--disk path=golden-image-template.qcow2,format=qcow2 \ +--cloud-init none --os-variant rockylinux10 --import + +# Connect to the console and log in as the default 'rocky' user +virsh console golden-image-builder +``` + +## **2. System-Wide Configuration with `cloud.cfg.d`** + +Inside our running VM, we can now customize the system-wide `cloud-init` configuration. The master file, `/etc/cloud/cloud.cfg`, should never be edited directly. The correct, upgrade-safe location for customizations is the `/etc/cloud/cloud.cfg.d/` directory. `cloud-init` reads all `.cfg` files here in alphabetical order after the main `cloud.cfg`, allowing you to override defaults. + +### **Hands-On: Setting Golden Image Defaults** + +Let's enforce a policy on our golden image: we will disable password authentication, set a new default user, and ensure a baseline set of packages is always installed. + +1. **Create a custom configuration file:** From inside the VM, create `/etc/cloud/cloud.cfg.d/99-custom-defaults.cfg`. The `99-` prefix ensures it is read last. + + ```bash + sudo cat < /etc/cloud/cloud.cfg.d/99-custom-defaults.cfg + # Golden Image Customizations + + # Define a new default user named 'admin' + system_info: + default_user: + name: admin + sudo: ["ALL=(ALL) NOPASSWD:ALL"] + shell: /bin/bash + + # Enforce key-based SSH authentication + ssh_pwauth: false + + # Ensure a baseline of packages is always installed + packages: + - htop + - vim-enhanced + EOF + ``` + +!!! tip "Disabling Specific Modules" +A powerful security technique is to completely disable certain `cloud-init` modules. For example, to prevent any user from ever using `runcmd`, you can add the following to your custom `.cfg` file. This tells `cloud-init` to run an empty list of modules during the final stage. + ```yaml + cloud_final_modules: [] + ``` + +## **3. Generalizing the Image** + +Our VM now contains our custom configuration, but it also holds unique machine identifiers (like `/etc/machine-id`) and SSH host keys. Before we can clone it, we **must** remove this data in a process called **generalization**. + +### **Method 1: `cloud-init clean` (Inside the VM)** + +`cloud-init` provides a built-in command for this purpose. + +1. **Run `cloud-init clean`:** From inside the VM, run the following to strip instance-specific data. + ```bash + sudo cloud-init clean --logs --seed + ``` + !!! note "On `cloud-init clean --seed`" + This command removes the unique seed `cloud-init` uses to identify the instance, forcing it to run from scratch on the next boot. It does **not** remove your custom configurations in `/etc/cloud/cloud.cfg.d/`. This step is essential for creating a truly generic template. + +2. **Immediately Shut Down:** After cleaning, power off the VM immediately. + ```bash + sudo poweroff + ``` + +### **Method 2: `virt-sysprep` (From the Host)** + +An even more thorough, industry-standard tool is `virt-sysprep`. It can be run from your host machine on the shutdown VM disk. It performs all the actions of `cloud-init clean` and much more, such as clearing command history, removing temporary files, and resetting log files. + +1. **Ensure the VM is shut down.** +2. **Run `virt-sysprep` from your host:** + ```bash + sudo virt-sysprep -a golden-image-template.qcow2 + ``` + +Once the generalization process is complete, the disk file (`golden-image-template.qcow2`) is your new golden image. + +!!! note "Golden Image Naming Conventions" + It is a good practice to give your golden images descriptive names that include the OS and a version number, such as `rocky10-base-v1.0.qcow2`. This helps with version control and infrastructure management. + +## **4. Verifying the Golden Image** + +Let's test our new image by booting a new instance *from* it without any `user-data`. + +1. **Create a new VM disk from our golden image:** + ```bash + qemu-img create -f qcow2 -F qcow2 -b golden-image-template.qcow2 test-instance.qcow2 + ``` + +2. **Boot the test instance:** + ```bash + virt-install --name golden-image-test --cloud-init none ... + ``` + +3. **Verify:** Connect to the console (`virsh console golden-image-test`). The login prompt should be for the user `admin`, not `rocky`. Once logged in, you can also verify that `htop` is installed (`rpm -q htop`). This confirms your baked-in defaults are working. + +## **What's Next?** + +You have now learned how to create standardized templates by baking in defaults with `cloud-init`'s system-wide configuration and properly generalizing them for cloning. In the next chapter, we will cover the essential skill of troubleshooting when `cloud-init` doesn't behave as expected. \ No newline at end of file diff --git a/docs/guides/virtualization/cloud-init/06_troubleshooting.md b/docs/guides/virtualization/cloud-init/06_troubleshooting.md new file mode 100644 index 0000000000..5297aefdb1 --- /dev/null +++ b/docs/guides/virtualization/cloud-init/06_troubleshooting.md @@ -0,0 +1,105 @@ +--- +title: VI. Troubleshooting cloud-init +author: Wale Soyinka +contributors: +tags: + - cloud-init + - rocky linux + - cloud + - automation + - troubleshooting +--- + +# **VI. Troubleshooting cloud-init** + +In any complex, automated system, things will eventually go wrong. When a `cloud-init` configuration fails, knowing how to systematically diagnose the problem is an essential skill. This chapter is your guide to `cloud-init` forensics, covering both in-guest and on-host troubleshooting techniques. + +## **1. In-Guest Troubleshooting Toolkit** + +When you can access a running instance, `cloud-init` provides several commands and logs to show you what happened. + +### **Pillar 1: The Status Command (`cloud-init status`)** + +This is your first port of call. It provides a high-level summary of `cloud-init`'s state. + +* **Check if `cloud-init` is done:** `cloud-init status` + (A successful run will show `status: done`) +* **Wait for `cloud-init` to finish:** `cloud-init status --wait` + (This is useful in scripts to pause execution until `cloud-init` completes) + +### **Pillar 2: The Main Log (`/var/log/cloud-init.log`)** + +This file is the golden source of truth: a detailed, chronological record of every stage and module. When you need to know *exactly* what happened, look here. Searching this file for `ERROR` or `WARNING` will often lead you directly to the problem. + +### **Pillar 3: The Output Log (`/var/log/cloud-init-output.log`)** + +This log captures the full `stdout` and `stderr` of all scripts executed by `cloud-init` (e.g., from `runcmd`). If a module ran but your script within it failed, the error message will be in this file. + +**Hands-On: Debugging a Failing `runcmd`** + +1. Create a `user-data.yml` with a `runcmd` that has a subtle error: + ```bash + cat < user-data.yml + #cloud-config + runcmd: + - [ ls, /non-existent-dir ] + EOF + ``` +2. Boot a VM with this data. `cloud-init status` will report `status: done` because the `runcmd` module itself executed successfully. +3. However, `/var/log/cloud-init-output.log` will contain the actual error from the `ls` command, showing you what failed: + ``` + ls: cannot access '/non-existent-dir': No such file or directory + ``` + +## **2. Host-Side Troubleshooting with `libguestfs-tools`** + +Sometimes, a VM will fail to boot entirely, making in-guest tools useless. In these cases, you can diagnose problems by inspecting the VM's disk image directly from the host using the powerful `libguestfs-tools` suite (install with `sudo dnf install libguestfs-tools`). + +### **`virt-cat`: Reading Files from a Guest Disk** + +`virt-cat` lets you read files from inside a VM's disk image without mounting it. This is perfect for grabbing log files from a non-booting instance. + +```bash +# From the host, read the cloud-init.log from the VM's disk +sudo virt-cat -a /path/to/your-vm-disk.qcow2 /var/log/cloud-init.log +``` + +### **`virt-inspector`: Deep System Inspection** + +`virt-inspector` generates a detailed XML report of a VM's OS, applications, and configuration. This is incredibly powerful for automated analysis. + +* **Get a full report:** + ```bash + sudo virt-inspector -a your-vm-disk.qcow2 > report.xml + ``` +* **Perform a targeted query:** You can pipe the XML to `xmllint` to extract specific information. This example checks the installed version of `cloud-init` inside the image: + ```bash + sudo virt-inspector -a your-vm-disk.qcow2 | xmllint --xpath "//application[name='cloud-init']/version/text()" - + ``` + +## **3. Common Pitfalls and How to Avoid Them** + +### **Pitfall 1: YAML and Schema Errors** + +Invalid YAML is the most common source of failures. A more advanced problem is a syntactically valid YAML file that violates `cloud-init`'s expected structure (e.g., a typo in a module name). + +* **Solution:** Use the `cloud-init schema` command to validate your configuration *before* you boot. It will catch both YAML errors and structural errors. + ```bash + # Validate your user-data file against the official schema + cloud-init schema --config-file user-data.yml + ``` + If the file is valid, it will print `Valid cloud-config: user-data.yml`. If not, it will provide detailed errors. + +### **Pitfall 2: Network-Dependent Modules Failing** + +If networking fails to come up, modules like `packages` will fail. Check your network configuration and the `Network` stage in `/var/log/cloud-init.log`. + +## **4. Controlling `cloud-init`'s Execution** + +* **Forcing a Re-run:** To test changes on a running VM, run `sudo cloud-init clean --logs` followed by `sudo reboot`. +* **Disabling `cloud-init`:** To prevent `cloud-init` from running on subsequent boots, create a sentinel file: `sudo touch /etc/cloud/cloud-init.disabled`. +* **Running on Every Boot (`bootcmd`):** Use the `bootcmd` module for scripts that must run on every single boot. This is rare but useful for certain diagnostics. + +## **What's Next?** + +You are now equipped with a powerful set of tools for both in-guest and on-host troubleshooting. In the final chapter, we will look at the `cloud-init` project itself, preparing you to explore its source code and contribute back to the community. \ No newline at end of file diff --git a/docs/guides/virtualization/cloud-init/07_contributing.md b/docs/guides/virtualization/cloud-init/07_contributing.md new file mode 100644 index 0000000000..41b9b5e8fb --- /dev/null +++ b/docs/guides/virtualization/cloud-init/07_contributing.md @@ -0,0 +1,132 @@ +--- +title: VII. Contributing to cloud-init +author: Wale Soyinka +contributors: +tags: + - cloud-init + - open source + - development + - python +--- + +# **VII. Beyond Consumption: Contributing to cloud-init** + +Congratulations! You have journeyed from the fundamental concepts of `cloud-init` to advanced provisioning and troubleshooting techniques. You are now a `cloud-init` power user. This final chapter opens the door to the next step in your journey: moving from a consumer of `cloud-init` to a potential contributor. + +`cloud-init` is a critical open-source project that thrives on community contributions. Whether it's fixing a typo in the documentation, reporting a bug, or writing a brand-new module, every contribution helps. This chapter provides a high-level map for understanding the source code, building a custom module, and engaging with the upstream community. It is not an exhaustive developer guide, but rather a friendly introduction to getting involved. + +## **1. The `cloud-init` Source Code Landscape** + +Before you can contribute, you need to know your way around the project. Let's explore the source code and set up a basic development environment. + +### **The Language and Repository** + +`cloud-init` is written almost entirely in **Python**. Its canonical source code repository is hosted on **Launchpad**, but for easier collaboration and a more familiar interface, most contributors interact with its official mirror on **GitHub**. + +* **Canonical Repository (Launchpad):** [https://git.launchpad.net/cloud-init](https://git.launchpad.net/cloud-init) +* **GitHub Mirror:** [https://github.com/canonical/cloud-init](https://github.com/canonical/cloud-init) + +To get the source code, you can clone the GitHub repository: + +```bash +# Clone the source code to your local machine +git clone https://github.com/canonical/cloud-init.git +cd cloud-init +``` + +### **Setting up a Development Environment** + +To work on the code without affecting your system's Python packages, you should always use a virtual environment. + +```bash +# Create a Python virtual environment +python3 -m venv .venv + +# Activate the virtual environment +source .venv/bin/activate + +# Install the required development dependencies +pip install -r requirements-dev.txt +``` + +### **A High-Level Tour of the Source Code** + +Navigating a new codebase can be daunting. Here are the most important directories: + +* `cloudinit/`: This is the main Python source directory. +* `cloudinit/sources/`: This directory contains the code for **Datasources** (e.g., `DataSourceNoCloud.py`). This is how `cloud-init` detects and reads configuration from different cloud platforms. +* `cloudinit/config/`: This is where the **Modules** live (e.g., `cc_packages.py`, `cc_users_groups.py`). The `cc_` prefix is a convention for modules that are enabled by `#cloud-config`. This is the most common place for new feature contributions. +* `doc/`: The project's official documentation. Documentation improvements are one of the best ways to make your first contribution. +* `tests/`: The comprehensive test suite for the project. + +## **2. Writing a Basic Custom Module** + +While `runcmd` is useful, writing a proper module is the best way to create reusable, portable, and idempotent configurations. + +Let's create the simplest possible module: one that reads a configuration key from `user-data` and writes a message to the `cloud-init` log. + +1. **Create the Module File:** Create a new file named `cloudinit/config/cc_hello_world.py`. + + ```python + # Filename: cloudinit/config/cc_hello_world.py + + # A list of frequency and stage for this module to run + frequency = "once-per-instance" + distros = ["all"] + + def handle(name, cfg, cloud, log, args): + # Get a 'message' key from the user-data config. + # If it doesn't exist, use a default value. + message = cfg.get("message", "Hello from a custom module!") + + # Write the message to the main cloud-init log. + log.info(f"Hello World Module says: {message}") + ``` + +2. **Enable the Module:** Creating the file isn't enough. You must tell `cloud-init` to run it. Create a file at `/etc/cloud/cloud.cfg.d/99-my-modules.cfg` and add your module to one of the module lists: + + ```yaml + # Add our custom module to the list of modules that run during the config stage + cloud_config_modules: + - hello_world + ``` + +3. **Use the Module:** Now, you can use the module in your `user-data`. The top-level key (`hello_world`) should match the module name without the `cc_` prefix. + + ```yaml + #cloud-config + hello_world: + message: "My first custom module is working!" + ``` + +After booting a VM with this configuration, you can check `/var/log/cloud-init.log` and you will find your custom message, proving your module worked. + +## **3. The Contribution Workflow** + +Contributing to an open-source project follows a standard workflow. Here is a simplified overview: + +1. **Find Something to Work On:** The best place to start is the project's issue tracker on Launchpad. Look for bugs or feature requests. Newcomers are encouraged to start with documentation fixes or issues tagged as "low-hanging-fruit" or "good first issue". + +2. **Fork and Branch:** Create your own copy (a "fork") of the `cloud-init` repository on GitHub. Then, create a new branch for your changes. + ```bash + git checkout -b my-documentation-fix + ``` + +3. **Make Your Changes and Commit:** Make your code or documentation changes. When you commit, write a clear message describing what you did. The `-s` flag adds a `Signed-off-by` line, which certifies that you wrote the patch or have the right to contribute it. + ```bash + git commit -s -m "Doc: Fix typo in the users module documentation" + ``` + +4. **Include Tests:** All significant contributions, especially new features, are expected to include tests. Explore the `tests/` directory to see how existing modules are tested. + +5. **Submit a Pull Request (PR):** Push your branch to your fork on GitHub and open a Pull Request to the `main` branch of the `canonical/cloud-init` repository. This is your formal request to have your work included in the project. + +6. **Engage in Code Review:** Project maintainers will review your PR. They may ask questions or request changes. This is a collaborative process. Engaging with feedback is a key part of contributing to open source. + +### **Community Engagement** + +To learn more, ask questions, and interact with the community, you can join the `#cloud-init` channel on the OFTC IRC network or the official mailing list. + +## **A Final Word** + +Congratulations on completing this guide. You have progressed from a novice user to a `cloud-init` power user, and now you have a map to guide you into the world of open-source contribution. The `cloud-init` community is welcoming, and your contributions, no matter how small, are valued. Happy building! diff --git a/docs/guides/virtualization/cloud-init/index.md b/docs/guides/virtualization/cloud-init/index.md new file mode 100644 index 0000000000..09ebada2c0 --- /dev/null +++ b/docs/guides/virtualization/cloud-init/index.md @@ -0,0 +1,34 @@ +--- +title: Guide to cloud-init on Rocky Linux +--- + +# Mastering cloud-init on Rocky Linux + +Welcome to the comprehensive guide to `cloud-init` on Rocky Linux. This series is designed to take you from the fundamental concepts of cloud instance initialization to advanced, real-world provisioning and troubleshooting techniques. Whether you are a new user setting up your first cloud server or an experienced administrator building custom images, this guide has something for you. + +The chapters are designed to be read sequentially, building on the knowledge from the previous sections. + +--- + +## Chapters in This Guide + +**[1. Fundamentals](./01_fundamentals.md)** +> Learn what `cloud-init` is, why it's essential for cloud computing, and the stages of its execution lifecycle. + +**[2. First Contact](./02_first_contact.md)** +> Your first hands-on exercise. Boot a cloud image and perform a simple customization using a basic `user-data` file. + +**[3. The Configuration Engine](./03_configuration_engine.md)** +> Dive deep into the `cloud-init` module system. Learn to use the most important modules for managing users, packages, and files. + +**[4. Advanced Provisioning](./04_advanced_provisioning.md)** +> Tackle complex scenarios, including how to define static network configurations and how to combine scripts and cloud-configs into a single payload. + +**[5. The Image Builder's Perspective](./05_image_builders_perspective.md)** +> Shift your perspective to that of an image builder. Learn how to create "golden images" with baked-in defaults and how to properly generalize them for cloning. + +**[6. Troubleshooting](./06_troubleshooting.md)** +> Learn the essential art of `cloud-init` forensics. Understand the logs, status commands, and common pitfalls to diagnose and solve problems effectively. + +**[7. Contributing to cloud-init](./07_contributing.md)** +> Go beyond being a user. This chapter provides a map for understanding the `cloud-init` source code and making your first contribution to the open-source project. \ No newline at end of file From 9d1fb63708f81817ab2f68ad709642a3323564ae Mon Sep 17 00:00:00 2001 From: Rocky Linux Automation <75949597+rockylinux-auto@users.noreply.github.com> Date: Sat, 4 Oct 2025 17:07:32 -0400 Subject: [PATCH 2/7] New Crowdin updates (#2928) * New translations active_directory_authentication.md (French) * New translations active_directory_authentication.md (German) * New translations rl9_network_manager.md (French) * New translations nmtui.md (French) * New translations podman.md (French) --- docs/gemstones/containers/podman.fr.md | 2 +- .../network/RL9_network_manager.fr.md | 2 +- docs/gemstones/network/nmtui.fr.md | 2 +- .../active_directory_authentication.de.md | 311 ++++++++++++++++++ .../active_directory_authentication.fr.md | 6 +- 5 files changed, 317 insertions(+), 6 deletions(-) create mode 100644 docs/guides/security/authentication/active_directory_authentication.de.md diff --git a/docs/gemstones/containers/podman.fr.md b/docs/gemstones/containers/podman.fr.md index 09dc549f86..9f31a32adb 100644 --- a/docs/gemstones/containers/podman.fr.md +++ b/docs/gemstones/containers/podman.fr.md @@ -99,7 +99,7 @@ Podman fournit également la sous-commande `generate systemd`. Il peut être uti !!! warning "Avertissement" ``` -`generate systemd` est désormais obsolète et ne recevra plus de fonctionnalités supplémentaires. L'utilisation de Quadlet est recommandée. +`generate systemd` est maintenant désuet et ne recevra plus de fonctionnalités. L'utilisation de `Quadlet` est recommandée. ``` Faisons-le désormais avec Nextcloud. Exécuter : diff --git a/docs/gemstones/network/RL9_network_manager.fr.md b/docs/gemstones/network/RL9_network_manager.fr.md index 7f55a6a20c..0c54b8bfed 100644 --- a/docs/gemstones/network/RL9_network_manager.fr.md +++ b/docs/gemstones/network/RL9_network_manager.fr.md @@ -42,7 +42,7 @@ Pour RockyLinux 8.x, nous avons expliqué comment configurer son réseau [ici](. ## Règles de nommage pour udev device manager -Pour RockyLinux 9.x, si vous allez dans le répertoire **/etc/sysconfig/network-scripts/** , il y aura un **readme-ifcfg-rh.txt** texte de description qui vous invite à vous rendre dans le répertoire **/etc/NetworkManager/system-connections/**. +Pour RockyLinux 9.x, si vous allez dans le répertoire **/etc/sysconfig/network-scripts/** , il y aura un texte descriptif **readme-ifcfg-rh.txt** qui vous invite à vous rendre dans le répertoire **/etc/NetworkManager/system-connections/**. ```bash Shell > cd /etc/NetworkManager/system-connections/ && ls diff --git a/docs/gemstones/network/nmtui.fr.md b/docs/gemstones/network/nmtui.fr.md index 2503ebb009..d3c4e5fd6e 100644 --- a/docs/gemstones/network/nmtui.fr.md +++ b/docs/gemstones/network/nmtui.fr.md @@ -50,7 +50,7 @@ Toutes les distributions RHEL 7.x ou !!! warning "Avertissement" - Dans les distributions RHEL 9.x, l'emplacement du répertoire où le fichier de configuration du réseau est stocké a été modifié, c'est-à-dire **/etc/NetworkManager/system-connections/**. Veuillez consulter [ce site](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/configuring_and_managing_networking/index) pour plus d'informations. + Dans les distributions RHEL 9.x, l'emplacement du répertoire où le fichier de configuration de la carte réseau est stocké a été modifié, soit **/etc/NetworkManager/system-connections/**. Veuillez consulter [ce site](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/configuring_and_managing_networking/index) pour plus d'informations. ```bash shell > ls /etc/sysconfig/network-scripts/ diff --git a/docs/guides/security/authentication/active_directory_authentication.de.md b/docs/guides/security/authentication/active_directory_authentication.de.md new file mode 100644 index 0000000000..24a4c6e5db --- /dev/null +++ b/docs/guides/security/authentication/active_directory_authentication.de.md @@ -0,0 +1,311 @@ +--- +title: Active Directory-Authentifizierung +author: Hayden Young +contributors: Steven Spencer, Sambhav Saggi, Antoine Le Morvan, Krista Burdine, Ganna Zhyrnova, Neel Chauhan +tested_with: 9.4 +--- + +## Voraussetzungen + +- Grundverständnis von Active Directory +- Grundverständnis von LDAP + +## Einleitung + +Microsofts Active Directory (AD) ist in den meisten Unternehmen das de facto Authentifizierungssystem für Windows-Systeme und für externe LDAP-angeschlossene Dienste. Es erlaubt Ihnen, Benutzer und Gruppen zu konfigurieren, sowie Zugriffskontrolle, Berechtigungen, Auto-Mount und mehr. + +Während Linux mit einem AD-Cluster verbunden wird, können _nicht alle_ der genannten Funktionen unterstützt werden, es kann jedoch Benutzer, Gruppen und Zugriffskontrolle verwalten. Es ist sogar möglich SSH-Schlüssel unter Verwendung von AD zu verteilen (durch einige Konfigurationseinstellungen auf der Linux-Seite und durch einige fortgeschrittene Optionen auf der AD-Seite). + +Diese Anleitung deckt jedoch nur die Konfiguration der Authentifizierung gegen Active Directory ab und enthält keine zusätzliche Konfiguration auf der Windowsseite. + +## AD mit Hilfe von SSSD finden und verbinden + +!!! note "Hinweis" + + In dieser Anleitung wird der Domainname `ad.company.local` verwendet, um + die Active Directory Domain zu simulieren. Um dieser Anleitung zu folgen, ersetzen Sie sie durch den aktuellen Domain-Namen, den Ihre AD-Domain verwendet. + +Der erste Schritt auf dem Weg zu einem Linux-System in AD ist es, den AD-Cluster zu finden, um sicherzustellen, dass die Netzwerkkonfiguration auf beiden Seiten korrekt ist. + +### Zubereitung + +- Stellen Sie sicher, dass die folgenden Ports für Ihren Linux-Host auf Ihrem Domain Controller offen sind: + + | Dienst | Port(s) | Beschreibung | + | -------- | ----------------- | ------------------------------------------------------------------------------- | + | DNS | 53 (TCP+UDP) | | + | Kerberos | 88, 464 (TCP+UDP) | Verwendet von `kadmin` für die Einstellung & die Aktualisierung von Passwörtern | + | LDAP | 389 (TCP+UDP) | | + | LDAP-GC | 3268 (TCP) | LDAP Global Catalog - ermöglicht die Quell-Benutzer-IDs von AD zu übernehmen | + +- Stellen Sie sicher, dass Sie Ihren AD Domänencontroller als DNS-Server auf Ihrem Rocky Linux Host konfiguriert haben: + + **Mit dem NetworkManager:** + + ```sh + # where your primary NetworkManager connection is 'System eth0' and your AD + # server is accessible on the IP address 10.0.0.2. + [root@host ~]$ nmcli con mod 'System eth0' ipv4.dns 10.0.0.2 + ``` + +- Stellen Sie sicher, dass die Zeit auf beiden Seiten (AD Host und Linux System) synchronisiert ist (siehe chronyd) + + **Um die Zeit auf Rocky Linux zu überprüfen:** + + ```sh + [user@host ~]$ date + Wed 22 Sep 17:11:35 BST 2021 + ``` + +- Installieren bitte Sie die benötigten Pakete für die AD-Verbindung auf der Linux-Seite: + + ```sh + [user@host ~]$ sudo dnf install realmd oddjob oddjob-mkhomedir sssd adcli krb5-workstation + ``` + + +### Discovery + +Jetzt sollten Sie in der Lage sein, Ihre AD-Server erfolgreich von Ihrem (Rocky) Linux-Host zu finden. + +```sh +[user@host ~]$ realm discover ad.company.local +ad.company.local + type: kerberos + realm-name: AD.COMPANY.LOCAL + domain-name: ad.company.local + configured: no + server-software: active-directory + client-software: sssd + required-package: oddjob + required-package: oddjob-mkhomedir + required-package: sssd + required-package: adcli + required-package: samba-common +``` + +Die relevanten SRV-Einträge, die in Ihrem Active Directory-DNS-Dienst gespeichert sind, ermöglichen die Erkennung. + +### Verbindung + +Sobald Sie Ihre Active Directory Installation vom Linux-Host gefunden haben, sollten Sie in der Lage sein mit `realmd` der Domain beizutreten, welche die Konfiguration von `sssd` unter Verwendung von `adcli` und anderen solchen Tools orchestriert. + +```sh +[user@host ~]$ sudo realm join ad.company.local +``` + +Wenn sich dieser Prozess über die Verschlüsselung mit folgender Meldung beschwert `KDC has no support for this encrption type`, versuchen Sie, die globalen Verschlüsselungsrichtlinien zu aktualisieren, um ältere Verschlüsselungsalgorithmen zu zulassen: + +```sh +[user@host ~]$ sudo update-crypto-policies --set DEFAULT:AD-SUPPORT +``` + +Wenn dieser Prozess erfolgreich ist, sollten Sie jetzt in der Lage sein, `passwd` Informationen für einen Active Directory Benutzer zu bekommen. + +```sh +[user@host ~]$ sudo getent passwd administrator@ad.company.local +administrator@ad.company.local:*:1450400500:1450400513:Administrator:/home/administrator@ad.company.local:/bin/bash +``` + +!!! note "Hinweis" + + `getent` liest Einträge von Name Service Switch Bibliotheken (NSS). Es bedeutet, dass es im Gegensatz zu `passwd` oder `dig` zum Beispiel verschiedene Datenbanken abgefragen werden inklusive `/etc/hosts` für `getent hosts` oder von `sssd` im `getent passwd` Fall. + +`realm` bietet einige interessante Optionen, die Sie verwenden können: + +| Option | Beschreibung | +| ---------------------------------------------------------- | --------------------------------------------------- | +| --computer-ou='OU=LINUX,OU=SERVERS,dc=ad,dc=company.local' | Das OU, wo das Server-Konto gespeichert werden soll | +| --os-name='rocky' | Gibt den OS-Namen an, der im AD gespeichert ist | +| --os-version='8' | Gibt die OS-Version an, die im AD gespeichert ist | +| -U admin_username | Admin-Konto | + +### Authentifizierungs-Versuch + +Jetzt sollten Ihre Benutzer in der Lage sein, sich bei Ihrem Linux-Host gegen Active Directory zu authentifizieren. + +**Unter Windows 10** (welches eine eigene Kopie von OpenSSH bereitstellen sollte): + +```dos +C:\Users\John.Doe> ssh -l john.doe@ad.company.local linux.host +Password for john.doe@ad.company.local: + +Activate the web console with: systemctl enable --now cockpit.socket + +Last login: Wed Sep 15 17:37:03 2021 from 10.0.10.241 +[john.doe@ad.company.local@host ~]$ +``` + +Wenn dies gelingt, haben Sie Linux erfolgreich für die Verwendung von Active Directory als Authentifizierungsquelle konfiguriert. + +### Einstellung der Standard-Domain + +Bei einer vollständig standardmäßigen Einrichtung müssen Sie sich mit Ihrem AD-Konto anmelden, indem Sie die Domäne in Ihrem Benutzernamen angeben (z. B. `john.doe@ad.company.local`). Wenn dies nicht das gewünschte Verhalten ist und Sie stattdessen den Domänennamen bei der Authentifizierung weglassen möchten, können Sie SSSD so konfigurieren, dass standardmäßig eine bestimmte Domäne verwendet wird. + +Dies ist ein relativ unkomplizierter Vorgang, der eine Konfigurationsoptimierung in Ihrer SSSD-Konfigurationsdatei erfordert. + +```sh +[user@host ~]$ sudo vi /etc/sssd/sssd.conf +[sssd] +... +default_domain_suffix = ad.company.local +``` + +Durch Hinzufügen des `default_domain_suffix` weisen Sie SSSD an, (wenn keine andere Domäne angegeben ist) daraus zu folgern, dass der Benutzer versucht, sich als Benutzer aus der Domäne `ad.company.local` zu authentifizieren. Dadurch können Sie sich beispielsweise als `john.doe` statt als `john.doe@ad.company.local` authentifizieren. + +Damit diese Konfigurationsänderung wirksam wird, müssen Sie die Einheit `sssd.service` mit `systemctl` neu starten. + +```sh +[user@host ~]$ sudo systemctl restart sssd +``` + +Wenn Sie nicht möchten, dass Ihre Home-Verzeichnisse mit dem Domänennamen als Suffix versehen werden, können Sie diese Optionen auf die gleiche Weise in Ihre Konfigurationsdatei `/etc/sssd/sssd.conf` einfügen: + +``` +[domain/ad.company.local] +use_fully_qualified_names = False +override_homedir = /home/%u +``` + +Vergessen Sie nicht, den Dienst `sssd` neu zu starten. + +### Auf bestimmte Benutzer beschränken + +Es gibt verschiedene Methoden, den Zugriff auf den Server auf eine begrenzte Anzahl von Benutzern zu beschränken, aber diese ist, wie der Name schon sagt, sicherlich die einfachste: + +Fügen Sie diese Optionen in Ihre Konfigurationsdatei `/etc/sssd/sssd.conf` ein und starten Sie den Dienst neu: + +``` +access_provider = simple +simple_allow_groups = group1, group2 +simple_allow_users = user1, user2 +``` + +Jetzt können nur Benutzer aus `group1` und `group2` oder `user1` und `user2` über sssd eine Verbindung zum Server herstellen! + +## Interagieren Sie mit dem AD über `adcli` + +`adcli` ist eine CLI zum Ausführen von Aktionen in einer Active Directory-Domäne. + +- Falls noch nicht geschehen, installieren Sie das erforderliche Paket: + +```sh +[user@host ~]$ sudo dnf install adcli +``` + +- Testen Sie, ob Sie bereits einer Active Directory-Domäne beigetreten sind: + +```sh +[user@host ~]$ sudo adcli testjoin +Successfully validated join to domain ad.company.local +``` + +- Erhalten Sie weitere Informationen zur Domäne: + +```sh +[user@host ~]$ adcli info ad.company.local +[domain] +domain-name = ad.company.local +domain-short = AD +domain-forest = ad.company.local +domain-controller = dc1.ad.company.local +domain-controller-site = site1 +domain-controller-flags = gc ldap ds kdc timeserv closest writable full-secret ads-web +domain-controller-usable = yes +domain-controllers = dc1.ad.company.local dc2.ad.company.local +[computer] +computer-site = site1 +``` + +- `adcli` ist mehr als nur ein Anzeige-Tool. Sie können damit mit Ihrer Domäne interagieren: Benutzer oder Gruppen verwalten, Passwörter ändern usw. + +Beispiel: Verwenden Sie `adcli`, um Informationen über einen Computer abzurufen: + +!!! note "Hinweis" + + Dieses Mal geben Sie dank der Option `-U` einen Administrator-Benutzernamen an + +```sh +[user@host ~]$ adcli show-computer pctest -U admin_username +Password for admin_username@AD: +sAMAccountName: + pctest$ +userPrincipalName: + - not set - +msDS-KeyVersionNumber: + 9 +msDS-supportedEncryptionTypes: + 24 +dNSHostName: + pctest.ad.company.local +servicePrincipalName: + RestrictedKrbHost/pctest.ad.company.local + RestrictedKrbHost/pctest + host/pctest.ad.company.local + host/pctest +operatingSystem: + Rocky +operatingSystemVersion: + 8 +operatingSystemServicePack: + - not set - +pwdLastSet: + 133189248188488832 +userAccountControl: + 69632 +description: + - not set - +``` + +Beispiel: Verwenden Sie `adcli`, um das Passwort des Benutzers zu ändern: + +```sh +[user@host ~]$ adcli passwd-user user_test -U admin_username +Password for admin_username@AD: +Password for user_test: +[user@host ~]$ +``` + +## Problembehandlung + +Manchmal wird der Netzwerkdienst nach SSSD gestartet, was zu Problemen bei der Authentifizierung führt. + +Bis Sie den Dienst neu starten, können AD-Benutzer keine Verbindung herstellen. + +In diesem Fall müssen Sie die Servicedatei von systemd überschreiben, um das Problem zu beheben. + +Kopieren Sie diesen Inhalt in `/etc/systemd/system/sssd.service`: + +``` +[Unit] +Description=System Security Services Daemon +# SSSD must be running before we permit user sessions +Before=systemd-user-sessions.service nss-user-lookup.target +Wants=nss-user-lookup.target +After=network-online.target + + +[Service] +Environment=DEBUG_LOGGER=--logger=files +EnvironmentFile=-/etc/sysconfig/sssd +ExecStart=/usr/sbin/sssd -i ${DEBUG_LOGGER} +Type=notify +NotifyAccess=main +PIDFile=/var/run/sssd.pid + +[Install] +WantedBy=multi-user.target +``` + +Beim nächsten Reboot wird der Dienst entsprechend seinen Anforderungen gestartet und alles wird gut gehen. + +## Verlassen des Active Directory + +Manchmal ist es notwendig, die Active Directory zu verlassen. + +Sie können erneut mit `realm` fortfahren und dann die nicht mehr benötigten Pakete entfernen: + +```sh +[user@host ~]$ sudo realm leave ad.company.local +[user@host ~]$ sudo dnf remove realmd oddjob oddjob-mkhomedir sssd adcli krb5-workstation +``` diff --git a/docs/guides/security/authentication/active_directory_authentication.fr.md b/docs/guides/security/authentication/active_directory_authentication.fr.md index 35fa14acb9..eef6acb81a 100644 --- a/docs/guides/security/authentication/active_directory_authentication.fr.md +++ b/docs/guides/security/authentication/active_directory_authentication.fr.md @@ -10,7 +10,7 @@ tested_with: 9.4 - Connaissances de base de Active Directory - Connaissances de base de LDAP -## Présentation de Active Directory +## Introduction Active Directory (AD) de Microsoft est, dans la plupart des entreprises, le système d'authentification standard pour les systèmes Windows et pour les applications externes connectées à LDAP. Il permet de configurer les utilisateurs et les groupes, le contrôle d'accès, les permissions, le montage automatique, etc. @@ -100,7 +100,7 @@ Si ce processus affiche un problème de chiffrement comme `KDC has no support fo [user@host ~]$ sudo update-crypto-policies --set DEFAULT:AD-SUPPORT ``` -Si ce processus réussit, vous devriez maintenant pouvoir extraire les informations `passwd` d'un utilisateur d'Active Directory. +Si la procédure est couronnée de succès, vous devriez maintenant pouvoir extraire les informations `passwd` d'un utilisateur d'Active Directory. ```sh [user@host ~]$ sudo getent passwd administrator@ad.company.local @@ -124,7 +124,7 @@ administrator@ad.company.local:*:1450400500:1450400513:Administrator:/home/admin Now your users should be able to authenticate to your Linux host against Active Directory. -**Sous Windows 10 :** (qui possède sa propre copie de OpenSSH) +**Sous Windows 10** (qui possède sa propre implémentation de OpenSSH) : ```dos C:\Users\John.Doe> ssh -l john.doe@ad.company.local linux.host From 23d7fc5e9849289f9fda1b53ccc6c17be4d7082a Mon Sep 17 00:00:00 2001 From: Rocky Linux Automation <75949597+rockylinux-auto@users.noreply.github.com> Date: Sun, 5 Oct 2025 09:24:39 -0400 Subject: [PATCH 3/7] New Crowdin updates (#2931) * New translations tracking_and_nontracking_branch.md (German) * New translations git_pull_vs_git_fetch.md (German) * New translations git_remote_add.md (German) * New translations git_pull_vs_git_fetch.md (German) --- .../gemstones/git/git_pull_vs_git_fetch.de.md | 70 +++++++++++++++++ docs/gemstones/git/git_remote_add.de.md | 78 +++++++++++++++++++ .../git/tracking_and_nontracking_branch.de.md | 73 +++++++++++++++++ 3 files changed, 221 insertions(+) create mode 100644 docs/gemstones/git/git_pull_vs_git_fetch.de.md create mode 100644 docs/gemstones/git/git_remote_add.de.md create mode 100644 docs/gemstones/git/tracking_and_nontracking_branch.de.md diff --git a/docs/gemstones/git/git_pull_vs_git_fetch.de.md b/docs/gemstones/git/git_pull_vs_git_fetch.de.md new file mode 100644 index 0000000000..7bfc75ec63 --- /dev/null +++ b/docs/gemstones/git/git_pull_vs_git_fetch.de.md @@ -0,0 +1,70 @@ +--- +title: "`git pull` und `git fetch` im Vergleich" +author: Wale Soyinka +contributors: Ganna Zhyrnova +tags: + - Git + - git pull + - git fetch +--- + +## Einleitung + +Dieses Gemstone erklärt die Unterschiede zwischen den Befehlen `git pull` und `git fetch`. Außerdem wird erläutert, wann welcher Befehl angemessen verwendet werden sollte. + +## Git Fetch versus Git Pull + +### Git Fetch + +`git fetch` lädt Änderungen aus einem Remote-Repository herunter, integriert sie jedoch nicht in Ihren lokalen Zweig. + +Es ist hilfreich zu sehen, was andere mit `commit` eingereicht haben, ohne diese Änderungen mit `merge` in Ihren lokalen Zweig zu übernehmen. + +1. Listet den aktuell ausgecheckten Zweig auf + + ```bash + git branch + ``` + +2. Rufen Sie Änderungen aus dem Hauptzweig eines Remote-Repos namens `origin` mit `fetch` ab. Geben Sie bitte Folgendes ein: + + ```bash + git fetch origin main + ``` + +3. Vergleichen Sie die Änderungen zwischen dem HEAD Ihres lokalen Repo und dem Remote-`origin/main`-Repo. + + ```bash + git log HEAD..origin/main + ``` + +### Git Pull + +`git pull` lädt Änderungen herunter und führt sie in Ihren aktuellen Branch zusammen. +Es ist nützlich, um Ihren lokalen Zweig schnell mit Änderungen aus dem Remote-Repository zu aktualisieren. + +1. **Änderungen abrufen und zusammenführen**: + + ```bash + git pull origin main + ``` + +2. **Mit `merge` zusammengeführte Änderungen Revue passieren**: + + ```bash + git log + ``` + +## Zusätzliche Anmerkungen + +- **Verwenden Sie `git fetch`**: + \-- Wenn Sie Änderungen vor dem Zusammenführen überprüfen müssen. + – Um unerwünschte Änderungen oder Konflikte in Ihrem lokalen Branch zu vermeiden. + +- **Verwenden Sie `git pull`**: + \-- Wenn Sie Ihren lokalen Branch mit den neuesten Commits aktualisieren möchten. + – Für schnelle, unkomplizierte Updates, ohne dass Änderungen vorher überprüft werden müssen. + +## Zusammenfassung + +Für ein effektives Git-Workflow-Management ist es wichtig, die Unterschiede zwischen `git fetch` und `git pull` zu verstehen. Die Auswahl des richtigen Befehls basierend auf Ihren Anforderungen ist wichtig, wenn Sie über Versionskontrollsysteme wie GitHub, GitLab, Gitea usw. arbeiten oder zusammenarbeiten. diff --git a/docs/gemstones/git/git_remote_add.de.md b/docs/gemstones/git/git_remote_add.de.md new file mode 100644 index 0000000000..576583e725 --- /dev/null +++ b/docs/gemstones/git/git_remote_add.de.md @@ -0,0 +1,78 @@ +--- +title: Hinzufügen eines Remote-Repositorys mithilfe der Git-CLI +author: Wale Soyinka +contributors: Ganna Zhyrnova +tags: + - GitHub + - git + - git remote + - git fetch +--- + +## Einleitung + +Dieses Gemstone veranschaulicht, wie mithilfe der Git-Befehlszeilenschnittstelle ein bestimmtes Remote-Repository zu einem vorhandenen lokalen Klon eines FOSS-Projekts hinzugefügt wird. +Wir verwenden das Repository des Rocky Linux-Dokumentationsprojekts als Beispiel für unser FOSS-Projekt - + +## Voraussetzungen + +- Ein Github-Konto. +- „git“ ist auf Ihrem System installiert. +- Ein lokaler Klon eines FOSS-Projekt-Repositorys. + +## Prozedur + +1. Öffnen Sie ein Terminal und ändern Sie Ihr Arbeitsverzeichnis in den Ordner, der Ihren lokalen Klon des Projekts enthält. + Wenn Sie beispielsweise das GitHub-Repository nach `~/path/to/your/rl-documentation-clone` geklont haben, geben Sie Folgendes ein + + ```bash + cd ~/path/to/your/rl-documentation-clone + ``` + +2. Bevor Sie Änderungen vornehmen, listen Sie die von Ihnen konfigurierten Remotes auf. Geben Sie bitte Folgendes ein: + + ```bash + git remote -vv + ``` + + Wenn es sich um ein frisch geklontes Repo handelt, sehen Sie in Ihrer Ausgabe wahrscheinlich ein einzelnes Remote mit dem Namen `origin`. + +3. Fügen Sie das Rocky Linux Documentation Repository (`https://github.com/rocky-linux/documentation.git`) als neues Remote zu Ihrem lokalen Repository hinzu. Hier weisen wir `upstream` als Namen für dieses bestimmte `Remote` zu. Geben Sie bitte Folgendes ein: + + ```bash + git remote add upstream https://github.com/rocky-linux/documentation.git + ``` + +4. To further emphasize that the names assigned to remote repositories are arbitrary, create another remote named rocky-docs that points to the same repo by running: + + ```bash + git remote add rocky-docs https://github.com/rocky-linux/documentation.git + ``` + +5. Bestätigen Sie, dass das neue Remote-Repository erfolgreich hinzugefügt wurde: + + ```bash + git remote -v + ``` + + Sie sollten `upstream` zusammen mit seiner URL aufgelistet sehen. + +6. Optional können Sie Daten aus dem neu hinzugefügten Remote abrufen, bevor Sie mit Änderungen an Ihrem lokalen Repo beginnen. + Rufen Sie mit `fetch` Zweige und Commits vom neu hinzugefügten Remote ab, indem Sie Folgendes ausführen: + + ```bash + git fetch upstream + ``` + +## Zusätzliche Anmerkungen + +- _origin_: Dies ist der Standardname, den Git dem Remote-Repository gibt, von dem Sie geklont haben. Es ist wie ein Spitzname für die Repository-URL. Wenn Sie ein Repository klonen, wird dieses Remote-Repository in Ihrer lokalen Git-Konfiguration automatisch als `origin` festgelegt. Der Name ist beliebig, soll aber gewissen Konventionen befolgen. + +- _upstream_: Dies bezieht sich oft auf das ursprüngliche Repository, wenn Sie ein Projekt geforkt haben. + Wenn Sie in Open-Source-Projekten ein Repository forken, um Änderungen vorzunehmen, ist das geforkte Repository Ihr `origin` und das ursprüngliche Repository wird normalerweise als `upstream` bezeichnet. Der Name ist beliebig, soll aber gewissen Konventionen befolgen. + + Diese subtile Unterscheidung zwischen der Verwendung/Zuweisung von `origin` und `remote` ist entscheidend, um durch Pull Requests zum ursprünglichen Projekt beizutragen. + +## Zusammenfassung + +Mit dem Dienstprogramm `git CLI` können Sie ganz einfach einen beschreibenden Namen verwenden und einem lokalen Klon eines FOSS-Projekts ein bestimmtes Remote-Repository hinzufügen. Auf diese Weise können Sie effektiv mit verschiedenen Repositorys synchronisieren und zu ihnen beitragen. diff --git a/docs/gemstones/git/tracking_and_nontracking_branch.de.md b/docs/gemstones/git/tracking_and_nontracking_branch.de.md new file mode 100644 index 0000000000..93178e2a2c --- /dev/null +++ b/docs/gemstones/git/tracking_and_nontracking_branch.de.md @@ -0,0 +1,73 @@ +--- +title: Tracking- vs. Non-Tracking-Branch in Git +author: Wale Soyinka +contributors: +tags: + - git + - git branch + - Tracking Branch + - Non-Tracking Branch +--- + +## Einleitung + +Dieses Gemstone befasst sich mit Tracking- und Non-Tracking-Zweigen in Git. Es enthält auch Schritte zum Überprüfen und Konvertieren zwischen den Zweigtypen. + +## Tracking Branch + +Ein Tracking-Branch ist ein Zweig, der mit einem Remote-Branch verknüpft ist. + +1. Erstellen Sie einen neuen Branch mit dem Namen `my-local-branch`. Sorgen Sie dafür, dass der neue lokale Zweig den Hauptzweig des Remote-Repositorys mit dem Namen `origin` verfolgt. Geben Sie bitte Folgendes ein: + + ```bash + git checkout -b my-local-branch origin/main + ``` + +2. Verwenden Sie den Befehl `git branch -vv`, um zu überprüfen, ob es sich bei dem Zweig um einen Tracking-Zweig handelt. Geben Sie bitte Folgendes ein: + + ```bash + git branch -vv + ``` + + Suchen Sie nach Zweigen mit `[origin/main]`, was darauf hinweist, dass sie `origin/main` verfolgen. + +## Non-Tracking Branch + +Ein `Non-Tracking-Branch` ist ein Zweig, der unabhängig von `Remote-Branch`es arbeitet. + +1. Erstellen Sie einen neuen lokalen Zweig ohne Nachverfolgung mit dem Namen `my-feature-branch`. Geben Sie bitte Folgendes ein: + + ```bash + git checkout -b my-feature-branch + ``` + +2. `Non-Tracking-Branches` zeigen in der Ausgabe von `git branch -vv` keinen `Remote-Branch` daneben an. Überprüfen Sie, ob `my-feature-branch` ein `Non-Tracking-Branch` ist. + +## Konvertierung von Non-Tracking in Tracking + +1. Stellen Sie optional zunächst sicher, dass die neuesten Änderungen aus dem Hauptzweig in den Zielzweig integriert werden. Geben Sie bitte Folgendes ein: + + ```bash + git checkout my-feature-branch + git merge main + ``` + +2. Richten Sie das Tracking für ein Remote-Branch ein: + + ```bash + git branch --set-upstream-to=origin/main my-feature-branch + ``` + + Ergebnis: `Branch 'my-feature-branch' set up to track remote branch 'main' from 'origin'.` + +3. Änderung prüfen. Geben Sie bitte Folgendes ein: + + ```bash + git branch -vv + ``` + + Jetzt sollte `my-feature-branch` `[origin/main]` anzeigen, was darauf hinweist, dass es sich um ein Tracking handelt. + +## Zusammenfassung + +Das Verständnis der Nuancen zwischen Tracking- und Nicht-Tracking-Branches ist in Git von entscheidender Bedeutung. Dieses Gemstone verdeutlicht diese Konzepte und zeigt auch, wie diese Branch-Typen identifiziert und zwischen ihnen konvertiert werden, um ein optimales Git-Workflow-Management zu gewährleisten. From 8db6a13cf464158ece93d943cf424789a318f454 Mon Sep 17 00:00:00 2001 From: wale soyinka Date: Sun, 5 Oct 2025 18:03:40 -0400 Subject: [PATCH 4/7] docs/desktop: Rewrite some desktop app guides for Rocky Linux 10 (#2930) * desktop category: Rewrite some desktop app guides for Rocky Linux 10 * docs/desktop: remove unused translated guides * desktop category: add new guide for valuta app * desktop category: apply @sspencerwire review feedbak to PR 2930 --- docs/desktop/gnome/decibels.de.md | 64 -------------- docs/desktop/gnome/decibels.fr.md | 64 -------------- docs/desktop/gnome/decibels.it.md | 64 -------------- docs/desktop/gnome/decibels.md | 82 +++++++++--------- docs/desktop/gnome/decibels.uk.md | 64 -------------- docs/desktop/gnome/decoder.de.md | 102 ---------------------- docs/desktop/gnome/decoder.fr.md | 102 ---------------------- docs/desktop/gnome/decoder.it.md | 102 ---------------------- docs/desktop/gnome/decoder.md | 113 +++++++++---------------- docs/desktop/gnome/decoder.uk.md | 102 ---------------------- docs/desktop/gnome/file-shredder.de.md | 53 ------------ docs/desktop/gnome/file-shredder.fr.md | 53 ------------ docs/desktop/gnome/file-shredder.it.md | 53 ------------ docs/desktop/gnome/file-shredder.md | 76 ++++++++++------- docs/desktop/gnome/file-shredder.uk.md | 53 ------------ docs/desktop/gnome/screenshot.de.md | 45 ---------- docs/desktop/gnome/screenshot.fr.md | 45 ---------- docs/desktop/gnome/screenshot.it.md | 45 ---------- docs/desktop/gnome/screenshot.md | 67 ++++++++++----- docs/desktop/gnome/screenshot.uk.md | 45 ---------- docs/desktop/gnome/valuta.de.md | 53 ------------ docs/desktop/gnome/valuta.fr.md | 53 ------------ docs/desktop/gnome/valuta.it.md | 53 ------------ docs/desktop/gnome/valuta.md | 64 +++++++------- docs/desktop/gnome/valuta.uk.md | 53 ------------ 25 files changed, 209 insertions(+), 1461 deletions(-) delete mode 100644 docs/desktop/gnome/decibels.de.md delete mode 100644 docs/desktop/gnome/decibels.fr.md delete mode 100644 docs/desktop/gnome/decibels.it.md delete mode 100644 docs/desktop/gnome/decibels.uk.md delete mode 100644 docs/desktop/gnome/decoder.de.md delete mode 100644 docs/desktop/gnome/decoder.fr.md delete mode 100644 docs/desktop/gnome/decoder.it.md delete mode 100644 docs/desktop/gnome/decoder.uk.md delete mode 100644 docs/desktop/gnome/file-shredder.de.md delete mode 100644 docs/desktop/gnome/file-shredder.fr.md delete mode 100644 docs/desktop/gnome/file-shredder.it.md delete mode 100644 docs/desktop/gnome/file-shredder.uk.md delete mode 100644 docs/desktop/gnome/screenshot.de.md delete mode 100644 docs/desktop/gnome/screenshot.fr.md delete mode 100644 docs/desktop/gnome/screenshot.it.md delete mode 100644 docs/desktop/gnome/screenshot.uk.md delete mode 100644 docs/desktop/gnome/valuta.de.md delete mode 100644 docs/desktop/gnome/valuta.fr.md delete mode 100644 docs/desktop/gnome/valuta.it.md delete mode 100644 docs/desktop/gnome/valuta.uk.md diff --git a/docs/desktop/gnome/decibels.de.md b/docs/desktop/gnome/decibels.de.md deleted file mode 100644 index ed5cfe6bcd..0000000000 --- a/docs/desktop/gnome/decibels.de.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Decibels -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Einleitung - -`Decibels` ist eine Anwendung zum Abspielen von Audiodateien. Die benutzerfreundliche Oberfläche erleichtert das Hochladen und Abspielen Ihrer Lieblingssongs, Vorlesungsaufzeichnungen, Projektideen und anderer Audiodateien. - -## Voraussetzungen - -Für diese Anleitung benötigen Sie Folgendes: - -- Rocky Linux -- Flatpak -- FlatHub - -## Installations-Ablauf - -Gehen Sie zu [Flathub.org] (https://flathub.org), geben Sie `Decibels` in die Suchleiste ein und klicken Sie auf **Install**. - -![Screenshot of the Decibels app page on FlatHub, showing the install button being highlighted by a red rectangle](images/01_decibels.png) - -![manual install script and run script](images/decibels-install.png) - -2. Kopieren Sie das manuelle Installationsskript und führen Sie es in einem Terminal aus: - - ```bash - flatpak install flathub org.gnome.Decibels - ``` - -3. Kopieren Sie abschließend den Ausführungsbefehl und rufen Sie ihn in Ihrem Terminal auf: - - ```bash - flatpak run org.gnome.Decibels - ``` - -## Anwendungshinweise - -Gehen Sie wie folgt vor, um `Decibels` zu verwenden: - -1. Auf **Open** klicken - - ![Screenshot of Decibels' landing page with a red rectangle surrounding the blue open button](images/02_decibels.png) - -2. Wählen Sie Ihre gewünschte Datei aus und klicken Sie auf **Open**, das in der oberen rechten Ecke des Bildschirms erscheint - - ![Screenshot of Decibels file selection interface with numbered arrows indicating audio file and Open button](images/03_decibels.png) - -!!! note "Anmerkung" - -``` -Sind Sie es leid, mit der Maus zu klicken? Hier finden Sie einige Möglichkeiten, wie Sie mit Ihrer Tastatur Ihre Audiodateien abspielen und mit ihnen interagieren können - -- ++ctrl++ + ++shift++ + ++o++ = Datei öffnen -- ++space++ = Abspielen oder Pause -- ++left++ = Audio um 10 Sekunden nach hinten verschieben -- ++right++ = Audio 10 Sekunden vorwärts bewegen -``` - -## Zusammenfassung - -Möchten Sie mehr über diese App erfahren oder haben Sie noch weitere Ideen dafür? [Submit an issue in Decibel's repository at GitLab](https://gitlab.gnome.org/GNOME/Incubator/decibels/-/issues). diff --git a/docs/desktop/gnome/decibels.fr.md b/docs/desktop/gnome/decibels.fr.md deleted file mode 100644 index 5f8fd393cd..0000000000 --- a/docs/desktop/gnome/decibels.fr.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Decibels -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Introduction - -`Decibels` est un logiciel qui lit des fichiers audio. Son interface conviviale facilite le téléchargement (et la lecture) de vos chansons préférées, ainsi que des enregistrements de cours, des idées de projets et d'autres fichiers. - -## Prérequis - -Ce guide suppose que vous disposez de la configuration suivante : - -- Rocky Linux -- Flatpak -- FlatHub - -## Processus d'Installation - -Accédez à [Flathub.org](https://flathub.org), tapez `Decibels` dans la barre de recherche et cliquez sur **Install**. - -![Screenshot of the Decibels app page on FlatHub, showing the install button being highlighted by a red rectangle](images/01_decibels.png) - -![manual install script and run script](images/decibels-install.png) - -2. Copiez le script d'installation manuelle et exécutez-le dans un terminal : - - ```bash - flatpak install flathub org.gnome.Decibels - ``` - -3. Enfin, copiez la commande à lancer et exécutez-la dans votre terminal : - - ```bash - flatpak run org.gnome.Decibels - ``` - -## Mode d'emploi - -Pour utiliser le programme `Decibels`, procédez comme suit : - -1. Cliquez sur **Open** - - ![Screenshot of Decibels' landing page with a red rectangle surrounding the blue open button](images/02_decibels.png) - -2. Sélectionnez le fichier souhaité et cliquez sur le bouton **Open** qui apparaîtra dans le coin supérieur droit de l'écran - - ![Screenshot of Decibels file selection interface with numbered arrows indicating audio file and Open button](images/03_decibels.png) - -!!! note "Remarque" - -``` -Fatigué de cliquer avec la souris ? Voici quelques façons d'utiliser le clavier pour interagir avec des fichiers audio - -- ++ctrl++ + ++shift++ + ++o++ = Ouvrir le fichier -- ++space++ = Lecture ou pause -- ++left++ = Reculer de 10 secondes -- ++right++ = Avancer de 10 secondes -``` - -## Conclusion - -Êtes-vous impatient d’en savoir plus sur cette application ou avez-vous des idées à proposer ? [Soumettez un issue au dépôt de Decibels sur GitLab](https://gitlab.gnome.org/GNOME/Incubator/decibels/-/issues). diff --git a/docs/desktop/gnome/decibels.it.md b/docs/desktop/gnome/decibels.it.md deleted file mode 100644 index 4090a415c8..0000000000 --- a/docs/desktop/gnome/decibels.it.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Decibels -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Introduzione - -Decibel è un'applicazione che riproduce file audio. L'interfaccia intuitiva consente di caricare e riprodurre facilmente le canzoni preferite, le registrazioni delle lezioni, le idee per i progetti e altri file audio. - -## Presupposti - -Questa guida presuppone che si disponga di quanto segue: - -- Rocky Linux -- Flatpak -- FlatHub - -## Processo di installazione - -Andate su [Flathub.org](https://flathub.org), digitate "Decibel" nella barra di ricerca e fate clic su **Install**. - -![Screenshot of the Decibels app page on FlatHub, showing the install button being highlighted by a red rectangle](images/01_decibels.png) - -![manual install script and run script](images/decibels-install.png) - -2. Copiare lo script di installazione manuale ed eseguirlo in un terminale: - - ```bash - flatpak install flathub org.gnome.Decibels - ``` - -3. Infine, copiate il comando run ed eseguitelo nel vostro terminale: - - ```bash - flatpak run org.gnome.Decibels - ``` - -## Guida all'uso - -Per utilizzare Decibel, procedere come segue: - -1. Cliccare su **Open** - - ![Screenshot of Decibels' landing page with a red rectangle surrounding the blue open button](images/02_decibels.png) - -2. Scegliere il file desiderato e fare clic su **Apri** che appare nell'angolo in alto a destra dello schermo - - ![Screenshot of Decibels file selection interface with numbered arrows indicating audio file and Open button](images/03_decibels.png) - -!!! note "Nota" - -``` -Stanchi di cliccare con il mouse? Ecco alcuni modi in cui potete usare la tastiera per riprodurre e interagire con i vostri file audio - -- ++ctrl++ + ++shift++ + ++o++ = Aprire il file -- ++space++ = Riproduzione o pausa -- ++left++ = Spostare l'audio indietro di 10 secondi -- ++right++ = Spostare l'audio in avanti di 10 secondi -``` - -## Conclusione - -Siete desiderosi di saperne di più su questa app o avete altre idee in merito? [Submit an issue in Decibel's repository at GitLab](https://gitlab.gnome.org/GNOME/Incubator/decibels/-/issues). diff --git a/docs/desktop/gnome/decibels.md b/docs/desktop/gnome/decibels.md index 889cce1a06..7cb46fa28e 100644 --- a/docs/desktop/gnome/decibels.md +++ b/docs/desktop/gnome/decibels.md @@ -1,64 +1,66 @@ --- -title: Decibels -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova +title: Decibels Audio Player +author: Wale Soyinka +contributors: +tags: + - gnome + - desktop + - audio + - flatpak --- -## Introduction +## A Simple, Modern Audio Player -Decibels is an application that plays audio files. Its user-friendly interface makes uploading and playing your favorite song(s), recordings of lectures, project ideas, and other audio files, easy. +**Decibels** is a modern and elegant audio player for the GNOME desktop. It is built on a philosophy of simplicity, designed to do one thing exceptionally well: play audio files. -## Assumptions +Unlike full-featured music library applications like Rhythmbox, Decibels does not manage a collection of music. Instead, it focuses on providing a clean, straightforward experience for playing individual sound files. Its signature feature is a beautiful waveform display that allows for easy and precise navigation through the audio track. -This guide assumes you have the following: +This makes it the perfect tool for quickly listening to a downloaded podcast, a voice memo, or a new song without the overhead of importing files into a library. -- Rocky Linux -- Flatpak -- FlatHub +## Installation -## Installation Process +The recommended way to install Decibels on Rocky Linux is as a Flatpak from the Flathub repository. This method ensures you have the latest version of the application, sandboxed from the rest of your system. -Go to [Flathub.org](https://flathub.org), type "Decibels" in the search bar, and click on **Install**. +### 1. Enable Flathub -![Screenshot of the Decibels app page on FlatHub, showing the install button being highlighted by a red rectangle](images/01_decibels.png) +First, ensure you have Flatpak installed and the Flathub remote configured on your system. -![manual install script and run script](images/decibels-install.png) +```bash +# Install the Flatpak package +sudo dnf install flatpak -2. Copy the manual install script and run it in a terminal: +# Add the Flathub remote repository +flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo +``` - ```bash - flatpak install flathub org.gnome.Decibels - ``` - -3. Finally, copy the run command and run that in your terminal: - - ```bash - flatpak run org.gnome.Decibels - ``` - - -## How to use +!!! note + You may need to log out and log back in for Flatpak applications to appear in the GNOME Activities Overview. -To use Decibels, do the following steps: +### 2. Install Decibels -1. Click on **Open** +Once Flathub is enabled, you can install Decibels with a single command: - ![Screenshot of Decibels' landing page with a red rectangle surrounding the blue open button](images/02_decibels.png) +```bash +flatpak install flathub org.gnome.Decibels +``` -2. Pick your desired file and click on the **Open** that appears in the upper right corner of the screen +## Basic Usage - ![Screenshot of Decibels file selection interface with numbered arrows indicating audio file and Open button](images/03_decibels.png) +After installation, you can launch Decibels from the GNOME Activities Overview by searching for "Decibels". +To play a file: -!!! note +1. Launch the application. You will be greeted by a clean, simple window. +2. Click the prominent **"Open a File..."** button in the center of the window. +3. Use the file chooser to navigate to and select an audio file on your system (e.g., an `.mp3`, `.flac`, `.ogg`, or `.wav` file). +4. The file will open, and its waveform will be displayed. Playback will begin automatically. - Tired of clicking with your mouse? Here are some ways you can use your keyboard to play and interact with your audio files +## Key Features - - ++ctrl++ + ++shift++ + ++o++ = Open File - - ++space++ = Play or Pause - - ++left++ = Move audio back 10 seconds - - ++right++ = Move audio forward 10 seconds +While simple, Decibels has several useful features: -## Conclusion +* **Waveform Navigation:** Instead of a simple progress bar, Decibels shows the audio's waveform. You can click anywhere on the waveform to instantly seek to that part of the track. +* **Playback Speed Control:** A control in the bottom-right corner allows you to adjust the playback speed, which is perfect for speeding up podcasts or slowing down audio for transcription. +* **Quick Skip Buttons:** Dedicated buttons allow you to jump backward or forward by 10-second intervals, making it easy to re-listen to a missed phrase. -Are you eager to learn more about this app, or do you have more ideas for it? [Submit an issue in Decibel's repository at GitLab](https://gitlab.gnome.org/GNOME/Incubator/decibels/-/issues). +Decibels is an excellent choice for anyone who needs a simple, elegant, and modern application for playing individual audio files on the GNOME desktop. diff --git a/docs/desktop/gnome/decibels.uk.md b/docs/desktop/gnome/decibels.uk.md deleted file mode 100644 index a5d680de37..0000000000 --- a/docs/desktop/gnome/decibels.uk.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Decibels -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Вступ - -Decibels — програма, яка відтворює аудіофайли. Його зручний інтерфейс спрощує завантаження та відтворення ваших улюблених пісень, а також записів лекцій, проектних ідей та інших файлів. - -## Припущення - -У цьому посібнику передбачається, що ви маєте наступне: - -- Rocky Linux -- Flatpak -- FlatHub - -## Процес встановлення - -Перейдіть на [Flathub.org](https://flathub.org), введіть «Decibels» в рядку пошуку та натисніть **Install**. - -![Screenshot of the Decibels app page on FlatHub, showing the install button being highlighted by a red rectangle](images/01_decibels.png) - -![manual install script and run script](images/decibels-install.png) - -2. Скопіюйте сценарій встановлення вручну та запустіть його в терміналі: - - ```bash - flatpak install flathub org.gnome.Decibels - ``` - -3. Нарешті, скопіюйте команду запуску та запустіть її у своєму терміналі: - - ```bash - flatpak run org.gnome.Decibels - ``` - -## Як використовувати - -Щоб скористатися програмою, виконайте такі дії: - -1. Натисніть _Open_ - - ![Screenshot of Decibels' landing page with a red rectangle surrounding the blue open button](images/02_decibels.png) - -2. Виберіть потрібний файл і натисніть кнопку **Open**, яка з’явиться у верхньому правому куті екрана - - ![Screenshot of Decibels file selection interface with numbered arrows indicating audio file and Open button](images/03_decibels.png) - -!!! note "Примітка" - -``` -Втомилися клацати мишею? Ось кілька способів використання клавіатури для відтворення аудіофайлів і взаємодії з ними - -- ++ctrl++ + ++shift++ + ++o++ = Відкрити файл -- ++space++ = Відтворити або призупинити -- ++left++ = Перемістити звук на 10 секунд назад -- ++right++ = Перемістити аудіо на 10 секунд вперед -``` - -## Висновок - -Ви прагнете дізнатися більше про цю програму чи маєте більше ідей для неї? [Надішліть ідею в репозиторій Decibel на GitLab](https://gitlab.gnome.org/GNOME/Incubator/decibels/-/issues). diff --git a/docs/desktop/gnome/decoder.de.md b/docs/desktop/gnome/decoder.de.md deleted file mode 100644 index 0f462fea71..0000000000 --- a/docs/desktop/gnome/decoder.de.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Decoder -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Einleitung - -Benötigen Sie einen QR-Code für Ihre Website, Anwendung oder Social-Media-Profile? Schauen Sie sich Decoder an! Mit der Anwendung können Sie QR-Codes erstellen, speichern und exportieren. - -## Voraussetzungen - -Für diese Anleitung benötigen Sie Folgendes: - -- Rocky Linux -- Flatpak -- FlatHub - -## Installations-Ablauf - -1. Gehen Sie zu [Flathub.org] (https://flathub.org), geben Sie `Decoder` in die Suchleiste ein und klicken Sie auf **Install**. ![Screenshot of the install button highlighted by a red rectangle](images/01_decoder.png) - - ![manual install script and run script](images/decoder_install.png) - -2. Kopieren Sie das manuelle Installationsskript und führen Sie es in einem Terminal aus: - - ```bash - flatpak install flathub com.belmoussaoui.Decoder - ``` - -3. Kopieren Sie abschließend den Ausführungsbefehl und rufen Sie ihn in Ihrem Terminal auf: - - ```bash - flatpak run com.belmoussaoui.Decoder - ``` - -## So erstellen Sie einen QR-Code - -Es stehen zwei Arten von QR-Codes zur Verfügung. Wählen Sie die Option, die Ihren Anforderungen am besten entspricht: - -- [Text](#text) -- [Wifi](#wifi) - -### Text - -![Screenshot of the test, description and URL, and Create buttons](images/02_decoder-text.png) - -1. Klicken Sie auf die Schaltfläche **Text** - -2. Fügen Sie einen Link zu Ihrer gewünschten Website hinzu und schreiben Sie bei Bedarf eine Beschreibung dazu - -3. Auf **Create** klicken - - ![Screenshot of the Save and Export screen with arrows](images/03_decoder-text.png) - -4. Auf **Save** klicken - -5. Auf **Export** klicken - -### Wifi - -![Screenshot showing all of the Wifi options with numbers and arrows](images/01_decoder-wifi.png) - -1. Klicken Sie auf die Schaltfläche **Wifi** -2. Fügen Sie den Netzwerknamen hinzu -3. Passwort hinzufügen -4. Wählen Sie aus, ob das Netzwerk ausgeblendet ist oder nicht -5. Wählen Sie den verwendeten Verschlüsselungsalgorithmus aus -6. Auf **Export** klicken -7. Auf **Save** klicken - -### So scannen Sie einen QR-Code - -Zusätzlich zum Erstellen und Generieren von QR-Codes können Sie mit Decoder auch QR-Codes scannen, die Sie auf Ihrem Computer gespeichert haben. Gehen Sie folgendermaßen vor: - -![Screenshot of a red circle on a grey button that has the word "Scan" written in black.](images/01_decoder-scan.png) - -1. Auf **Scan** klicken - - ![Screenshot of the rectangular button with the words "From a Screenshot" written in white.](images/02_decoder-scan.png) - -2. Auf **From a Screenshot** klicken - - ![Screenshot of grey square surrounding options menu, and red square surrounding the "Take a Screenshot button"](images/03_decoder-scan.png) - -3. Wählen Sie die gewünschten Effekte aus und klicken Sie auf **Screenshot erstellen** - - ![Screenshot of a red arrow pointing at a blue button that has the word "Share" written in white](images/04_decoder-scan.png) - -4. Auf **Share** klicken - -5. Scannen Sie den QR-Code mit Ihrem Mobilgerät - -!!! note "Anmerkung" - -``` -Um einen QR-Code direkt von Ihrem Computer aus zu scannen, müssen Sie der App Zugriff auf die Kamera Ihres Computers erlauben. -``` - -## Zusammenfassung - -Ganz gleich, ob Sie das WLAN eines Restaurants mit Freunden teilen, Ihr Geschäft ausbauen oder sich auf einer Konferenz mit anderen Fachleuten vernetzen möchten – Decoder vereinfacht das Erstellen und Scannen von QR-Codes. Sie möchten mehr über diese Anwendung erfahren oder haben weitere Ideen dazu? [Senden Sie ein Issue an sein Repository bei GitLab](https://gitlab.gnome.org/World/decoder/-/issues). diff --git a/docs/desktop/gnome/decoder.fr.md b/docs/desktop/gnome/decoder.fr.md deleted file mode 100644 index 12c01214c0..0000000000 --- a/docs/desktop/gnome/decoder.fr.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Decoder -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Introduction - -Besoin d'un code QR pour votre site Web, votre application ou vos profils de réseaux sociaux ? Découvrez `Decoder` ! C'est une application qui permet de créer, d'enregistrer et d'exporter des codes QR. - -## Prérequis - -Ce guide suppose que vous disposez de la configuration suivante : - -- Rocky Linux -- Flatpak -- FlatHub - -## Processus d'Installation - -1. Accédez au [site Web Flathub](https://flathub.org/), tapez `Decoder` dans la barre de recherche et cliquez sur **Install**. ![Screenshot of the install button highlighted by a red rectangle](images/01_decoder.png) - - ![manual install script and run script](images/decoder_install.png) - -2. Copiez le script d'installation manuelle et exécutez-le dans un terminal : - - ```bash - flatpak install flathub com.belmoussaoui.Decoder - ``` - -3. Enfin, copiez la commande à lancer et exécutez-la dans votre terminal : - - ```bash - flatpak run com.belmoussaoui.Decoder - ``` - -## Comment créer un code QR - -Deux types de codes QR sont disponibles. Choisissez l'option qui correspond le mieux à vos besoins : - -- [Text](#text) -- [Wifi](#wifi) - -### Text - -![Screenshot of the test, description and URL, and Create buttons](images/02_decoder-text.png) - -1. Cliquez sur le bouton **Text** - -2. Ajoutez un lien vers le site Web de votre choix et ajoutez une description si vous en souhaitez une - -3. Cliquez sur **Create**. - - ![Screenshot of the Save and Export screen with arrows](images/03_decoder-text.png) - -4. Cliquez sur **Save** - -5. Cliquez sur **Export** - -### Wifi - -![Screenshot showing all of the Wifi options with numbers and arrows](images/01_decoder-wifi.png) - -1. Cliquez sur le bouton **Wifi** -2. Ajoutez le nom du réseau -3. Ajoutez le mot de passe -4. Sélectionnez si le réseau est masqué ou non -5. Sélectionnez l'algorithme de cryptage utilisé -6. Cliquez sur **Export** -7. Cliquez sur **Save** - -### Comment scanner un code QR - -En plus de créer et de générer des codes QR, vous pouvez utiliser `Decoder` pour scanner les codes QR que vous avez enregistrés sur votre ordinateur. Voici comment procéder : - -![Screenshot of a red circle on a grey button that has the word "Scan" written in black.](images/01_decoder-scan.png) - -1. Cliquez sur **Scan** - - ![Screenshot of the rectangular button with the words "From a Screenshot" written in white.](images/02_decoder-scan.png) - -2. Cliquez sur **From a Screenshot** - - ![Screenshot of grey square surrounding options menu, and red square surrounding the "Take a Screenshot button"](images/03_decoder-scan.png) - -3. Choisissez les effets souhaités et cliquez sur **Prendre une capture d'écran** - - ![Screenshot of a red arrow pointing at a blue button that has the word "Share" written in white](images/04_decoder-scan.png) - -4. Cliquez sur **Share** - -5. Scannez le code QR avec votre appareil mobile - -!!! note "Remarque" - -``` -Pour scanner un code QR directement depuis votre ordinateur, assurez-vous d'accorder à l'application l'accès à l'appareil photo de votre ordinateur. -``` - -## Conclusion - -Qu'il s'agisse de partager le Wi-Fi d'un restaurant avec des amis, de développer votre entreprise ou de réseauter avec d'autres professionnels lors d'une conférence, `Decoder` peut faciliter le processus de création et de numérisation de codes QR. Vous souhaitez en savoir plus ou avoir plus d'idées pour cette application ? [Soumettez un issue à son dépôt sur GitLab](https://gitlab.gnome.org/World/decoder/-/issues). diff --git a/docs/desktop/gnome/decoder.it.md b/docs/desktop/gnome/decoder.it.md deleted file mode 100644 index c0b793f7cb..0000000000 --- a/docs/desktop/gnome/decoder.it.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Decoder -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Introduzione - -Avete bisogno di un codice QR per il vostro sito web, la vostra applicazione o i vostri profili sui social media? Scopri Decoder! L'applicazione consente di creare, salvare ed esportare codici QR. - -## Presupposti - -Questa guida presuppone che si disponga di quanto segue: - -- Rocky Linux -- Flatpak -- FlatHub - -## Processo dell'installazione - -1. Andate sul [sito web di Flathub](https://flathub.org/), digitate "Decoder" nella barra di ricerca e fate clic su **Install**. ![Screenshot of the install button highlighted by a red rectangle](images/01_decoder.png) - - ![manual install script and run script](images/decoder_install.png) - -2. Copiare lo script di installazione manuale ed eseguirlo in un terminale: - - ```bash - flatpak install flathub com.belmoussaoui.Decoder - ``` - -3. Infine, copiate il comando run ed eseguitelo nel vostro terminale: - - ```bash - flatpak run com.belmoussaoui.Decoder - ``` - -## Come creare un codice QR - -Sono disponibili due tipi di codici QR. Scegliete l'opzione più adatta alle vostre esigenze: - -- [Text](#text) -- [Wifi](#wifi) - -### Text - -![Screenshot of the test, description and URL, and Create buttons](images/02_decoder-text.png) - -1. Fare clic sul pulsante **Text** - -2. Aggiungete un link al sito web desiderato e aggiungete una descrizione, se la desiderate - -3. Cliccare su **Create** - - ![Screenshot of the Save and Export screen with arrows](images/03_decoder-text.png) - -4. Cliccare su **Save** - -5. Cliccare su **Export** - -### Wifi - -![Screenshot showing all of the Wifi options with numbers and arrows](images/01_decoder-wifi.png) - -1. Fare clic sul pulsante **Wifi** -2. Aggiungere il nome della rete -3. Aggiungere la password -4. Selezionare se la rete è nascosta o non nascosta -5. Selezionare l'algoritmo di crittografia utilizzato -6. Cliccare su **Export** -7. Cliccare su **Save** - -### Come scansionare un codice QR - -Oltre a creare e generare codici QR, è possibile utilizzare Decoder per scansionare i codici QR salvati sul computer. Fate quanto segue: - -![Screenshot of a red circle on a grey button that has the word "Scan" written in black.](images/01_decoder-scan.png) - -1. Cliccare su **Scan** - - ![Screenshot of the rectangular button with the words "From a Screenshot" written in white.](images/02_decoder-scan.png) - -2. Fare clic su **From a Screenshot** - - ![Screenshot of grey square surrounding options menu, and red square surrounding the "Take a Screenshot button"](images/03_decoder-scan.png) - -3. Scegliete gli effetti desiderati e cliccate su **Take a Screenshot** - - ![Screenshot of a red arrow pointing at a blue button that has the word "Share" written in white](images/04_decoder-scan.png) - -4. Cliccare su **Share** - -5. Scansionate il codice QR con il vostro dispositivo mobile - -!!! note "Nota" - -``` -Per scansionare un codice QR direttamente dal computer, è necessario concedere all'applicazione l'accesso alla fotocamera del computer. -``` - -## Conclusione - -Che si tratti di condividere il Wi-Fi di un ristorante con gli amici, di far crescere la propria attività o di fare rete con altri professionisti durante una conferenza, Decoder semplifica la creazione e la scansione dei codici QR. Siete desiderosi di saperne di più su questa applicazione o avete altre idee in merito? [Submit an issue to its repository at GitLab](https://gitlab.gnome.org/World/decoder/-/issues). diff --git a/docs/desktop/gnome/decoder.md b/docs/desktop/gnome/decoder.md index 0ec3bd1624..0152a8536d 100644 --- a/docs/desktop/gnome/decoder.md +++ b/docs/desktop/gnome/decoder.md @@ -1,96 +1,67 @@ --- -title: Decoder -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova +title: Decoder QR Code Tool +author: Wale Soyinka +contributors: +tags: + - gnome + - desktop + - qr code + - flatpak --- -## Introduction +## Scan and Generate QR Codes -Do you need a QR code for your website, application, or social media profiles? Check out Decoder! The application lets you create, save, and export QR codes. +**Decoder** is a simple and elegant utility for the GNOME desktop designed for a single purpose: working with QR codes. In a world where QR codes are used for everything from sharing Wi-Fi passwords to accessing restaurant menus, having a dedicated tool to handle them is essential. -## Assumptions +Decoder provides two primary functions in a clean, focused interface: +1. **Scanning:** Decode QR codes, either by using your computer's webcam or by selecting an image file. +2. **Generating:** Create your own QR codes from any text you provide. -This guide assumes you have the following: +Its tight integration with the GNOME desktop makes it feel like a natural part of the operating system. -- Rocky Linux -- Flatpak -- FlatHub +## Installation -## Installation Process +The recommended way to install Decoder on Rocky Linux is as a Flatpak from the Flathub repository. This method ensures you have the latest version of the application in a secure, sandboxed environment. -1. Go to the [Flathub website](https://flathub.org/), type "Decoder" in the search bar, and click on **Install**. ![Screenshot of the install button highlighted by a red rectangle](images/01_decoder.png) +### 1. Enable Flathub - ![manual install script and run script](images/decoder_install.png) +If you have not already done so, ensure you have Flatpak installed and the Flathub remote configured on your system. -2. Copy the manual install script and run it in a terminal: +```bash +# Install the Flatpak package +sudo dnf install flatpak - ```bash - flatpak install flathub com.belmoussaoui.Decoder - ``` +# Add the Flathub remote repository +flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo +``` -3. Finally, copy the run command and run that in your terminal: +### 2. Install Decoder - ```bash - flatpak run com.belmoussaoui.Decoder - ``` +Once Flathub is enabled, you can install Decoder with a single command: -## How to Create a QR Code +```bash +flatpak install flathub com.belmoussaoui.Decoder +``` -Two types of QR codes are available. Choose the option that best suits your needs: +## How to Use Decoder -- [Text](#text) -- [Wifi](#wifi) +After installation, you can launch Decoder from the GNOME Activities Overview. -### Text +### Scanning a QR Code -![Screenshot of the test, description and URL, and Create buttons](images/02_decoder-text.png) +When you first open Decoder, it is ready to scan. You have two options: -1. Click on the **Text** button -2. Add a link to your desired website and add a description if you want one -3. Click on **Create** +* **Scan with Camera:** Click the camera icon in the top-left. A window will appear showing your webcam's feed. Simply point the webcam at a QR code to scan it in real-time. +* **Scan from Image:** Click the image icon in the top-right. This will open a file chooser, allowing you to select a saved image or screenshot that contains a QR code. - ![Screenshot of the Save and Export screen with arrows](images/03_decoder-text.png) +Once a code is scanned, Decoder intelligently parses its content. If the code contains a website URL, it will display the link with a button to open it in your default web browser. If it contains plain text, it will display the text with a convenient button to copy it to your clipboard. -4. Click on **Save** -5. Click on **Export** +### Generating a QR Code -### Wifi +To create your own QR code, click the "Generate" button at the top of the Decoder window. -![Screenshot showing all of the Wifi options with numbers and arrows](images/01_decoder-wifi.png) +1. A text box will appear. Simply type or paste the text you wish to encode into this box. +2. As you type, a QR code representing your text is instantly generated on the right. +3. You can then click the **"Save as Image..."** button to save the QR code as a `.png` file, or click the **"Copy to Clipboard"** button to paste it into other applications. -1. Click on the **Wifi** button -2. Add the network name -3. Add the password -4. Select if the network is hidden or not hidden -5. Select the encryption algorithm used -6. Click on **Export** -7. Click on **Save** - -### How to Scan a QR code - -In addition to creating and generating QR codes, you can use Decoder to scan QR codes you saved on your computer. Do the following: - -![Screenshot of a red circle on a grey button that has the word "Scan" written in black.](images/01_decoder-scan.png) - -1. Click on **Scan** - - ![Screenshot of the rectangular button with the words "From a Screenshot" written in white.](images/02_decoder-scan.png) - -2. Click on **From a Screenshot** - - ![Screenshot of grey square surrounding options menu, and red square surrounding the "Take a Screenshot button"](images/03_decoder-scan.png) - -3. Pick your desired effects and click on **Take a Screenshot** - - ![Screenshot of a red arrow pointing at a blue button that has the word "Share" written in white](images/04_decoder-scan.png) - -4. Click on **Share** -5. Scan the QR code with your mobile device - -!!! note - - To scan a QR code directly from your computer, you must grant the app access to your computer's camera. - -## Conclusion - -Whether it is to share a restaurant's Wi-Fi with friends, grow your business, or network with other professionals at a conference, Decoder can ease creating and scanning QR codes. Are you eager to learn more about this application or have more ideas for it? [Submit an issue to its repository at GitLab](https://gitlab.gnome.org/World/decoder/-/issues). +Decoder is a perfect example of the GNOME design philosophy: a simple, beautiful, and highly effective tool that does one job exceptionally well. diff --git a/docs/desktop/gnome/decoder.uk.md b/docs/desktop/gnome/decoder.uk.md deleted file mode 100644 index e58c5f1349..0000000000 --- a/docs/desktop/gnome/decoder.uk.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Декодер -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Вступ - -Потрібен QR-код для вашого веб-сайту, програми чи профілів у соціальних мережах? Перевірте декодер! Програма дозволяє створювати, зберігати та експортувати QR-коди. - -## Припущення - -У цьому посібнику передбачається, що ви маєте наступне: - -- Rocky Linux -- Flatpak -- FlatHub - -## Процес встановлення - -1. Перейдіть на [веб-сайт Flathub](https://flathub.org/), введіть «Декодер» у рядку пошуку та натисніть **Встановити**. ![Screenshot of the install button highlighted by a red rectangle](images/01_decoder.png) - - ![manual install script and run script](images/decoder_install.png) - -2. Скопіюйте сценарій встановлення вручну та запустіть його в терміналі: - - ```bash - flatpak install flathub com.belmoussaoui.Decoder - ``` - -3. Нарешті, скопіюйте команду запуску та запустіть її у своєму терміналі: - - ```bash - flatpak run com.belmoussaoui.Decoder - ``` - -## Як створити QR-код - -Доступні два типи QR-кодів. Виберіть варіант, який найкраще відповідає вашим потребам: - -- [Text](#text) -- [Wifi](#wifi) - -### Text - -![Screenshot of the test, description and URL, and Create buttons](images/02_decoder-text.png) - -1. Натисніть кнопку **Text** - -2. Додайте посилання на потрібний веб-сайт і додайте опис, якщо хочете - -3. Натисніть **Create** - - ![Screenshot of the Save and Export screen with arrows](images/03_decoder-text.png) - -4. Натисніть **Save** - -5. Натисніть **Export** - -### Wifi - -![Screenshot showing all of the Wifi options with numbers and arrows](images/01_decoder-wifi.png) - -1. Натисніть кнопку **Wifi** -2. Додайте назву мережі -3. Додайте пароль -4. Виберіть, прихована мережа чи ні -5. Виберіть використовуваний алгоритм шифрування -6. Натисніть **Export** -7. Натисніть **Save** - -### Як сканувати QR-код - -Окрім створення та генерування QR-кодів, ви можете використовувати Decoder для сканування QR-кодів, які ви зберегли на своєму комп’ютері. Зробіть наступне: - -![Screenshot of a red circle on a grey button that has the word "Scan" written in black.](images/01_decoder-scan.png) - -1. Натисніть **Scan** - - ![Screenshot of the rectangular button with the words "From a Screenshot" written in white.](images/02_decoder-scan.png) - -2. Натисніть **From a Screenshot** - - ![Screenshot of grey square surrounding options menu, and red square surrounding the "Take a Screenshot button"](images/03_decoder-scan.png) - -3. Виберіть потрібні ефекти та натисніть **Take a Screenshot** - - ![Screenshot of a red arrow pointing at a blue button that has the word "Share" written in white](images/04_decoder-scan.png) - -4. Натисніть **Share** - -5. Відскануйте QR-код за допомогою мобільного пристрою - -!!! note "Примітка" - -``` -Щоб відсканувати QR-код безпосередньо з комп’ютера, потрібно надати програмі доступ до камери комп’ютера. -``` - -## Висновок - -Декодер може спростити створення та сканування QR-кодів, якщо ви хочете поділитися Wi-Fi ресторану з друзями, розвивати свій бізнес або спілкуватися з іншими професіоналами на конференції. Ви прагнете дізнатися більше про цю програму чи маєте більше ідей для неї? [Надішліть проблему до свого репозиторію на GitLab](https://gitlab.gnome.org/World/decoder/-/issues). diff --git a/docs/desktop/gnome/file-shredder.de.md b/docs/desktop/gnome/file-shredder.de.md deleted file mode 100644 index 275a3baa6c..0000000000 --- a/docs/desktop/gnome/file-shredder.de.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: File Shredder -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Einleitung - -Möchten Sie eine Postkarte oder eine PDF-Datei mit Informationen wie Ihrem Geburtstag entfernen? Probieren Sie `File Shredder` aus, eine Anwendung, die vertrauliche Online-Informationen dauerhaft löscht. - -## Voraussetzungen - -Für diese Anleitung benötigen Sie Folgendes: - -- Rocky Linux -- Flatpak -- FlatHub - -## Installations-Ablauf - -![Screenshot of the File Shredder app page on FlatHub, showing the blue install button being highlighted by a red rectangle](images/01_file-shredder.png) - -1. Gehen Sie zu [Flathub.org] (https://flathub.org), geben Sie `File Shredder` in die Suchleiste ein und klicken Sie auf **Install** - - ![manual install script and run script](images/file-shredder_install.png) - -2. Kopieren Sie das manuelle Skript in Ihr Terminal: - - ```bash - flatpak install flathub io.github.ADBeveridge.Raider - ``` - -3. Führen Sie anschließend das manuelle Installationsskript in Ihrem Terminal aus: - - ```bash - flatpak run flathub io.github.ADBeveridge.Raider - ``` - -## Anwendungshinweise - -Gehen Sie wie folgt vor, um `File Shredder` zu verwenden: - -1. Ziehen oder klicken Sie auf **Add file**, um die Datei(en) auszuwählen, die Sie entfernen möchten - - ![Screenshot of the File Shredder homepage, showing the add drop-down menu and drop here button being highlighted by red rectangles](images/02_file-shredder.png) - -2. Auf **Shred All** klicken - -![Screenshot of a file named Social Security appearing on top. Unten befindet sich eine rote Schaltfläche mit dem Satz „Shred All“ in weißer Schrift, umgeben von einem roten Rechteck](images/03_file-shredder.png) - -## Zusammenfassung - -Ob Sozialversicherungsakten oder Bankauszüge: Mit dem Tool `File Shredder` können Sie Dateien ganz einfach vernichten, ohne einen Aktenvernichter kaufen zu müssen. Sie möchten mehr über diese Anwendung erfahren oder haben weitere Ideen dazu? [Ein Issue im Repository von File Shredder bei GitHub anlegen](https://github.com/ADBeveridge/raider/issues). diff --git a/docs/desktop/gnome/file-shredder.fr.md b/docs/desktop/gnome/file-shredder.fr.md deleted file mode 100644 index cdb18c8473..0000000000 --- a/docs/desktop/gnome/file-shredder.fr.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: File Shredder -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Introduction - -Besoin de supprimer une carte postale ou un fichier PDF contenant des informations telles que votre date de naissance ? Découvrez `File Shredder`, une application qui supprime définitivement les informations sensibles en ligne. - -## Prérequis - -Ce guide suppose que vous disposez de la configuration suivante : - -- Rocky Linux -- Flatpak -- FlatHub - -## Processus d'Installation - -![Screenshot of the File Shredder app page on FlatHub, showing the blue install button being highlighted by a red rectangle](images/01_file-shredder.png) - -1. Accédez au [site Web Flathub](https://flathub.org/), tapez `File Shredder` dans la barre de recherche et cliquez sur **Install** - - ![manual install script and run script](images/file-shredder_install.png) - -2. Copiez le script d'installation manuelle dans un terminal : - - ```bash - flatpak install flathub io.github.ADBeveridge.Raider - ``` - -3. Enfin, exécutez le script d'installation manuelle dans votre terminal : - - ```bash - flatpak run flathub io.github.ADBeveridge.Raider - ``` - -## Mode d'emploi - -Pour utiliser le programme `File Shredder`, procédez comme suit : - -1. Faites glisser ou cliquez sur **Add File** pour sélectionner le(s) fichier(s) que vous souhaitez supprimer - - ![Screenshot of the File Shredder homepage, showing the add drop-down menu and drop here button being highlighted by red rectangles](images/02_file-shredder.png) - -2. Cliquez sur **Shred All** - -![Screenshot of a file named Social Security appearing on top. At the bottom, there is a red button with the phrase Shred All written in white font and surrounded by a red rectangle](images/03_file-shredder.png) - -## Conclusion - -Qu’il s’agisse d’un dossier de sécurité sociale ou d’un relevé bancaire, File Shredder est l’outil qui permet de supprimer définitivement des fichiers sans avoir à acheter un shredder. Vous souhaitez en savoir plus ou proposer des idées pour cette application ? [Soumettez un issue dans le dépôt de File Shredder sur GitHub](https://github.com/ADBeveridge/raider/issues). diff --git a/docs/desktop/gnome/file-shredder.it.md b/docs/desktop/gnome/file-shredder.it.md deleted file mode 100644 index ad99ae2a61..0000000000 --- a/docs/desktop/gnome/file-shredder.it.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: File Shredder -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Introduzione - -Dovete rimuovere una cartolina o un file PDF contenente informazioni come il vostro compleanno? Scoprite File Shredder, un'applicazione che rimuove in modo permanente le informazioni sensibili online. - -## Presupposti - -Questa guida presuppone che si disponga di quanto segue: - -- Rocky Linux -- Flatpak -- FlatHub - -## Processo di installazione - -![Screenshot of the File Shredder app page on FlatHub, showing the blue install button being highlighted by a red rectangle](images/01_file-shredder.png) - -1. Andate sul [sito web di Flathub](https://flathub.org), digitate "File Shredder" nella barra di ricerca e cliccate su **Install** - - ![manual install script and run script](images/file-shredder_install.png) - -2. Copiare lo script manuale nel terminale: - - ```bash - flatpak install flathub io.github.ADBeveridge.Raider - ``` - -3. Infine, eseguire lo script manuale nel terminale: - - ```bash - flatpak run flathub io.github.ADBeveridge.Raider - ``` - -## Istruzioni - -Per utilizzare File Shredder, procedere come segue: - -1. Trascinare o fare clic su **Aggiungi file** per scegliere il file o i file che si desidera rimuovere - - ![Screenshot of the File Shredder homepage, showing the add drop-down menu and drop here button being highlighted by red rectangles](images/02_file-shredder.png) - -2. Cliccare su **Shred All** - -![Screenshot of a file named Social Security appearing on top. In basso, c'è un pulsante rosso con la frase Shred All scritta in caratteri bianchi e circondata da un rettangolo rosso](images/03_file-shredder.png) - -## Conclusione - -Che si tratti di un file della previdenza sociale o di un estratto conto bancario, File Shredder è lo strumento che consente di distruggere facilmente i file senza dover acquistare un distruggidocumenti. Siete desiderosi di saperne di più su questa applicazione o avete altre idee in merito? [Submit an issue in File Shredder's repository at GitHub](https://github.com/ADBeveridge/raider/issues). diff --git a/docs/desktop/gnome/file-shredder.md b/docs/desktop/gnome/file-shredder.md index 9df0ff5afd..d9eb854e1e 100644 --- a/docs/desktop/gnome/file-shredder.md +++ b/docs/desktop/gnome/file-shredder.md @@ -1,53 +1,67 @@ --- -title: File Shredder -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova +title: File Shredder - Secure Deletion +author: Wale Soyinka +contributors: +tags: + - gnome + - desktop + - security + - privacy + - flatpak --- - -## Introduction -Do you need to remove a postcard or a PDF file containing information like your birthday? Check out File Shredder, an application that permanently removes sensitive information online. +## Permanently and Securely Delete Files -## Assumptions +When you delete a file using your file manager, the data is not actually erased. The operating system simply marks the space on your hard drive as "available," leaving the original data intact until it is eventually overwritten by new files. This means that "deleted" files can often be recovered using specialized software. -This guide assumes you have the following: +**File Shredder** is a simple, modern utility for the GNOME desktop that solves this problem by allowing you to permanently and securely delete files. It does this by overwriting the file's data with random noise multiple times before deleting it, making recovery practically impossible. -- Rocky Linux -- Flatpak -- FlatHub +## Installation -## Installation Process +The recommended way to install File Shredder on Rocky Linux is as a Flatpak from the Flathub repository. -![Screenshot of the File Shredder app page on FlatHub, showing the blue install button being highlighted by a red rectangle](images/01_file-shredder.png) +### 1. Enable Flathub -1. Go to [Flathub's website](https://flathub.org), type "File Shredder" in the search bar, and click on **Install** +If you have not already done so, ensure you have Flatpak installed and the Flathub remote configured on your system. - ![manual install script and run script](images/file-shredder_install.png) +```bash +# Install the Flatpak package +sudo dnf install flatpak -2. Copy the manual script in your terminal: +# Add the Flathub remote repository +flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo +``` - ```bash - flatpak install flathub io.github.ADBeveridge.Raider - ``` +### 2. Install File Shredder -3. Finally, run the manual script in your terminal: +Once Flathub is enabled, you can install File Shredder with a single command. - ```bash - flatpak run flathub io.github.ADBeveridge.Raider - ``` +!!! note "Application ID" + The application is named "File Shredder," but its technical ID on Flathub is `io.github.ADBeveridge.Raider`. -## How to Use +```bash +flatpak install flathub io.github.ADBeveridge.Raider +``` -To use File Shredder, do the following: +## How to Use File Shredder -1. Drag or click on **Add file** to pick the file(s) you want to remove +After installation, launch the application from the GNOME Activities Overview by searching for "File Shredder". - ![Screenshot of the File Shredder homepage, showing the add drop-down menu and drop here button being highlighted by red rectangles](images/02_file-shredder.png) +The process is straightforward: -2. Click on **Shred All** +1. Drag and drop the files or folders you wish to permanently erase directly onto the File Shredder window. Alternatively, click the **"Add Files..."** or **"Add Folder..."** buttons. +2. The files will appear in a list. Review this list carefully. +3. When you are absolutely certain you want to destroy the files forever, click the **Shred** button. - ![Screenshot of a file named Social Security appearing on top. At the bottom, there is a red button with the phrase Shred All written in white font and surrounded by a red rectangle](images/03_file-shredder.png) +!!! warning "This Action Is Irreversible" + There is no "undo" button. Once a file is shredded, it is gone permanently. Double-check the files you have added before clicking the Shred button. -## Conclusion +## An Important Consideration for SSDs -Whether it’s a Social Security file or a banking statement, File Shredder is the tool that makes it easy to shred files without needing to buy a shredder. Are you eager to learn more about this application or have more ideas for it? [Submit an issue in File Shredder's repository at GitHub](https://github.com/ADBeveridge/raider/issues). +While File Shredder is highly effective on traditional magnetic hard disk drives (HDDs), its effectiveness on modern Solid-State Drives (SSDs) has limitations. + +SSDs use complex internal mechanisms like wear-leveling and garbage collection to manage data and prolong the drive's life. These mechanisms mean that the drive itself, not the operating system, decides where data is physically written. A software tool like File Shredder cannot force an SSD to overwrite a specific physical block of data. + +Therefore, while using File Shredder on an SSD makes data recovery significantly more difficult than a standard deletion, it **cannot guarantee** that all traces of the data have been physically erased from the drive's memory cells. For the highest level of data security on an SSD, the recommended approach is to use full-disk encryption (such as LUKS, which can be set up during the installation of Rocky Linux). + +File Shredder remains a valuable tool for enhancing your data privacy, especially on HDDs, and provides a strong layer of security for most use cases. diff --git a/docs/desktop/gnome/file-shredder.uk.md b/docs/desktop/gnome/file-shredder.uk.md deleted file mode 100644 index af428bf672..0000000000 --- a/docs/desktop/gnome/file-shredder.uk.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: File Shredder -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Вступ - -Вам потрібно видалити листівку чи PDF-файл, що містить інформацію, як-от ваш день народження? Перевірте File Shredder. - -## Припущення - -У цьому посібнику передбачається, що ви маєте наступне: - -- Rocky Linux -- Flatpak -- FlatHub - -## Процес встановлення - -![Screenshot of the File Shredder app page on FlatHub, showing the blue install button being highlighted by a red rectangle](images/01_file-shredder.png) - -1. Перейдіть на [веб-сайт Flathub](https://flathub.org), введіть «File Shredder» у рядку пошуку та натисніть **Install** - - ![manual install script and run script](images/file-shredder_install.png) - -2. Скопіюйте скрипт у свій термінал: - - ```bash - flatpak install flathub io.github.ADBeveridge.Raider - ``` - -3. Нарешті, запустіть сценарій у вашому терміналі: - - ```bash - flatpak run flathub io.github.ADBeveridge.Raider - ``` - -## Як цим користуватися - -Щоб скористатися File Shredder, виконайте такі дії: - -1. Перетягніть або клацніть **Add file**, щоб вибрати файли, які потрібно видалити - - ![Screenshot of the File Shredder homepage, showing the add drop-down menu and drop here button being highlighted by red rectangles](images/02_file-shredder.png) - -2. Натисніть **Shred All** - -![Screenshot of a file named Social Security appearing on top. At the bottom, there is a red button with the phrase Shred All written in white font and surrounded by a red rectangle](images/03_file-shredder.png) - -## Висновок - -Незалежно від того, чи це файл соціального страхування, чи виписка з банківського рахунку, File Shredder — це інструмент, який дозволяє легко знищувати файли, не купуючи шредер. Ви прагнете дізнатися більше про цю програму чи маєте більше ідей для неї? [Надішліть проблему в репозиторій File Shredder на GitHub](https://github.com/ADBeveridge/raider/issues). diff --git a/docs/desktop/gnome/screenshot.de.md b/docs/desktop/gnome/screenshot.de.md deleted file mode 100644 index 35b943e079..0000000000 --- a/docs/desktop/gnome/screenshot.de.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Screenshot -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Einleitung - -Sind Sie es leid, mit der Tastatur Bilder auf Ihrem Computerbildschirm aufzunehmen? Lernen Sie `Screenshot` kennen, eine Anwendung, die Ihnen hilft, schnell Bildschirmbilder aufzunehmen. - -## Voraussetzungen - -Für diese Anleitung benötigen Sie Folgendes: - -- Rocky Linux - -!!! note "Anmerkung" - -``` -Laut [der GNOME-Website](https://apps.gnome.org/) ist diese Anwendung auf Ihrem Desktop vorinstalliert. -``` - -## Anwendungshinweise - -Gehen Sie wie folgt vor, um `Screenshot` zu verwenden: - -![Screenshot of image being taken by the application with the options present](images/screenshot-01.png) - -1. Wählen Sie das Bildschirmbild aus, von dem Sie einen Screenshot machen möchten, gehen Sie zur Anwendung und wählen Sie die Methode, mit der Sie Ihr Bild aufnehmen möchten. - -2. Auf **Take a Screenshot** klicken - - ![Screenshot of taken picture of being saved with black arrows pointing at a text box that contains the file name, "Linux.png" as well as Save and Copy buttons](images/screenshot-02.png) - -3. Wenn Sie mit dem Screenshot zufrieden sind, benennen Sie die Datei um und klicken Sie auf **Save**. - -!!! tip "Hinweis" - -``` -Möchten Sie Speicherplatz auf Ihrem Computer sparen? Klicken Sie auf **Copy**, um Ihren Screenshot schnell zu Ihrer Arbeit hinzuzufügen. -``` - -## Zusammenfassung - -Ganz gleich, ob es sich um ein Bild für Ihre Online-Collage, den Hintergrund Ihres Computers oder ein Tutorial handelt, das Sie für Ihr Lieblingsprodukt erstellen, GNOMEs Screenshot ist das Tool, das Ihnen dabei hilft, die gewünschten Screenshots zu erstellen. Sie möchten mehr über diese Anwendung erfahren oder haben weitere Ideen dazu? [Ein Issue in dem Screenshots Repository bei GitLab anlegen](https://gitlab.gnome.org/gnumdk/screenshot/-/issues). diff --git a/docs/desktop/gnome/screenshot.fr.md b/docs/desktop/gnome/screenshot.fr.md deleted file mode 100644 index 33b74c0560..0000000000 --- a/docs/desktop/gnome/screenshot.fr.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Screenshot – Captures d'Écran -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Introduction - -Fatigué d'utiliser votre clavier pour prendre des images sur l'écran de votre ordinateur ? Découvrez le logiciel `Screenshot`, une application qui vous aide à prendre rapidement des images à l'écran. - -## Prérequis - -Ce guide suppose que vous disposez de la configuration suivante : - -- Rocky Linux - -!!! note "Remarque" - -``` -Selon [le site Web de GNOME](https://apps.gnome.org/), cette application est préinstallée sur votre bureau. -``` - -## Mode d'emploi - -Pour utiliser le programme `Screenshot`, procédez comme suit : - -![Screenshot of image being taken by the application with the options present](images/screenshot-01.png) - -1. Sélectionnez l'image à l'écran que vous souhaitez capturer, accédez à l'application, choisissez la méthode que vous souhaitez utiliser pour prendre votre photo. - -2. Cliquez sur **Take a Screenshot** - - ![Screenshot of taken picture of being saved with black arrows pointing at a text box that contains the file name, "Linux.png" as well as Save and Copy buttons](images/screenshot-02.png) - -3. Une fois que vous êtes satisfait de la capture d'écran, renommez le fichier et cliquez sur **Save**. - -!!! tip "Astuce" - -``` -Vous souhaitez économiser l'espace de stockage de votre ordinateur ? Cliquez sur **Copy** pour ajouter rapidement votre capture d'écran à votre travail. -``` - -## Conclusion - -Qu'il s'agisse d'une image pour votre collage en ligne, de l'arrière-plan de votre ordinateur ou d'un tutoriel que vous créez pour votre produit préféré, `Screenshot` de GNOME est l'outil qui vous aide à obtenir les captures d'écran que vous souhaitez. Vous souhaitez en savoir plus ou proposer des idées pour cette application ? [Soumettez un `issue` au référentiel Screenshot sur GitLab](https://gitlab.gnome.org/gnumdk/screenshot/-/issues). diff --git a/docs/desktop/gnome/screenshot.it.md b/docs/desktop/gnome/screenshot.it.md deleted file mode 100644 index a775d69aa1..0000000000 --- a/docs/desktop/gnome/screenshot.it.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Screenshot -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Introduzione - -Siete stanchi di usare la tastiera per scattare immagini dello schermo del computer? Ecco Screenshot, un'applicazione che aiuta a scattare rapidamente immagini dello schermo. - -## Presupposti - -Questa guida presuppone che si disponga di quanto segue: - -- Rocky Linux - -!!! note "Nota" - -``` -Secondo [il sito web di GNOME](https://apps.gnome.org/), questa applicazione è preinstallata sul desktop. -``` - -## Come si usa - -Per utilizzare Screenshot, procedere come segue: - -![Screenshot of image being taken by the application with the options present](images/screenshot-01.png) - -1. Scegliere l'immagine sullo schermo che si desidera fotografare, accedere all'applicazione e scegliere il metodo che si desidera utilizzare per scattare la foto. - -2. Fare clic su **Fai uno screenshot** - - ![Screenshot of taken picture of being saved with black arrows pointing at a text box that contains the file name, "Linux.png" as well as Save and Copy buttons](images/screenshot-02.png) - -3. Una volta soddisfatti della schermata, rinominare il file e fare clic su **Salva**. - -!!! tip "Suggerimento" - -``` -Volete risparmiare la memoria del vostro computer? Cliccate su **Copia** per aggiungere rapidamente lo screenshot al vostro lavoro. -``` - -## Conclusione - -Che si tratti di un'immagine per il vostro collage online, dello sfondo del vostro computer o di un tutorial per il vostro prodotto preferito, Screenshot di GNOME è lo strumento che vi aiuterà a ottenere le schermate che desiderate. Siete desiderosi di saperne di più su questa applicazione o avete altre idee in merito? [Sottoporre un problema al repository di Screenshot su GitLab](https://gitlab.gnome.org/gnumdk/screenshot/-/issues). diff --git a/docs/desktop/gnome/screenshot.md b/docs/desktop/gnome/screenshot.md index d2a2614fbc..cfaeb34a1a 100644 --- a/docs/desktop/gnome/screenshot.md +++ b/docs/desktop/gnome/screenshot.md @@ -1,40 +1,65 @@ --- -title: Screenshot -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova +title: Taking Screenshots and Recording Screencasts in GNOME +author: Wale Soyinka +contributors: +tags: + - gnome + - desktop + - screenshot + - screencast + - guide --- -## Introduction -Are you tired of using your keyboard to take images on your computer screen? Meet Screenshot, an application that helps you quickly take onscreen images. +## Taking Screenshots and Recording Screencasts in GNOME -## Assumptions +The modern GNOME desktop, featured in Rocky Linux, includes a powerful and seamlessly integrated tool for capturing your screen. This is not a separate application you need to install; it is a core part of the desktop shell, providing a fluid and efficient way to take screenshots and record short videos (screencasts). -This guide assumes you have the following: +This guide covers how to use both the interactive user interface and the powerful keyboard shortcuts to capture your screen content. -- Rocky Linux +## Using the Interactive Screenshot UI -!!! note +The easiest way to start is with the interactive overlay, which gives you full control over what and how you capture. - According [to GNOME's website](https://apps.gnome.org/), this application is pre-installed on your desktop. +1. **Launch the Tool:** Press the `Print Screen` (often labeled `PrtSc`) key on your keyboard. The screen will dim, and the screenshot UI will appear. -## How to Use +2. **Understand the Interface:** The control panel in the middle of the screen has three main sections: + * **Capture Mode:** On the left, you can choose to capture a rectangular `Region`, the entire `Screen`, or a specific `Window`. + * **Action Toggle:** In the center, you can switch between taking a **Screenshot** (camera icon) or recording a **Screencast** (video camera icon). + * **Capture Button:** The large, round button on the right initiates the capture. -To use Screenshot, do the following: +### Taking a Screenshot -![Screenshot of image being taken by the application with the options present](images/screenshot-01.png) +1. Ensure the action toggle is set to **Screenshot** (the camera icon). +2. Select your capture mode: `Region`, `Screen`, or `Window`. +3. Click the round **Capture** button. -1. Pick the onscreen image you want to screenshot, go to the application, and choose the method you wish to use to take your picture. +By default, the screenshot image is automatically saved to the `Pictures/Screenshots` directory in your home folder. -2. Click **Take a Screenshot** +### Recording a Screencast - ![Screenshot of taken picture of being saved with black arrows pointing at a text box that contains the file name, "Linux.png" as well as Save and Copy buttons](images/screenshot-02.png) +1. Set the action toggle to **Screencast** (the video camera icon). +2. Select the area you wish to record (`Region` or `Screen`). +3. Click the round **Capture** button to begin recording. -3. Once you're satisfied with the screenshot, rename the file and click on **Save**. +A red dot (●) will appear in the top-right corner of your screen, along with a timer, indicating that recording is active. To stop, simply click this red dot. The video will be automatically saved as a `.webm` file in the `Videos/Screencasts` directory in your home folder. -!!! tip +## Keyboard Shortcuts for Power Users - Want to save your computer's storage? Click on **Copy** to quickly add your screenshot to your work. +For even faster captures, GNOME provides a set of direct keyboard shortcuts that bypass the interactive UI. -## Conclusion +| Shortcut | Action | +| :--- | :--- | +| `Print Screen` | Open the interactive screenshot UI. | +| `Alt + Print Screen` | Take a screenshot of the currently active window immediately. | +| `Shift + Print Screen` | Immediately start selecting a rectangular area for a screenshot. | +| `Ctrl + Alt + Shift + R` | Start and stop a recording of the entire screen. | -Whether it is a picture for your online collage, your computer's background, or a tutorial that you are creating for your favorite product, GNOME's Screenshot is the tool to help you get the screenshots you want. Are you eager to learn more about this application or have more ideas for it? [Submit an issue to Screenshot’s repository at GitLab](https://gitlab.gnome.org/gnumdk/screenshot/-/issues). +### The "Copy to Clipboard" Modifier + +This is a powerful productivity feature. By adding the `Ctrl` key to any of the screenshot shortcuts, the captured image will be copied directly to your clipboard instead of being saved to a file. This is perfect for quickly pasting a screenshot into another application like a document or chat window. + +* **`Ctrl + Print Screen`**: Open the interactive UI, but the capture will go to the clipboard. +* **`Ctrl + Alt + Print Screen`**: Copy a screenshot of the active window to the clipboard. +* **`Ctrl + Shift + Print Screen`**: Copy a screenshot of a selected area to the clipboard. + +The built-in GNOME screenshot and screencast tool is a perfect example of elegant and efficient design, providing both a simple, discoverable interface for new users and a fast, shortcut-driven workflow for power users. diff --git a/docs/desktop/gnome/screenshot.uk.md b/docs/desktop/gnome/screenshot.uk.md deleted file mode 100644 index 06260bf8e8..0000000000 --- a/docs/desktop/gnome/screenshot.uk.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Screenshot -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Вступ - -Вам набридло використовувати клавіатуру для зйомки зображень на екрані комп’ютера? Зустрічайте Screenshot! - -## Припущення - -У цьому посібнику передбачається, що ви маєте наступне: - -- Rocky Linux - -!!! note "Примітка" - -``` -Відповідно до [веб-сайту GNOME](https://apps.gnome.org/), ця програма попередньо встановлена ​​на вашому робочому столі. -``` - -## Як цим користуватися - -Щоб використовувати Screenshot, виконайте такі дії: - -![Screenshot of image being taken by the application with the options present](images/screenshot-01.png) - -1. Виберіть зображення на екрані, яке ви хочете зробити, перейдіть до програми та виберіть спосіб, який ви хочете використовувати, щоб зробити знімок. - -2. Натисніть **Take a Screenshot** - - ![Screenshot of taken picture of being saved with black arrows pointing at a text box that contains the file name, "Linux.png" as well as Save and Copy buttons](images/screenshot-02.png) - -3. Коли ви будете задоволені знімком екрана, перейменуйте файл і натисніть **Зберегти**. - -!!! tip "Підказка" - -``` -Хочете заощадити пам’ять комп’ютера? Натисніть **Copy**, щоб швидко додати знімок екрана до своєї роботи. -``` - -## Висновок - -Незалежно від того, чи це зображення для вашого онлайн-колажу, фон вашого комп’ютера чи підручник, який ви створюєте для свого улюбленого продукту, Screenshot GNOME — це інструмент, який допоможе вам отримати потрібні знімки екрана. Ви прагнете дізнатися більше про цю програму чи маєте більше ідей для неї? [Надішліть проблему до репозиторію Screenshot на GitLab](https://gitlab.gnome.org/gnumdk/screenshot/-/issues). diff --git a/docs/desktop/gnome/valuta.de.md b/docs/desktop/gnome/valuta.de.md deleted file mode 100644 index 4e14bf67b4..0000000000 --- a/docs/desktop/gnome/valuta.de.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Valuta -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Einleitung - -Wenn Sie häufig reisen oder ins Ausland ziehen, vereinfachen Sie Ihre Finanzplanung mit Valuta. Diese Anwendung rechnet schnell zwei Währungen um. - -## Vorbedingungen - -Für diese Anleitung benötigen Sie Folgendes: - -- Rocky Linux -- Flatpak -- FlatHub - -## Installationsanweisungen - -![Screenshot of the Valuta page on Flathub with the blue install button highlighted in a red square](images/01_valuta.png) - -1. Gehen Sie zu [Flathub.org] (https://flathub.org), geben Sie `Valuta` in die Suchleiste ein und klicken Sie auf **Install** - - ![manual install script and run script](images/valuta-install.png) - -2. Kopieren Sie das manuelle Skript in Ihr Terminal: - - ```bash - flatpak install flathub io.github.idevecore.Valuta - ``` - -3. Führen Sie anschließend das manuelle Installationsskript in Ihrem Terminal aus: - - ```bash - flatpak run flathub io.github.idevecore.Valuta - ``` - -## Wie funktioniert es? - -Um `Valuta` zu verwenden, gehen Sie wie folgt vor: - -1. Wählen Sie im Dropdown-Menü Ihr Land aus und geben Sie den Betrag ein, den Sie ausgeben möchten. - - ![Screenshot of Valuta app showing 1000 USD in the input field, with a grey arrow pointing down to a grey box showing 1000 USD](images/02_valuta.png) - -2. Wählen Sie aus dem Dropdown-Menü das Land aus, in das Sie reisen. Der umgerechnete Betrag wird automatisch angezeigt. - -![Screenshot showing a grey arrow pointing upward to a green box displaying the converted amount, 899.52 EUR](images/03_valuta.png) - -## Zusammenfassung - -Ob für den Urlaub oder eine Geschäftsreise, `Valuta` vereinfacht den Währungsumtausch. Möchten Sie mehr erfahren oder Ideen zur Verbesserung teilen? [Ein Issue im Valuta-Repository bei GitHub einreichen](https://github.com/ideveCore/valuta/issues). diff --git a/docs/desktop/gnome/valuta.fr.md b/docs/desktop/gnome/valuta.fr.md deleted file mode 100644 index f6d14719f5..0000000000 --- a/docs/desktop/gnome/valuta.fr.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Valuta -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Introduction - -Si vous voyagez souvent ou déménagez à l’étranger, facilitez votre planification financière avec Valuta. Cette application convertit rapidement des devises entre deux pays. - -## Prérequis - -Ce guide suppose que vous disposez de la configuration suivante : - -- Rocky Linux -- Flatpak -- FlatHub - -## Processus d'Installation - -![Screenshot of the Valuta page on Flathub with the blue install button highlighted in a red square](images/01_valuta.png) - -1. Accédez à [Flathub.org](https://flathub.org), tapez `Valuta` dans la barre de recherche et cliquez sur **Install** - - ![manual install script and run script](images/valuta-install.png) - -2. Copiez le script d'installation manuelle dans un terminal : - - ```bash - flatpak install flathub io.github.idevecore.Valuta - ``` - -3. Enfin, exécutez le script d'installation manuelle dans votre terminal : - - ```bash - flatpak run flathub io.github.idevecore.Valuta - ``` - -## Mode d'emploi - -Pour utiliser le programme `Valuta`, procédez comme suit : - -1. Choisissez votre pays dans le menu déroulant et saisissez le montant en espèces que vous souhaitez dépenser. - - ![Screenshot of Valuta app showing 1000 USD in the input field, with a grey arrow pointing down to a grey box showing 1000 USD](images/02_valuta.png) - -2. Choisissez le pays vers lequel vous voyagez dans le menu déroulant. À partir de là, le montant converti apparaît automatiquement. - -![Screenshot showing a grey arrow pointing upward to a green box displaying the converted amount, 899.52 EUR](images/03_valuta.png) - -## Conclusion - -Que ce soit pour des vacances ou un voyage d'affaires, `Valuta` simplifie la conversion de devises. Vous souhaitez en savoir plus ou partager des idées pour l'améliorer ? [Soumettez un issue dans le dépôt de Valuta sur GitHub](https://github.com/ideveCore/valuta/issues). diff --git a/docs/desktop/gnome/valuta.it.md b/docs/desktop/gnome/valuta.it.md deleted file mode 100644 index c1e0427cc3..0000000000 --- a/docs/desktop/gnome/valuta.it.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Valuta -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Introduzione - -Se viaggiate o vi trasferite spesso all'estero, semplificate la vostra pianificazione finanziaria con Valuta. Questa applicazione converte rapidamente due valute. - -## Presupposti - -Questa guida presuppone che si disponga di quanto segue: - -- Rocky Linux -- Flatpak -- FlatHub - -## Processo di installazione - -![Screenshot of the Valuta page on Flathub with the blue install button highlighted in a red square](images/01_valuta.png) - -1. Andate su [Flathub.org](https://flathub.org), digitate "Valuta" nella barra di ricerca e cliccate su **Installa** - - ![manual install script and run script](images/valuta-install.png) - -2. Copiare lo script manuale nel terminale: - - ```bash - flatpak install flathub io.github.idevecore.Valuta - ``` - -3. Infine, lo script manuale nel terminale: - - ```bash - flatpak run flathub io.github.idevecore.Valuta - ``` - -## Come si usa - -Per utilizzare Valuta, procedere come segue: - -1. Scegliete il vostro Paese dal menu a tendina e digitate il denaro che volete spendere. - - ![Screenshot of Valuta app showing 1000 USD in the input field, with a grey arrow pointing down to a grey box showing 1000 USD](images/02_valuta.png) - -2. Selezionare il Paese in cui si viaggia dal menu a discesa. L'importo convertito apparirà automaticamente. - -![Screenshot showing a grey arrow pointing upward to a green box displaying the converted amount, 899.52 EUR](images/03_valuta.png) - -## Conclusione - -Che si tratti di una vacanza o di un viaggio di lavoro, Valuta semplifica la conversione di valuta. Volete saperne di più o condividere idee per migliorarlo? [Sottoporre un problema nel repository di Valuta su GitHub](https://github.com/ideveCore/valuta/issues). diff --git a/docs/desktop/gnome/valuta.md b/docs/desktop/gnome/valuta.md index 5ad546e3ed..7407abd795 100644 --- a/docs/desktop/gnome/valuta.md +++ b/docs/desktop/gnome/valuta.md @@ -1,53 +1,57 @@ --- -title: Valuta -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova +title: Currency Conversion with Valuta on GNOME +author: Wale Soyinka +contributors: +tags: + - gnome + - desktop + - currency + - flatpak --- -## Introduction +## Currency Conversion with Valuta on GNOME - If you often travel or move abroad, ease your financial planning with Valuta. This application quickly converts two currencies. +In an increasingly interconnected world, where digital transactions span continents and travel is but a flight away, the need for quick, reliable currency conversion is paramount. Whether you're a seasoned globetrotter, an astute online shopper, or a remote professional managing international finances, a dedicated currency converter is an indispensable tool. For users of the GNOME desktop environment, Valuta emerges as a prime example of elegant simplicity and focused functionality. -## Assumptions +Valuta is not merely a calculator; it's a thoughtfully designed application that integrates seamlessly into the GNOME ecosystem. It eschews unnecessary complexity, offering a straightforward, efficient user experience that gets the job done without fuss. Its minimalist interface and adherence to GNOME's design principles make it feel like a native extension of your desktop, providing instant access to up-to-date exchange rates. -This guide assumes you have the following: +## Installation: Bringing Valuta to Your GNOME Desktop -- Rocky Linux -- Flatpak -- FlatHub +Valuta is distributed as a Flatpak, a modern packaging format that ensures applications run consistently across various Linux distributions, offering sandboxing for enhanced security and providing access to the latest versions directly from developers. -## Installation process +To install Valuta, open your terminal and execute the following command: -![Screenshot of the Valuta page on Flathub with the blue install button highlighted in a red square](images/01_valuta.png) +```bash +flatpak install flathub io.github.ideveCore.Valuta +``` -1. Go to [Flathub.org](https://flathub.org), type "Valuta" in the search bar, and click **Install** +This command will fetch and install Valuta from Flathub, the universal Flatpak app store. Once the installation is complete, you can launch Valuta directly from your applications menu or by typing `flatpak run io.github.ideveCore.Valuta` in the terminal. - ![manual install script and run script](images/valuta-install.png) +## Using Valuta: Simplicity in Action -2. Copy the manual script in your terminal: +Valuta's strength lies in its intuitive design. The application focuses on a single, core task: converting one currency to another with minimal interaction. - ```bash - flatpak install flathub io.github.idevecore.Valuta - ``` +1. **Select Your Base Currency:** Upon launching Valuta, you'll typically see two currency fields. The top field represents your "base" currency. Click on the currency code (e.g., "USD") to open a search bar where you can type and select your desired currency from a comprehensive list. +2. **Enter the Amount:** In the input box next to your base currency, type the amount you wish to convert. As you type, Valuta will instantly display the converted value in the second currency field. +3. **Select Your Target Currency:** Similarly, click on the currency code in the bottom field to choose the currency you want to convert to. Valuta will immediately update the converted amount based on the latest exchange rates. -3. Finally, the manual script in your terminal: +The application automatically fetches and updates exchange rates from reliable sources like the European Central Bank (via Frankfurter) and Moeda.info, ensuring you always have accurate information at your fingertips. For even quicker conversions, Valuta integrates with the GNOME search provider, allowing you to perform conversions directly from the GNOME Activities overview (e.g., by typing "10 USD to EUR"). - ```bash - flatpak run flathub io.github.idevecore.Valuta - ``` +## Beyond GNOME: Alternatives on Other Platforms -## How to use +Valuta is a capable replacement for those apps for users coming from other platforms to a Rocky Linux desktop system. Here are a few notable currency converter applications on macOS and Windows 11 platforms that Valuta can at as a suitable substitute for : -To use Valuta, do the following: +### For macOS -1. Choose your country from the drop-down menu and type the cash you want to spend. +* **Converter (Currency Converter Calculator):** This application provides a familiar, calculator-like interface for quick and efficient currency conversions, often praised for its ease of use and integration with the macOS aesthetic. +* **XE Currency Converter:** A globally recognized name in currency exchange, XE offers a robust application with real-time rates, offline capabilities, and a user-friendly interface. It's a comprehensive tool for both casual and serious currency tracking. - ![Screenshot of Valuta app showing 1000 USD in the input field, with a grey arrow pointing down to a grey box showing 1000 USD](images/02_valuta.png) +### For Windows 11 -2. Select the country you are traveling to from the drop-down menu. The converted amount will automatically appear. - -![Screenshot showing a grey arrow pointing upward to a green box displaying the converted amount, 899.52 EUR](images/03_valuta.png) +* **Windows Calculator App:** The built-in Calculator application in Windows 11 includes a surprisingly capable currency converter. It supports over 100 currencies and can even perform conversions offline, making it a convenient default option. +* **Callista Currency Converter:** Available on the Microsoft Store, Callista provides up-to-the-minute exchange rates, supports a vast array of currencies, and often includes features like conversion history, all within a free and ad-free experience. +* **XE Currency Converter:** Just like on macOS, XE offers its powerful currency conversion tools to Windows users, complete with real-time rates, money transfer options, and rate alerts. ## Conclusion -Whether it is for a vacation or a business trip, Valuta simplifies currency conversion. Want to learn more or share ideas to improve it? [Submit an issue in Valuta's repository at GitHub](https://github.com/ideveCore/valuta/issues). +Valuta stands as a testament to the power of focused design within the GNOME ecosystem. It provides a fast, accurate, and aesthetically pleasing solution for currency conversion, seamlessly integrating into your desktop workflow. For those who appreciate efficiency and elegance in their tools, Valuta is an excellent choice, ensuring that managing international finances or planning your next adventure is always just a few clicks away. diff --git a/docs/desktop/gnome/valuta.uk.md b/docs/desktop/gnome/valuta.uk.md deleted file mode 100644 index 44abadab31..0000000000 --- a/docs/desktop/gnome/valuta.uk.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Valuta -author: Christine Belzie -contributors: Steven Spencer, Ganna Zhyrnova ---- - -## Вступ - -Якщо ви часто подорожуєте або переїжджаєте за кордон, спростіть своє фінансове планування з Valuta. Ця програма швидко конвертує валюти. - -## Припущення - -У цьому посібнику передбачається, що ви маєте наступне: - -- Rocky Linux -- Flatpak -- FlatHub - -## Процес встановлення - -![Screenshot of the Valuta page on Flathub with the blue install button highlighted in a red square](images/01_valuta.png) - -1. Перейдіть на [Flathub.org](https://flathub.org), введіть «Valuta» в рядку пошуку та натисніть **Install** - - ![manual install script and run script](images/valuta-install.png) - -2. Скопіюйте скрипт у свій термінал: - - ```bash - flatpak install flathub io.github.idevecore.Valuta - ``` - -3. Нарешті, скрипт у вашому терміналі: - - ```bash - flatpak run flathub io.github.idevecore.Valuta - ``` - -## Як використовувати - -Щоб використовувати Valuta, виконайте такі дії: - -1. Виберіть свою країну зі спадного меню та введіть суму готівки, яку хочете витратити. - - ![Screenshot of Valuta app showing 1000 USD in the input field, with a grey arrow pointing down to a grey box showing 1000 USD](images/02_valuta.png) - -2. Виберіть країну, до якої ви подорожуєте, зі спадного меню. Звідти автоматично з’являється конвертована сума. - -![Screenshot showing a grey arrow pointing upward to a green box displaying the converted amount, 899.52 EUR](images/03_valuta.png) - -## Висновок - -Незалежно від того, під час відпустки чи відрядження, Valuta спрощує конвертацію валюти. Хочете дізнатися більше або поділитися ідеями щодо його покращення? [Надішліть проблему в репозиторій Valuta на GitHub](https://github.com/ideveCore/valuta/issues). From f92d6c1676b4937d6114eb946374a5a54b2b0611 Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Tue, 7 Oct 2025 09:34:21 -0500 Subject: [PATCH 5/7] Fix a few issues in (#2934) * `valuta.md` duplicated level 1 and 2 header content. Change out contractions for words. * `decoder.md` fix numbered list formatting in second paragraph * `screenshot.md` remove duplicated 1 and 2 header content. Change the keyboard commands to markdown equivalents. Minor sentence simplification. --- docs/desktop/gnome/decoder.md | 15 +++++----- docs/desktop/gnome/screenshot.md | 50 +++++++++++++++----------------- docs/desktop/gnome/valuta.md | 22 +++++++------- 3 files changed, 42 insertions(+), 45 deletions(-) diff --git a/docs/desktop/gnome/decoder.md b/docs/desktop/gnome/decoder.md index 0152a8536d..3a25a9ed83 100644 --- a/docs/desktop/gnome/decoder.md +++ b/docs/desktop/gnome/decoder.md @@ -14,8 +14,9 @@ tags: **Decoder** is a simple and elegant utility for the GNOME desktop designed for a single purpose: working with QR codes. In a world where QR codes are used for everything from sharing Wi-Fi passwords to accessing restaurant menus, having a dedicated tool to handle them is essential. Decoder provides two primary functions in a clean, focused interface: -1. **Scanning:** Decode QR codes, either by using your computer's webcam or by selecting an image file. -2. **Generating:** Create your own QR codes from any text you provide. + +1. **Scanning:** Decode QR codes, either by using your computer's webcam or by selecting an image file. +2. **Generating:** Create your own QR codes from any text you provide. Its tight integration with the GNOME desktop makes it feel like a natural part of the operating system. @@ -51,8 +52,8 @@ After installation, you can launch Decoder from the GNOME Activities Overview. When you first open Decoder, it is ready to scan. You have two options: -* **Scan with Camera:** Click the camera icon in the top-left. A window will appear showing your webcam's feed. Simply point the webcam at a QR code to scan it in real-time. -* **Scan from Image:** Click the image icon in the top-right. This will open a file chooser, allowing you to select a saved image or screenshot that contains a QR code. +* **Scan with Camera:** Click the camera icon in the top-left. A window will appear showing your webcam's feed. Simply point the webcam at a QR code to scan it in real-time. +* **Scan from Image:** Click the image icon in the top-right. This will open a file chooser, allowing you to select a saved image or screenshot that contains a QR code. Once a code is scanned, Decoder intelligently parses its content. If the code contains a website URL, it will display the link with a button to open it in your default web browser. If it contains plain text, it will display the text with a convenient button to copy it to your clipboard. @@ -60,8 +61,8 @@ Once a code is scanned, Decoder intelligently parses its content. If the code co To create your own QR code, click the "Generate" button at the top of the Decoder window. -1. A text box will appear. Simply type or paste the text you wish to encode into this box. -2. As you type, a QR code representing your text is instantly generated on the right. -3. You can then click the **"Save as Image..."** button to save the QR code as a `.png` file, or click the **"Copy to Clipboard"** button to paste it into other applications. +1. A text box will appear. Simply type or paste the text you wish to encode into this box. +2. As you type, a QR code representing your text is instantly generated on the right. +3. You can then click the **"Save as Image..."** button to save the QR code as a `.png` file, or click the **"Copy to Clipboard"** button to paste it into other applications. Decoder is a perfect example of the GNOME design philosophy: a simple, beautiful, and highly effective tool that does one job exceptionally well. diff --git a/docs/desktop/gnome/screenshot.md b/docs/desktop/gnome/screenshot.md index cfaeb34a1a..3cfea20632 100644 --- a/docs/desktop/gnome/screenshot.md +++ b/docs/desktop/gnome/screenshot.md @@ -10,9 +10,7 @@ tags: - guide --- -## Taking Screenshots and Recording Screencasts in GNOME - -The modern GNOME desktop, featured in Rocky Linux, includes a powerful and seamlessly integrated tool for capturing your screen. This is not a separate application you need to install; it is a core part of the desktop shell, providing a fluid and efficient way to take screenshots and record short videos (screencasts). +The modern GNOME desktop, featured in Rocky Linux, includes a powerful and seamlessly integrated tool for capturing your screen. This is not a separate application you need to install, but a core part of the desktop shell, providing a fluid and efficient way to take screenshots and record short videos (screencasts). This guide covers how to use both the interactive user interface and the powerful keyboard shortcuts to capture your screen content. @@ -20,46 +18,46 @@ This guide covers how to use both the interactive user interface and the powerfu The easiest way to start is with the interactive overlay, which gives you full control over what and how you capture. -1. **Launch the Tool:** Press the `Print Screen` (often labeled `PrtSc`) key on your keyboard. The screen will dim, and the screenshot UI will appear. +1. **Launch the Tool:** Press the `Print Screen` (often labeled `PrtSc`) key on your keyboard. The screen will dim, and the screenshot UI will appear. -2. **Understand the Interface:** The control panel in the middle of the screen has three main sections: - * **Capture Mode:** On the left, you can choose to capture a rectangular `Region`, the entire `Screen`, or a specific `Window`. - * **Action Toggle:** In the center, you can switch between taking a **Screenshot** (camera icon) or recording a **Screencast** (video camera icon). - * **Capture Button:** The large, round button on the right initiates the capture. +2. **Understand the Interface:** The control panel in the middle of the screen has three main sections: + * **Capture Mode:** On the left, you can choose to capture a rectangular `Region`, the entire `Screen`, or a specific `Window`. + * **Action Toggle:** In the center, you can switch between taking a **Screenshot** (camera icon) or recording a **Screencast** (video camera icon). + * **Capture Button:** The large, round button on the right initiates the capture. ### Taking a Screenshot -1. Ensure the action toggle is set to **Screenshot** (the camera icon). -2. Select your capture mode: `Region`, `Screen`, or `Window`. -3. Click the round **Capture** button. +1. Ensure the action toggle is set to **Screenshot** (the camera icon). +2. Select your capture mode: `Region`, `Screen`, or `Window`. +3. Click the round **Capture** button. By default, the screenshot image is automatically saved to the `Pictures/Screenshots` directory in your home folder. ### Recording a Screencast -1. Set the action toggle to **Screencast** (the video camera icon). -2. Select the area you wish to record (`Region` or `Screen`). -3. Click the round **Capture** button to begin recording. +1. Set the action toggle to **Screencast** (the video camera icon). +2. Select the area you want to record (`Region` or `Screen`). +3. Click the round **Capture** button to begin recording. -A red dot (●) will appear in the top-right corner of your screen, along with a timer, indicating that recording is active. To stop, simply click this red dot. The video will be automatically saved as a `.webm` file in the `Videos/Screencasts` directory in your home folder. +A red dot will appear in the top-right corner of your screen, along with a timer, indicating that recording is active. To stop, simply click this red dot. The video will be automatically saved as a `.webm` file in the `Videos/Screencasts` directory in your home folder. ## Keyboard Shortcuts for Power Users For even faster captures, GNOME provides a set of direct keyboard shortcuts that bypass the interactive UI. -| Shortcut | Action | -| :--- | :--- | -| `Print Screen` | Open the interactive screenshot UI. | -| `Alt + Print Screen` | Take a screenshot of the currently active window immediately. | -| `Shift + Print Screen` | Immediately start selecting a rectangular area for a screenshot. | -| `Ctrl + Alt + Shift + R` | Start and stop a recording of the entire screen. | +| Shortcut | Action | +|------------------------|------------------------------------------------------------------| +| ++print-screen++ | Open the interactive screenshot UI. | +| ++alt+print-screen++ | Take a screenshot of the currently active window immediately. | +| ++shift+print-screen++ | Immediately start selecting a rectangular area for a screenshot. | +| ++ctrl+alt+shift+"R"++ | Start and stop a recording of the entire screen. | ### The "Copy to Clipboard" Modifier -This is a powerful productivity feature. By adding the `Ctrl` key to any of the screenshot shortcuts, the captured image will be copied directly to your clipboard instead of being saved to a file. This is perfect for quickly pasting a screenshot into another application like a document or chat window. +This is a powerful productivity feature. By adding the ++ctrl++ key to any of the screenshot shortcuts, the captured image will copy directly to your clipboard instead of saving to a file. This is perfect for quickly pasting a screenshot into another application such as a document or chat window. -* **`Ctrl + Print Screen`**: Open the interactive UI, but the capture will go to the clipboard. -* **`Ctrl + Alt + Print Screen`**: Copy a screenshot of the active window to the clipboard. -* **`Ctrl + Shift + Print Screen`**: Copy a screenshot of a selected area to the clipboard. +* ++ctrl+print-screen++ : Open the interactive UI, but the capture will go to the clipboard. +* ++ctrl+alt+print-screen++ : Copy a screenshot of the active window to the clipboard. +* ++ctrl+shift+print-screen++ : Copy a screenshot of a selected area to the clipboard. -The built-in GNOME screenshot and screencast tool is a perfect example of elegant and efficient design, providing both a simple, discoverable interface for new users and a fast, shortcut-driven workflow for power users. +The built-in GNOME screenshot and screencast tool is a perfect example of elegant and efficient design, providing both a simple, discoverable interface for new users, and a fast, shortcut-driven workflow for power users. diff --git a/docs/desktop/gnome/valuta.md b/docs/desktop/gnome/valuta.md index 7407abd795..06e8bb95d0 100644 --- a/docs/desktop/gnome/valuta.md +++ b/docs/desktop/gnome/valuta.md @@ -9,8 +9,6 @@ tags: - flatpak --- -## Currency Conversion with Valuta on GNOME - In an increasingly interconnected world, where digital transactions span continents and travel is but a flight away, the need for quick, reliable currency conversion is paramount. Whether you're a seasoned globetrotter, an astute online shopper, or a remote professional managing international finances, a dedicated currency converter is an indispensable tool. For users of the GNOME desktop environment, Valuta emerges as a prime example of elegant simplicity and focused functionality. Valuta is not merely a calculator; it's a thoughtfully designed application that integrates seamlessly into the GNOME ecosystem. It eschews unnecessary complexity, offering a straightforward, efficient user experience that gets the job done without fuss. Its minimalist interface and adherence to GNOME's design principles make it feel like a native extension of your desktop, providing instant access to up-to-date exchange rates. @@ -19,7 +17,7 @@ Valuta is not merely a calculator; it's a thoughtfully designed application that Valuta is distributed as a Flatpak, a modern packaging format that ensures applications run consistently across various Linux distributions, offering sandboxing for enhanced security and providing access to the latest versions directly from developers. -To install Valuta, open your terminal and execute the following command: +To install Valuta, open your terminal and run the following command: ```bash flatpak install flathub io.github.ideveCore.Valuta @@ -31,11 +29,11 @@ This command will fetch and install Valuta from Flathub, the universal Flatpak a Valuta's strength lies in its intuitive design. The application focuses on a single, core task: converting one currency to another with minimal interaction. -1. **Select Your Base Currency:** Upon launching Valuta, you'll typically see two currency fields. The top field represents your "base" currency. Click on the currency code (e.g., "USD") to open a search bar where you can type and select your desired currency from a comprehensive list. -2. **Enter the Amount:** In the input box next to your base currency, type the amount you wish to convert. As you type, Valuta will instantly display the converted value in the second currency field. -3. **Select Your Target Currency:** Similarly, click on the currency code in the bottom field to choose the currency you want to convert to. Valuta will immediately update the converted amount based on the latest exchange rates. +1. **Select Your Base Currency:** Upon launching Valuta, you will typically see two currency fields. The top field represents your "base" currency. Click the currency code (e.g., "USD") to open a search bar where you can type and select your desired currency from a comprehensive list. +2. **Enter the Amount:** In the input box next to your base currency, type the amount you wish to convert. As you type, Valuta will instantly display the converted value in the second currency field. +3. **Select Your Target Currency:** Similarly, click on the currency code in the bottom field to choose the currency you want to convert to. Valuta will immediately update the converted amount based on the latest exchange rates. -The application automatically fetches and updates exchange rates from reliable sources like the European Central Bank (via Frankfurter) and Moeda.info, ensuring you always have accurate information at your fingertips. For even quicker conversions, Valuta integrates with the GNOME search provider, allowing you to perform conversions directly from the GNOME Activities overview (e.g., by typing "10 USD to EUR"). +The application automatically fetches and updates exchange rates from reliable sources such as the European Central Bank (via Frankfurter) and Moeda.info, ensuring you always have accurate information at your fingertips. For even quicker conversions, Valuta integrates with the GNOME search provider, allowing you to perform conversions directly from the GNOME Activities overview (e.g., by typing "10 USD to EUR"). ## Beyond GNOME: Alternatives on Other Platforms @@ -43,14 +41,14 @@ Valuta is a capable replacement for those apps for users coming from other platf ### For macOS -* **Converter (Currency Converter Calculator):** This application provides a familiar, calculator-like interface for quick and efficient currency conversions, often praised for its ease of use and integration with the macOS aesthetic. -* **XE Currency Converter:** A globally recognized name in currency exchange, XE offers a robust application with real-time rates, offline capabilities, and a user-friendly interface. It's a comprehensive tool for both casual and serious currency tracking. +* **Converter (Currency Converter Calculator):** This application provides a familiar, calculator-like interface for quick and efficient currency conversions, often praised for its ease of use and integration with the macOS aesthetic. +* **XE Currency Converter:** A globally recognized name in currency exchange, XE offers a robust application with real-time rates, offline capabilities, and a user-friendly interface. It is a comprehensive tool for both casual and serious currency tracking. ### For Windows 11 -* **Windows Calculator App:** The built-in Calculator application in Windows 11 includes a surprisingly capable currency converter. It supports over 100 currencies and can even perform conversions offline, making it a convenient default option. -* **Callista Currency Converter:** Available on the Microsoft Store, Callista provides up-to-the-minute exchange rates, supports a vast array of currencies, and often includes features like conversion history, all within a free and ad-free experience. -* **XE Currency Converter:** Just like on macOS, XE offers its powerful currency conversion tools to Windows users, complete with real-time rates, money transfer options, and rate alerts. +* **Windows Calculator App:** The built-in Calculator application in Windows 11 includes a surprisingly capable currency converter. It supports over 100 currencies and can even perform conversions offline, making it a convenient default option. +* **Callista Currency Converter:** Available on the Microsoft Store, Callista provides up-to-the-minute exchange rates, supports a vast array of currencies, and often includes features such as conversion history, all within a free and ad-free experience. +* **XE Currency Converter:** Just like on macOS, XE offers its powerful currency conversion tools to Windows users, complete with real-time rates, money transfer options, and rate alerts. ## Conclusion From 498fb0d070d465c7e4576ec265da1339c135bea0 Mon Sep 17 00:00:00 2001 From: wale soyinka Date: Tue, 7 Oct 2025 10:39:23 -0400 Subject: [PATCH 6/7] Switch back to updated Docker repo for RHEL/EL 10. Thanks @kimiroo. (#2932) --- docs/gemstones/containers/docker.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/gemstones/containers/docker.md b/docs/gemstones/containers/docker.md index fb955bf4ac..ffe6b35963 100644 --- a/docs/gemstones/containers/docker.md +++ b/docs/gemstones/containers/docker.md @@ -13,14 +13,10 @@ The Docker Engine can run native Docker-style container workloads on Rocky Linux ## Add the Docker repository -!!! Note - - Docker v28 does not currently have a RHEL 10 repository, therefore we will use the CentOS repository. - Use the `dnf` utility to add the Docker repository to your Rocky Linux server. Type: ```bash -sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo +sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo ``` ## Install the needed packages From 774e62026b398a69a2ba4b2ed8a6f9875ec137f4 Mon Sep 17 00:00:00 2001 From: wsoyinka Date: Tue, 7 Oct 2025 14:13:46 -0400 Subject: [PATCH 7/7] Address @sspencerwire PR feedback for cloud-init guide --- .../virtualization/cloud-init/01_fundamentals.md | 12 ++++++------ .../virtualization/cloud-init/02_first_contact.md | 7 ++++--- .../cloud-init/03_configuration_engine.md | 11 +++++++---- .../cloud-init/04_advanced_provisioning.md | 4 ++-- .../cloud-init/05_image_builders_perspective.md | 6 +++--- .../virtualization/cloud-init/06_troubleshooting.md | 8 ++++---- .../virtualization/cloud-init/07_contributing.md | 6 +++--- 7 files changed, 29 insertions(+), 25 deletions(-) diff --git a/docs/guides/virtualization/cloud-init/01_fundamentals.md b/docs/guides/virtualization/cloud-init/01_fundamentals.md index bf4bb93e08..56543008a5 100644 --- a/docs/guides/virtualization/cloud-init/01_fundamentals.md +++ b/docs/guides/virtualization/cloud-init/01_fundamentals.md @@ -9,13 +9,13 @@ tags: --- -# **I. cloud-init Fundamentals: The Architecture of First Boot** +## Introduction This guide explores `cloud-init`, the essential tool for automating the initial setup of your Rocky Linux 10 cloud instances. When we talk about deploying servers in the cloud—or even in your local virtualization lab—we often take for granted the almost instantaneous transition from a blank image to a fully functional, network-ready machine. This feat of digital alchemy is performed by a single, tireless utility: cloud-init. -## **1. The Bootstrapping Conundrum** +## 1. The Bootstrapping Conundrum -### **The Problem: When a Server Wakes Up Blind** +### The Problem: When a Server Wakes Up Blind Imagine a generic Rocky Linux 10 QCOW2 image. It’s a perfect, pristine copy, unaware of its final destination. It doesn’t know its hostname, which user account should have SSH access, what timezone it’s in, or if it needs Apache or NGINX. @@ -23,13 +23,13 @@ If you were deploying physical hardware, a system administrator would manually c This is the problem **cloud-init** solves. -### **What is cloud-init?** +### What is cloud-init? Simply put, cloud-init is the industry-standard multi-distribution package that handles early initialization of cloud instances. It is the core service responsible for taking a generic image (like the one we’re using) and performing the required configuration tasks to transform it into a unique, production-ready server. It literally sits at the heart of the provisioning process, interpreting **metadata** and **user-defined instructions** to set up the system. Without it, your cloud instance is just a beautifully compiled Linux kernel with an identity crisis. -### **The cloud-init Ecosystem** +### The cloud-init Ecosystem cloud-init is a consumer, not a creator. It relies on the underlying cloud platform (AWS, Azure, GCP, OpenStack, or local tools like libvirt) to provide it with configuration information. @@ -86,4 +86,4 @@ Understanding this lifecycle is crucial for debugging and knowing precisely when ## What's Next? -Now that you understand the fundamental architecture of `cloud-init`—the "what" and "why," the different data types, and the boot stages—you are ready to move from theory to practice. The next chapter will guide you through your first hands-on exercise: booting the Rocky Linux 10 cloud image and performing a simple, real-world customization. \ No newline at end of file +Now that you understand the fundamental architecture of `cloud-init`—the "what" and "why," the different data types, and the boot stages—you are ready to move from theory to practice. The next chapter will guide you through your first hands-on exercise: booting the Rocky Linux 10 cloud image and performing a simple, real-world customization. diff --git a/docs/guides/virtualization/cloud-init/02_first_contact.md b/docs/guides/virtualization/cloud-init/02_first_contact.md index 61fef7e629..e1a2d69431 100644 --- a/docs/guides/virtualization/cloud-init/02_first_contact.md +++ b/docs/guides/virtualization/cloud-init/02_first_contact.md @@ -9,15 +9,15 @@ tags: --- -# **II. First Contact: Simple Bootstrapping with the Rocky Linux 10 QCOW2 Image** +## Simple Bootstrapping with the Rocky Linux 10 QCOW2 Image In the previous chapter, we covered the fundamental concepts of `cloud-init`. Now, it’s time to move from theory to practice. This chapter is your first hands-on mission: you will take the official Rocky Linux 10 Generic Cloud image, provide it with a simple set of instructions, and watch it configure itself on first boot. -## **1. Prepping the Lab Environment** +## 1. Prepping the Lab Environment Before we can boot our first instance, we need to prepare our local lab environment. For these exercises, we will simulate a cloud environment using standard Linux virtualization tools. -### **Prerequisites: Host Tools** +### Prerequisites: Host Tools Ensure you have the following tools installed on your host machine. On a Rocky Linux host, you can install them with `dnf`: @@ -45,6 +45,7 @@ cp Rocky-10-GenericCloud.qcow2 first-boot-vm.qcow2 ``` !!! tip "Save Disk Space with Backing Files" + A full copy of the image can be large. To save disk space, you can create a *linked clone* that uses the original image as a backing file. This creates a much smaller `qcow2` file that only stores the differences from the original. ```bash diff --git a/docs/guides/virtualization/cloud-init/03_configuration_engine.md b/docs/guides/virtualization/cloud-init/03_configuration_engine.md index b1ddea183d..2dd7f3c89c 100644 --- a/docs/guides/virtualization/cloud-init/03_configuration_engine.md +++ b/docs/guides/virtualization/cloud-init/03_configuration_engine.md @@ -5,19 +5,19 @@ contributors: tags: - cloud-init - rocky linux - - cloud + - cloud-init modules - automation --- -# **III. The Configuration Engine: Deep Dive into cloud-init Modules** +## Deep Dive into cloud-init Modules In the last chapter, you successfully booted a cloud image and performed a simple customization. While effective, the true power, portability, and idempotency of `cloud-init` are unlocked through its module system. These modules are the specialized tools in the `cloud-init` toolkit, designed to handle specific configuration tasks in a declarative and predictable way. This chapter dives deep into the module system, explaining what modules are, how they work, and how to use the most essential ones to build a well-configured server. -## **1. The Anatomy of Configuration** +## 1. The Anatomy of Configuration -### **What are cloud-init Modules?** +### What are cloud-init Modules? A `cloud-init` module is a specialized Python script designed to handle a single, discrete provisioning task. Think of them as plugins for tasks like managing users, installing packages, or writing files. @@ -50,6 +50,7 @@ System Boot The order is critical. For example, the `users-groups` module runs before `runcmd`, ensuring a script can be run by a user who was just created in the same configuration. !!! tip "Customizing `cloud-init` Behavior" + While `/etc/cloud/cloud.cfg` defines the default behavior, you should never edit it directly. For persistent, system-wide customizations, place your own `.cfg` files in the `/etc/cloud/cloud.cfg.d/` directory. This is the standard practice for building custom images, which we will explore in a later chapter. ## **2. High-Utility Modules: The Daily Drivers** @@ -132,6 +133,7 @@ In this example, we will ensure two useful tools, `nginx` (a high-performance we 3. **Boot and Verify:** After booting, SSH in and check that `nginx` is installed with `rpm -q nginx`. !!! note "Idempotency in Action" + If you were to reboot this VM with the same `user-data`, the `packages` module would see that `nginx` and `htop` are already installed and do nothing further. It ensures the desired state (packages are present) without taking unnecessary action. That is idempotency. ### **Module Deep Dive: `write_files`** @@ -164,6 +166,7 @@ To demonstrate its power, we will use `write_files` to create a custom homepage 3. **Boot and Verify:** After booting, SSH in and use `curl localhost` to see the new homepage. !!! tip "Writing Binary Files" + The `write_files` module is not limited to text. By specifying an `encoding`, you can deploy binary files. For example, you can use `encoding: b64` to write base64-encoded data. For advanced use cases, refer to the [official `write_files` documentation](https://cloudinit.readthedocs.io/en/latest/topics/modules.html#write-files). ## **What's Next?** diff --git a/docs/guides/virtualization/cloud-init/04_advanced_provisioning.md b/docs/guides/virtualization/cloud-init/04_advanced_provisioning.md index 6ea2672ec1..793db0e770 100644 --- a/docs/guides/virtualization/cloud-init/04_advanced_provisioning.md +++ b/docs/guides/virtualization/cloud-init/04_advanced_provisioning.md @@ -10,7 +10,7 @@ tags: - networking --- -# **IV. Advanced Provisioning: Networking and Multi-Part Payloads** +## Networking and Multi-Part Payloads In the previous chapter, you mastered the core `cloud-init` modules for managing users, packages, and files. You can now build a well-configured server declaratively. Now, it's time to explore more advanced techniques that give you even greater control over your instance's configuration. @@ -19,7 +19,7 @@ This chapter covers two powerful, advanced topics: 1. **Declarative Network Configuration:** How to move beyond DHCP and define static network configurations for your instances. 2. **Multi-Part MIME Payloads:** How to combine different types of user-data, like shell scripts and `#cloud-config` files, into a single, powerful payload. -## **1. Declarative Network Configuration** +## 1. Declarative Network Configuration By default, most cloud images are configured to acquire an IP address via DHCP. While convenient, many production environments require servers to have predictable, static IP addresses. The `cloud-init` network configuration system provides a platform-agnostic, declarative way to manage this. diff --git a/docs/guides/virtualization/cloud-init/05_image_builders_perspective.md b/docs/guides/virtualization/cloud-init/05_image_builders_perspective.md index 2b7157a437..e22438cb82 100644 --- a/docs/guides/virtualization/cloud-init/05_image_builders_perspective.md +++ b/docs/guides/virtualization/cloud-init/05_image_builders_perspective.md @@ -10,7 +10,7 @@ tags: - image-building --- -# **V. The Image Builder's Perspective: Defaults and Generalization** +## Defaults and Generalization So far, our journey has focused on configuring individual instances at boot time using `user-data`. In this chapter, we will shift our perspective to that of an **image builder**—someone who creates and maintains the "golden images" that serve as templates for other virtual machines. @@ -19,7 +19,7 @@ Our goal is to create a new, custom image with our own baked-in policies and def 1. **Customizing System-Wide Defaults:** Modifying the `cloud-init` configuration *within the image itself*. 2. **Generalizing the Image:** Using tools like `cloud-init clean` and `virt-sysprep` to strip all machine-specific data, preparing the image for cloning. -## **1. The Customization Lab Setup** +## 1. The Customization Lab Setup To begin, we need a running instance of the base cloud image that we can modify. We will boot this VM *without* providing any `user-data` to get a clean system. @@ -127,4 +127,4 @@ Let's test our new image by booting a new instance *from* it without any `user-d ## **What's Next?** -You have now learned how to create standardized templates by baking in defaults with `cloud-init`'s system-wide configuration and properly generalizing them for cloning. In the next chapter, we will cover the essential skill of troubleshooting when `cloud-init` doesn't behave as expected. \ No newline at end of file +You have now learned how to create standardized templates by baking in defaults with `cloud-init`'s system-wide configuration and properly generalizing them for cloning. In the next chapter, we will cover the essential skill of troubleshooting when `cloud-init` doesn't behave as expected. diff --git a/docs/guides/virtualization/cloud-init/06_troubleshooting.md b/docs/guides/virtualization/cloud-init/06_troubleshooting.md index 5297aefdb1..2593fdcbe3 100644 --- a/docs/guides/virtualization/cloud-init/06_troubleshooting.md +++ b/docs/guides/virtualization/cloud-init/06_troubleshooting.md @@ -10,15 +10,15 @@ tags: - troubleshooting --- -# **VI. Troubleshooting cloud-init** +## Troubleshooting cloud-init In any complex, automated system, things will eventually go wrong. When a `cloud-init` configuration fails, knowing how to systematically diagnose the problem is an essential skill. This chapter is your guide to `cloud-init` forensics, covering both in-guest and on-host troubleshooting techniques. -## **1. In-Guest Troubleshooting Toolkit** +## 1. In-Guest Troubleshooting Toolkit When you can access a running instance, `cloud-init` provides several commands and logs to show you what happened. -### **Pillar 1: The Status Command (`cloud-init status`)** +### Pillar 1: The Status Command (`cloud-init status`) This is your first port of call. It provides a high-level summary of `cloud-init`'s state. @@ -102,4 +102,4 @@ If networking fails to come up, modules like `packages` will fail. Check your ne ## **What's Next?** -You are now equipped with a powerful set of tools for both in-guest and on-host troubleshooting. In the final chapter, we will look at the `cloud-init` project itself, preparing you to explore its source code and contribute back to the community. \ No newline at end of file +You are now equipped with a powerful set of tools for both in-guest and on-host troubleshooting. In the final chapter, we will look at the `cloud-init` project itself, preparing you to explore its source code and contribute back to the community. diff --git a/docs/guides/virtualization/cloud-init/07_contributing.md b/docs/guides/virtualization/cloud-init/07_contributing.md index 41b9b5e8fb..4e6613e616 100644 --- a/docs/guides/virtualization/cloud-init/07_contributing.md +++ b/docs/guides/virtualization/cloud-init/07_contributing.md @@ -9,17 +9,17 @@ tags: - python --- -# **VII. Beyond Consumption: Contributing to cloud-init** +## Contributing to cloud-init project Congratulations! You have journeyed from the fundamental concepts of `cloud-init` to advanced provisioning and troubleshooting techniques. You are now a `cloud-init` power user. This final chapter opens the door to the next step in your journey: moving from a consumer of `cloud-init` to a potential contributor. `cloud-init` is a critical open-source project that thrives on community contributions. Whether it's fixing a typo in the documentation, reporting a bug, or writing a brand-new module, every contribution helps. This chapter provides a high-level map for understanding the source code, building a custom module, and engaging with the upstream community. It is not an exhaustive developer guide, but rather a friendly introduction to getting involved. -## **1. The `cloud-init` Source Code Landscape** +## 1. The `cloud-init` Source Code Landscape Before you can contribute, you need to know your way around the project. Let's explore the source code and set up a basic development environment. -### **The Language and Repository** +### The Language and Repository `cloud-init` is written almost entirely in **Python**. Its canonical source code repository is hosted on **Launchpad**, but for easier collaboration and a more familiar interface, most contributors interact with its official mirror on **GitHub**.