├── project ├── docs │ ├── image │ │ ├── Shortcuts.png │ │ ├── yast_eula.png │ │ ├── geeko-color.png │ │ ├── yast_firewall.png │ │ ├── yast_grub_menu.png │ │ ├── yast_kdeconnect.png │ │ ├── yast_repos_list.png │ │ ├── Button-monochrome.png │ │ ├── Shortcuts_Custom.png │ │ ├── yast_system_role.png │ │ ├── Button-filled-colour.png │ │ ├── Shortcuts_Spectacle.png │ │ ├── Sticker-Logo-white.png │ │ ├── snapper_post_zypper.png │ │ ├── yast_network_address.png │ │ ├── CustomShortcuts_AddNew.png │ │ ├── snapper_boot_selection.png │ │ ├── yast_add_online_repos.png │ │ ├── yast_network_settings.png │ │ ├── yast_wireless_specific.png │ │ ├── CustomShortcuts_Command.png │ │ ├── CustomShortcuts_NameNew.png │ │ ├── CustomShortcuts_Trigger.png │ │ ├── Shortcuts_ChooseApplication.png │ │ ├── snapper_snapshot_selection.png │ │ ├── yast_suggested_partitioning.png │ │ ├── CustomShortcuts_Demonstration.png │ │ ├── image_choice_fiw_conf_prompt.png │ │ └── geeko-color.svg │ ├── pipewire.md │ ├── todo.md │ ├── zstd.md │ ├── reference_docs.md │ ├── bluetooth.md │ ├── install_proprietary.md │ ├── codecs.md │ ├── power.md │ ├── index.md │ ├── kdeconnect.md │ ├── hybrid_graphics.md │ ├── kde.md │ ├── updating_upgrading.md │ ├── best_of_post.md │ ├── markdown.md │ ├── image_choice.md │ ├── microos_getting_started.md │ ├── pick_an_image.md │ ├── snapper.md │ ├── alternative_procurement.md │ └── yast_installer.md ├── overrides │ ├── styles.css │ ├── partials │ │ └── footer.html │ └── .icons │ │ └── button-filled-monochrome.svg └── mkdocs.yml ├── .pypspelling.yml ├── pyproject.toml ├── wikis_top5.md ├── .github └── workflows │ └── build-deploy.yml ├── requirements.txt ├── README.md ├── .gitignore ├── dictionary └── en-custom.txt ├── ToC.md ├── CONTRIBUTING.md └── LICENSE /project/docs/image/Shortcuts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/Shortcuts.png -------------------------------------------------------------------------------- /project/docs/image/yast_eula.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_eula.png -------------------------------------------------------------------------------- /project/docs/image/geeko-color.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/geeko-color.png -------------------------------------------------------------------------------- /project/docs/image/yast_firewall.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_firewall.png -------------------------------------------------------------------------------- /project/docs/image/yast_grub_menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_grub_menu.png -------------------------------------------------------------------------------- /project/docs/image/yast_kdeconnect.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_kdeconnect.png -------------------------------------------------------------------------------- /project/docs/image/yast_repos_list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_repos_list.png -------------------------------------------------------------------------------- /project/docs/image/Button-monochrome.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/Button-monochrome.png -------------------------------------------------------------------------------- /project/docs/image/Shortcuts_Custom.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/Shortcuts_Custom.png -------------------------------------------------------------------------------- /project/docs/image/yast_system_role.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_system_role.png -------------------------------------------------------------------------------- /project/overrides/styles.css: -------------------------------------------------------------------------------- 1 | p { 2 | text-align: justify; 3 | text-justify: inter-word; 4 | } 5 | .md-grid { 6 | max-width: initial; 7 | } -------------------------------------------------------------------------------- /project/docs/image/Button-filled-colour.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/Button-filled-colour.png -------------------------------------------------------------------------------- /project/docs/image/Shortcuts_Spectacle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/Shortcuts_Spectacle.png -------------------------------------------------------------------------------- /project/docs/image/Sticker-Logo-white.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/Sticker-Logo-white.png -------------------------------------------------------------------------------- /project/docs/image/snapper_post_zypper.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/snapper_post_zypper.png -------------------------------------------------------------------------------- /project/docs/image/yast_network_address.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_network_address.png -------------------------------------------------------------------------------- /project/docs/image/CustomShortcuts_AddNew.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/CustomShortcuts_AddNew.png -------------------------------------------------------------------------------- /project/docs/image/snapper_boot_selection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/snapper_boot_selection.png -------------------------------------------------------------------------------- /project/docs/image/yast_add_online_repos.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_add_online_repos.png -------------------------------------------------------------------------------- /project/docs/image/yast_network_settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_network_settings.png -------------------------------------------------------------------------------- /project/docs/image/yast_wireless_specific.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_wireless_specific.png -------------------------------------------------------------------------------- /project/docs/image/CustomShortcuts_Command.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/CustomShortcuts_Command.png -------------------------------------------------------------------------------- /project/docs/image/CustomShortcuts_NameNew.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/CustomShortcuts_NameNew.png -------------------------------------------------------------------------------- /project/docs/image/CustomShortcuts_Trigger.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/CustomShortcuts_Trigger.png -------------------------------------------------------------------------------- /project/docs/image/Shortcuts_ChooseApplication.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/Shortcuts_ChooseApplication.png -------------------------------------------------------------------------------- /project/docs/image/snapper_snapshot_selection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/snapper_snapshot_selection.png -------------------------------------------------------------------------------- /project/docs/image/yast_suggested_partitioning.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/yast_suggested_partitioning.png -------------------------------------------------------------------------------- /project/docs/image/CustomShortcuts_Demonstration.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/CustomShortcuts_Demonstration.png -------------------------------------------------------------------------------- /project/docs/image/image_choice_fiw_conf_prompt.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/KaratekHD/openSUSE-docs-revamped-temp/dev/project/docs/image/image_choice_fiw_conf_prompt.png -------------------------------------------------------------------------------- /.pypspelling.yml: -------------------------------------------------------------------------------- 1 | matrix: 2 | - name: markdown 3 | aspell: 4 | lang: en 5 | d: en_US 6 | sources: 7 | - 'project/docs/*.md' 8 | default_encoding: utf-8 9 | dictionary: 10 | wordlists: 11 | - dictionary/en-custom.txt 12 | output: dictionary/build/markdown.dic 13 | pipeline: 14 | - pyspelling.filters.markdown: 15 | - pyspelling.filters.html: 16 | comments: false 17 | attributes: 18 | - title 19 | - alt 20 | ignores: 21 | - code 22 | - pre 23 | - pyspelling.filters.url: -------------------------------------------------------------------------------- /project/docs/pipewire.md: -------------------------------------------------------------------------------- 1 | ### What is pipewire? 2 | 3 | ### Installing 4 | Install the package: 5 | ``` 6 | sudo zypper in pipewire pipewire-pulseaudio 7 | ``` 8 | Then enable the pipwire audio socket: 9 | ``` 10 | systemctl --user enable --now pipewire.{service,socket} pipewire-pulse.{service,socket} 11 | ``` 12 | Finally reboot your system: 13 | ``` 14 | systemctl reboot 15 | ``` 16 | 17 | ### For KDE Plasma users 18 | After rebooting, enable pipewire service making pipewire available to Plasma: 19 | ``` 20 | systemctl --user enable --now pipewire-media-session.service 21 | ``` -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [tool.poetry] 2 | name = "opensuse-docs-revamped-temp" 3 | version = "0.3.1" 4 | description = "openSUSE documentation" 5 | authors = ["Onuralp SEZER "] 6 | 7 | [tool.poetry.dependencies] 8 | python = "^3.6" 9 | mkdocs = "^1.1.2" 10 | mkdocs-material = "^7.1.1" 11 | mkdocs-git-revision-date-plugin = "^0.3.1" 12 | mkdocs-versioning = "^0.4.0" 13 | mkdocs-pdf-export-plugin = "^0.5.8" 14 | 15 | 16 | [tool.poetry.dev-dependencies] 17 | pyspelling = "^2.7.2" 18 | 19 | [build-system] 20 | requires = ["poetry-core>=1.0.0"] 21 | build-backend = "poetry.core.masonry.api" 22 | -------------------------------------------------------------------------------- /wikis_top5.md: -------------------------------------------------------------------------------- 1 | # Rationale 2 | 3 | To comply with the newly added license, we are required to name the top 5 "principal" contributors to the wikis. If the top 5 (+ 1 for good measure) users with the most edits is a valid application of this notion, we have: 4 | ``` 5 | As per MariaDB [wiki_en]> select user_id, count(rev_user) as edits_count, user_name from revision, user where rev_user=user_id group by rev_user order by edits_count desc limit 20; 6 | +---------+---------------+ 7 | | edits_count | user_name | 8 | +---------+---------------+ 9 | | 4358 | Hennevogel | 10 | | 3286 | Rajko m | 11 | | 2444 | Jsmeix | 12 | | 2264 | Saigkill | 13 | | 2227 | Spyhawk | 14 | | 1824 | Ddemaio | 15 | +---------+---------------+ 16 | ``` 17 | -------------------------------------------------------------------------------- /project/docs/todo.md: -------------------------------------------------------------------------------- 1 | # Things to do 2 | 3 | !!! note 4 | This page is temporary for onboarding and will be removed in doc releases. 5 | 6 | ## Theme 7 | 8 | - [x] Fix logo color 9 | - [ ] Replace google fonts 10 | - [ ] Fix logo size and aspect ratio 11 | 12 | ## Current Articles 13 | 14 | - [ ] Complete links in: [Reference Documentation](reference_docs.md) 15 | 16 | ## New Articles 17 | 18 | - [ ] Leap or tumbleweed - distro_choice.md 19 | - [ ] Full, live or net install - media_choice.md 20 | - [ ] Desktop environment - desktop_choice.md 21 | - [ ] Full disk install or dual boot - full_or_dual_boot.md 22 | - [ ] Disk partitioning - disk_partition.md 23 | - [ ] Disk encryption - disk_encryption.md 24 | - [ ] Snapshots/Btrfs - btrfs.md 25 | - [ ] Distros for special uses - other_distros.md 26 | - [ ] Getting Help - help.md 27 | 28 | -------------------------------------------------------------------------------- /.github/workflows/build-deploy.yml: -------------------------------------------------------------------------------- 1 | name: Docs to gh-page 2 | 3 | on: 4 | push: 5 | branches: [master, dev] 6 | 7 | jobs: 8 | build: 9 | runs-on: ubuntu-latest 10 | strategy: 11 | matrix: 12 | python-version: [3.8] 13 | 14 | steps: 15 | - uses: actions/checkout@v2 16 | - name: Set up Python ${{ matrix.python-version }} 17 | uses: actions/setup-python@v2 18 | with: 19 | python-version: ${{ matrix.python-version }} 20 | - name: Install dependencies 21 | run: | 22 | python -m pip install --upgrade pip 23 | pip install -r requirements.txt 24 | - name: Build the docs 25 | working-directory: ./project 26 | run: mkdocs gh-deploy --force 27 | - name: Deploy to GitHub Pages 28 | uses: JamesIves/github-pages-deploy-action@3.7.1 29 | with: 30 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 31 | BRANCH: gh-pages 32 | FOLDER: ./project/site 33 | CLEAN: true -------------------------------------------------------------------------------- /project/docs/zstd.md: -------------------------------------------------------------------------------- 1 | ## Enable zstd compression 2 | First enable `zstd` compression on `/` (root) and `/home` by adding the corresponding parameters to `/etc/fstab`: 3 | 4 | ``` 5 | / btrfs compress=zstd:1 0 0 6 | /home btrfs subvol=/@/home,compress=zstd:1 0 0 7 | ``` 8 | 9 | This will apply `zstd` compression to all the files directly under the relevant directories. The files already present under these directories will not be touched, however. To retroactively compress them, use: 10 | 11 | `sudo btrfs filesystem defrag -czstd -rv / /home/` 12 | 13 | ## Costs & benefits 14 | Compression is about making your files take less space on your hard drive, but it requires extra computations when reading or writing. In other words it trades (very marginally increased) processor and RAM usage for less hard drive usage. The tradeoff is likely to benefit the most modern machines with solid state drives (_SSD_), which are likely to have less storage capacity than their desktop counterparts, while having comparable computational power. 15 | 16 | It should also be noticed that `zstd`compression can increase the lifespan of SSDs, as it may decrease reads over time. -------------------------------------------------------------------------------- /project/docs/reference_docs.md: -------------------------------------------------------------------------------- 1 | title: 2 | summary: Links to the official openSUSE guides. 3 | authors: 4 | contributors: 5 | date: 6 | 7 | # Reference Documentation 8 | 9 | Suse and openSUSE have authored a comprehensive set of reference documentation and guides suitable 10 | for corporate users and system administrators. 11 | 12 | !!! Todo 13 | Complete links, only a first line links are currently populated. [Source links](https://doc.opensuse.org/) 14 | 15 | Guide|Paginated HTML|Single HTML|PDF|EPUB 16 | ----|---|---|---|---- 17 | Startup Guide|[Paginated HTML](https://doc.opensuse.org/documentation/leap/startup/html/book-opensuse-startup/index.html)|[Single HTML](https://doc.opensuse.org/documentation/leap/startup/single-html/book-opensuse-startup/index.html)|[PDF](https://doc.opensuse.org/documentation/leap/startup/book-opensuse-startup_color_en.pdf)|[EPUB](https://doc.opensuse.org/documentation/leap/startup/book-opensuse-startup_en.epub) 18 | GNOME User Guide|[Paginated HTML]()|[Single HTML]()|[PDF]()|[EPUB]() 19 | Reference Guide|[Paginated HTML]()|[Single HTML]()|[PDF]()|[EPUB]() 20 | Security Guide|[Paginated HTML]()|[Single HTML]()|[PDF]()|[EPUB]() 21 | Tuning Guide|[Paginated HTML]()|[Single HTML]()|[PDF]()|[EPUB]() 22 | Virtualization Guide|[Paginated HTML]()|[Single HTML]()|[PDF]()|[EPUB]() 23 | AutoYaST Guide|[Paginated HTML]()|[Single HTML]()|[PDF]()|[EPUB]() 24 | Release Notes||[Single HTML]()|| 25 | 26 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | beautifulsoup4==4.9.3 2 | bracex==2.1.1; python_version >= '3.6' 3 | brotli==1.0.9 4 | cffi==1.14.6 5 | click==8.0.1; python_version >= '3.6' 6 | cssselect2==0.4.1; python_version >= '3.6' 7 | fonttools[woff]==4.26.2; python_version >= '3.6' 8 | ghp-import==2.0.1 9 | gitdb==4.0.7; python_version >= '3.4' 10 | gitpython==3.1.18; python_version >= '3.6' 11 | html5lib==1.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' 12 | importlib-metadata==4.6.4; python_version >= '3.6' 13 | jinja2==3.0.1; python_version >= '3.6' 14 | lxml==4.6.3; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4' 15 | markdown==3.3.4; python_version >= '3.6' 16 | markupsafe==2.0.1; python_version >= '3.6' 17 | mergedeep==1.3.4; python_version >= '3.6' 18 | mkdocs-git-revision-date-plugin==0.3.1 19 | mkdocs-material-extensions==1.0.1; python_version >= '3.5' 20 | mkdocs-material==7.2.4 21 | mkdocs-pdf-export-plugin==0.5.8 22 | mkdocs-versioning==0.4.0 23 | mkdocs==1.2.2 24 | packaging==21.0; python_version >= '3.6' 25 | pillow==8.3.1; python_version >= '3.6' 26 | pycparser==2.20; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' 27 | pydyf==0.0.3; python_version >= '3.6' 28 | pygments==2.9.0; python_version >= '3.5' 29 | pymdown-extensions==8.2; python_version >= '3.6' 30 | pyparsing==2.4.7; python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3' 31 | pyphen==0.11.0; python_version >= '3.6' 32 | pyspelling==2.7.3 33 | python-dateutil==2.8.2; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' 34 | pyyaml-env-tag==0.1; python_version >= '3.6' 35 | pyyaml==5.4.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5' 36 | six==1.16.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3' 37 | smmap==4.0.0; python_version >= '3.5' 38 | soupsieve==2.2.1; python_version >= '3.0' 39 | tinycss2==1.1.0; python_version >= '3.6' 40 | watchdog==2.1.3; python_version >= '3.6' 41 | wcmatch==8.2; python_version >= '3.6' 42 | weasyprint==53.0; python_version >= '3.6' 43 | webencodings==0.5.1 44 | zipp==3.5.0; python_version >= '3.6' 45 | zopfli==0.1.8 46 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Live demo 2 | Our latest build is live at https://opensuse.github.io/openSUSE-docs-revamped-temp/. 3 | 4 | ## /!\ Disclaimer 5 | This is the construction site for the upcoming Leap and Tumbleweed documentation. Please do not consider any of this as official documentation *for now*. Use instead: 6 | - Generic documentation based on Leap: https://doc.opensuse.org/ 7 | - Tumbleweed specific knowledge-base: https://en.opensuse.org/Portal:Tumbleweed 8 | 9 | ## About 10 | Take a look at the "About" section (right panel). You can also check [this](https://news.opensuse.org/2020/10/12/join-our-team-and-help-us-imporove-the-openSUSE-learning-experience/) out for context. If you wonder why we are doing this when there is already an official documentation along with wikis, the answer is two-fold: 11 | * wikis make it difficult to sort the outdated / unofficial stuff from the up-to-date / official stuff 12 | * the official docs is slightly outdated, provides too little recommendations or best-practice advices on top of technical facts, is tedious to navigate at times and does not cater for Tumbleweed users. 13 | 14 | We are therefore working with people from the official docs to move to a maintainer-centric model, which we believe will better serve the openSUSE community. 15 | 16 | ## Contributing 17 | 1. Check out on the table of contents below. 18 | 2. Refer to the instructions available [here](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/CONTRIBUTING.md). 19 | 20 | ## Roadmap & table of contents 21 | 1. _End of February 2021_: we finish acquiring and writing all the contents of the sections __Before installing__ and __Installing__ of the [table of contents](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/ToC.md). 22 | 2. _End of April_: in parallel of reviewing (1) for both contents and language, we split the workflow into two groups, one finishing the contents for subsections (8-11) while the other works on (6-7) and (12). 23 | 3. _May_: we shuffle teams while maintaining a two-team workflow, this time for subsections (13-18), to be divided up as suits the teams. 24 | 4. _Enf of June 2021_: we release version 1.0 here on GitPages. 25 | -------------------------------------------------------------------------------- /project/docs/bluetooth.md: -------------------------------------------------------------------------------- 1 | ## Pairing a Bluetooth device across different operating systems 2 | 3 | ### With Windows 10 (adapted from [StackExchange](https://unix.stackexchange.com/questions/255509/bluetooth-pairing-on-dual-boot-of-windows-linux-mint-ubuntu-stop-having-to-p)) 4 | 1. Pair all devices on Linux 5 | 2. Pair all devices on Windows 6 | 3. From Windows, go to _Device & Printers_ in _Control Panel_ and go to your Bluetooth device's properties. Then, in the _Bluetooth_ section, you can find the unique identifier. Copy it as you will need it. 7 | 4. Download __PsExec__ from [here](http://technet.microsoft.com/en-us/sysinternals/bb897553.aspx). 8 | 5. Unzip the zip you downloaded and open a _CMD_ window with elevated privileges. (Click the Start menu, search for cmd, then right-click the CMD and click __Run as Administrator__.) 9 | 6. `cd` into the folder where you unzipped your download. 10 | 7. Run `psexec -s -i regedit.exe` 11 | 8. Navigate to find the keys under `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\BTHPORT\Parameters\Keys`. If there is no _CurrentControlSet_, try _ControlSet001_. 12 | 9. You should see a few keys labels with the MAC addresses -- write down the MAC address associated with the unique identifier you copied before. 13 | 10. Go back to Linux (if not in Linux) and add your Windows key to your Linux config entries. Just note that the Bluetooth port's MAC address is formatted differently when moving from Windows to Linux - referenced as aa1122334455 in Windows in my example above. The Linux version will be in all caps and punctuated by ':' after every two characters - for example `AA:11:22:33:44:55`.  14 | 11. Switch to root: do `sudo -s` 15 | 12. `cd` to your Bluetooth config location at `/var/lib/bluetooth/[bth port MAC addresses]` 16 | 13. Here you'll find folders for each device you've paired with. The folder names being the Bluetooth devices' MAC addresses and contain a single file info. In these files, you'll see the link key you need to replace with your Windows ones, like so: 17 | ``` 18 | [LinkKey] 19 | Key=< NEW KEY, ex. B99999999FFFFFFFFF999999999FFFFF > 20 | ``` 21 | 14. Finally restart your bluetooth systemd service with `sudo systemctl restart bluetooth` 22 | -------------------------------------------------------------------------------- /project/docs/install_proprietary.md: -------------------------------------------------------------------------------- 1 | ## Nvidia proprietary drivers 2 | 3 | ### Determine which driver is required by your GPU 4 | 5 | 1. There are two Nvidia driver options available in the Nvidia repository - __nvidia-glG05__ and __nvidia-glG04__. 6 | 2. The __nvidia-glG05__ package corresponds with the Nvidia 460 series driver. 7 | 3. The __nvidia-glG04__ package corresponds with the Nvidia 390 series driver. 8 | 4. Please refer to the Nvidia [website](https://www.nvidia.com/en-us/drivers/unix/) to determine which driver best supports your GPU. 9 | 10 | ### Setup the driver 11 | 12 | #### With Yast 13 | 1. Go to _YAsT2_. 14 | 2. Then _Software Management_. 15 | 3. On the menu, click __Configuration__ > __Repositories__... (or do `Ctrl + R`). 16 | 4. Click __Add__ > __Community Repositories__. 17 | 5. Select __nVidia Graphics Drivers__ > __Accept__ > __Trust__. 18 | 6. On the _Configured Software Repositories_ > Click __Ok__ 19 | 7. Back to _Software Management Windows_" > __View__ > __Repositories__ > Select __nVidia Graphics Drivers__. 20 | 8. Select __x11-video-nvidiaG05__ > __Accept__ (Some graphic cards need _G04_, see the first section above) 21 | 9. After the installation of the nvidia drivers the user have to be added to the video group gpasswd -a $USER video or usermod -aG video $USER 22 | 10. Reboot. 23 | 24 | #### Using the command line 25 | 1. Add the Nvidia Repository. If using Tumbleweed for example, you would run `sudo zypper addrepo --refresh https://download.nvidia.com/opensuse/tumbleweed NVIDIA`. For Leap, you can run `sudo zypper addrepo --refresh 'https://download.nvidia.com/opensuse/leap/$releasever' NVIDIA`. 26 | 2. Install the appropriate driver by running `sudo zypper in x11-video-nvidiaG05` or `sudo zypper in x11-video-nvidiaG04` 27 | 3. After the installation of the nvidia drivers the user have to be added to the video group gpasswd -a $USER video or usermod -aG video $USER 28 | 4. Reboot. 29 | 30 | #### CUDA 31 | 1. CUDA can be installed with the __Nvidia-ComputeG05__ or __Nvidia-ComputeG04__ package. 32 | 2. See [Nvidia's documentation](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html) for further information. 33 | 34 | 35 | ### Hybrid Graphics/Optimus 36 | 1. See [Hybrid Graphics](hybrid_graphics.md) 37 | -------------------------------------------------------------------------------- /project/overrides/partials/footer.html: -------------------------------------------------------------------------------- 1 | {#- 2 | This file was automatically generated - do not edit 3 | -#} 4 | {% import "partials/language.html" as lang with context %} 5 | 57 | -------------------------------------------------------------------------------- /project/docs/codecs.md: -------------------------------------------------------------------------------- 1 | # Installing Codecs 2 | You need to play online or offline multimedia content but the content does not play or you receive errors. Usually this is a sign of missing codecs. Due to legal limitations proprietary codecs can't be stored and served directly from the __openSUSE__/__SUSE__ infrastructure. To install certain codec packages you will need to add the Packman repository and install the required software from there. Some commonly used and installed codecs are: 3 | 4 | - ffmpeg 5 | - gstreamer-plugins-good 6 | - gstreamer-plugins-bad 7 | - gstreamer-plugins-libav 8 | - gstreamer-plugins-ugly 9 | - libavcodec-full 10 | - vlc-codecs 11 | 12 | You can get them using `Zypper`, _OBS Package Installer_ (`opi`) or `YaST`. 13 | ## OBS Package Installer 14 | `opi` can be used to search and install software from the _Open Build Service_ (OBS) and it works on __openSUSE__ and __SUSE__. To install the required codecs: 15 | 1. Launch a _terminal emulator_ (_Konsole_, _Gnome Terminal_ etc.), 16 | 1. Install `opi`: `sudo zypper install opi` 17 | 1. Install codecs with `opi`: `opi codecs` 18 | 1. Update the system: `zypper dist-upgrade --from packman` 19 | 20 | ## The manual way 21 | ### Adding the Packman repository 22 | For installing codecs we have to add the Packman repository. Remember if things don’t work after installing the codecs, make sure all your multimedia packages are coming from Packman. 23 | 24 | #### Using the command line 25 | Use the following commands to add all of the third-party Packman repository (Packman Essentials is included), according to your installed openSUSE version: 26 | 27 | ##### Tumbleweed 28 | `sudo zypper addrepo -cfp 90 'https://ftp.gwdg.de/pub/linux/misc/packman/suse/openSUSE_Tumbleweed/' packman` 29 | 30 | ##### Leap 31 | `sudo zypper addrepo -cfp 90 'https://ftp.gwdg.de/pub/linux/misc/packman/suse/openSUSE_Leap_$releasever/' packman` 32 | 33 | #### Using YaST 34 | 1. Launch `YaST`, 35 | 1. Select _Software Repositories_, 36 | 1. Press _Add_ (lower left corner), 37 | 1. From the list select _Community repositories_ and press _Next_, 38 | 1. Select _Packman Repository_ and press _Ok_. 39 | 40 | ### Installing codecs 41 | #### Using the command line 42 | 1. Refresh your local repository: `sudo zypper ref`, 43 | 1. Install some generally needed codecs: `zypper install ffmpeg lame gstreamer-plugins-libav gstreamer-plugins-bad gstreamer-plugins-ugly gstreamer-plugins-good libavcodec-full vlc-codecs`, 44 | 1. Update everything to the latest Version `zypper dist-upgrade --from packman`. 45 | 46 | #### Using YaST 47 | 1. Launch `YaST`, 48 | 1. Select _Software Management_, 49 | 1. View > Repositories > Packman Repository, 50 | 1. Click "Switch system packages" to packages from Packman repository. 51 | 52 | Furthermore you can type in the _Search_ field the name of the codec packages you're looking for. 53 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | ### .gitignore files, directories and their patterns ### 2 | # List of temporary files generated by the OS or the editor that 3 | # GIT should ignore so as not to pollute the source code. 4 | # 5 | # Reference: 6 | # https://git-scm.com/docs/gitignore 7 | # https://gitignore.io 8 | # 9 | # 10 | 11 | ### mkdocs generated static pages ### 12 | # This folder contains the HTML files generated by mkdocs 13 | project/site/ 14 | Pipfile 15 | Pipfile.lock 16 | poetry.lock 17 | ### Editors temp files ### 18 | 19 | # Kate 20 | .*.kate-swp 21 | .swp.* 22 | 23 | #Vscode 24 | .vscode/ 25 | 26 | #idea 27 | .idea/ 28 | 29 | #python venv 30 | .venv 31 | venv 32 | # dictonary 33 | dictionary/build/markdown.dic 34 | 35 | # Vim 36 | [._]*.s[a-v][a-z] 37 | !*.svg # comment out if you don't need vector files 38 | [._]*.sw[a-p] 39 | [._]s[a-rt-v][a-z] 40 | [._]ss[a-gi-z] 41 | [._]sw[a-p] 42 | Session.vim 43 | Sessionx.vim 44 | .netrwhist 45 | *~ 46 | tags 47 | [._]*.un~ 48 | 49 | 50 | ### Compiled source ### 51 | *.com 52 | *.class 53 | *.dll 54 | *.exe 55 | *.o 56 | *.so 57 | *.cab 58 | *.msi 59 | *.msix 60 | *.msm 61 | *.msp 62 | 63 | 64 | ### Archives & Packages ### 65 | # it's better to unpack these files and commit the raw source 66 | # git has its own built in compression methods 67 | *.7z 68 | *.dmg 69 | *.gz 70 | *.iso 71 | *.jar 72 | *.rar 73 | *.tar 74 | *.zip 75 | 76 | 77 | ### Logs and databases ### 78 | *.log 79 | *.sql 80 | *.sqlite 81 | 82 | 83 | ### Linux ### 84 | *~ 85 | 86 | # temporary files which can be created if a process still has a handle open of a deleted file 87 | .fuse_hidden* 88 | 89 | # KDE directory preferences 90 | .directory 91 | 92 | # Linux trash folder which might appear on any partition or disk 93 | .Trash-* 94 | 95 | # .nfs files are created when an open file is removed but is still being accessed 96 | .nfs* 97 | 98 | 99 | ### macOS ### 100 | # General 101 | .DS_Store 102 | .DS_Store? 103 | .AppleDouble 104 | .LSOverride 105 | 106 | # Icon must end with two \r 107 | Icon 108 | 109 | # Thumbnails 110 | ._* 111 | 112 | # Files that might appear in the root of a volume 113 | .DocumentRevisions-V100 114 | .fseventsd 115 | .Spotlight-V100 116 | .TemporaryItems 117 | .Trashes 118 | .VolumeIcon.icns 119 | .com.apple.timemachine.donotpresent 120 | 121 | # Directories potentially created on remote AFP share 122 | .AppleDB 123 | .AppleDesktop 124 | Network Trash Folder 125 | Temporary Items 126 | .apdisk 127 | 128 | 129 | ### Windows ### 130 | # Windows thumbnail cache files 131 | Thumbs.db 132 | Thumbs.db:encryptable 133 | ehthumbs.db 134 | ehthumbs_vista.db 135 | 136 | # Dump file 137 | *.stackdump 138 | 139 | # Folder config file 140 | [Dd]esktop.ini 141 | 142 | # Recycle Bin used on file shares 143 | $RECYCLE.BIN/ 144 | 145 | # Windows shortcuts 146 | *.lnk 147 | 148 | -------------------------------------------------------------------------------- /dictionary/en-custom.txt: -------------------------------------------------------------------------------- 1 | 2 | Packman 3 | Ok 4 | ok 5 | 6 | 7 | software 8 | softwareA 9 | softwareB 10 | 11 | 12 | 13 | rpms 14 | RPM 15 | RPM's 16 | 17 | Wayland 18 | XWayland 19 | Krita 20 | DigiKam 21 | 22 | config 23 | xmlout 24 | distro 25 | gpg 26 | GPG 27 | Ignore 28 | reponame 29 | removerepo 30 | addrepo 31 | repo 32 | 33 | sudo 34 | cuda 35 | 36 | initrd 37 | chroot 38 | theming 39 | decrypt 40 | LVM 41 | partitioner 42 | 43 | ar 44 | vc 45 | 46 | codecs 47 | codec 48 | 49 | firefox 50 | ZYpp 51 | libzypp 52 | 53 | YaST 54 | yast 55 | AutoYaST 56 | 57 | CLI 58 | Pre 59 | filesystem 60 | pre 61 | zypp 62 | UUI 63 | GIDs 64 | UIDs 65 | UID 66 | GID 67 | NTP 68 | LVM 69 | LUKS 70 | UEFI 71 | EPUB 72 | 73 | XPS 74 | PSK 75 | SSID 76 | WPA 77 | dhcp 78 | hostname 79 | ip 80 | subnet 81 | ethernet 82 | conenction 83 | Netiso 84 | wifi 85 | WIFI 86 | 87 | Distros 88 | distros 89 | md 90 | 91 | GBs 92 | stsc 93 | systemctl 94 | flatpak 95 | flatpaks 96 | 97 | 98 | Konsole 99 | Console 100 | libavcodec 101 | vlc 102 | 103 | gstreamer 104 | libav 105 | ffmpeg 106 | 107 | 108 | TumbleWeed 109 | Github 110 | VLC 111 | flathub 112 | Libreoffice 113 | LibreOffice 114 | Snapd 115 | snapd 116 | AppArmor 117 | virtualbox 118 | systemd 119 | AppArmor 120 | WWAN 121 | 122 | BTRFS 123 | Btrfs 124 | btrfs 125 | subvolume 126 | snapper 127 | 128 | UserData 129 | Userdata 130 | 131 | subcommand 132 | bootloader 133 | backend 134 | 135 | zypper's 136 | zypper 137 | dup 138 | pchk 139 | lp 140 | 141 | 142 | promptids 143 | commandline 144 | commandLine 145 | uneeded 146 | deps 147 | nvidia 148 | URI 149 | ascii 150 | packagename 151 | snapshotting 152 | flavours 153 | 154 | FOSS 155 | Oss 156 | repos 157 | cd 158 | CD 159 | releasever 160 | updatable 161 | 162 | Matcha 163 | Akwa 164 | papirus 165 | gtk 166 | GTK 167 | KDE 168 | 169 | windows 170 | Windows 171 | Linux 172 | macOS 173 | Kubic 174 | MicroOS 175 | openSUSE 176 | openSUSE's 177 | SUSE 178 | 179 | 180 | 181 | behaviour 182 | specialise 183 | reidentify 184 | 185 | AppImages 186 | 187 | deduplication 188 | untrusted 189 | cryptographic 190 | cryptsetup 191 | untick 192 | 193 | informations 194 | information 195 | customizable 196 | misconfigured 197 | 198 | # Lorem Ipsum 199 | Duis 200 | Excepteur 201 | Lorem 202 | adipiscing 203 | aliqua 204 | aliquip 205 | amet 206 | anim 207 | aute 208 | cillum 209 | commodo 210 | consectetur 211 | consequat 212 | culpa 213 | cupidatat 214 | deserunt 215 | dolore 216 | eiusmod 217 | elit 218 | enim 219 | esse 220 | et 221 | eu 222 | exercitation 223 | fugiat 224 | incididunt 225 | ipsum 226 | irure 227 | labore 228 | laboris 229 | laborum 230 | magna 231 | mollit 232 | nisi 233 | nostrud 234 | nulla 235 | occaecat 236 | officia 237 | pariatur 238 | proident 239 | qui 240 | quis 241 | reprehenderit 242 | sed 243 | sint 244 | sunt 245 | tempor 246 | ullamco 247 | ut 248 | velit 249 | veniam 250 | voluptate 251 | # Lorem -------------------------------------------------------------------------------- /project/overrides/.icons/button-filled-monochrome.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | image/svg+xml 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | -------------------------------------------------------------------------------- /project/mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: openSUSE User Documentation Project 2 | repo_url: https://github.com/openSUSE/openSUSE-docs-revamped-temp 3 | edit_uri: "" 4 | 5 | plugins: 6 | - search: 7 | prebuild_index: true 8 | - git-revision-date 9 | - mkdocs-versioning: 10 | version: 0.3.1 11 | - pdf-export: 12 | verbose: true 13 | media_type: print 14 | #enable PDF printing by running "export ENABLE_PDF_EXPORT=1" 15 | enabled_if_env: ENABLE_PDF_EXPORT 16 | #comment out the next two options to make every page have its own PDF 17 | combined: true 18 | combined_output_path: docs.pdf 19 | theme: 20 | name: material 21 | font: 22 | code: Fira Code 23 | text: Noto Sans TC 24 | custom_dir: overrides 25 | palette: 26 | scheme: preference 27 | primary: green 28 | accent: red 29 | logo: image/Button-filled-colour.png 30 | favicon: image/geeko-color.png 31 | features: 32 | - navigation.sections 33 | - navigation.instant 34 | - navigation.tracking 35 | - navigation.expand 36 | # - navigation.tabs 37 | # - navigation.tabs.sticky 38 | icon: 39 | repo: fontawesome/brands/github 40 | 41 | extra: 42 | logo: image/geeko-color.png 43 | social: 44 | - icon: button-filled-monochrome 45 | link: https://www.opensuse.org 46 | name: openSUSE Main Website 47 | - icon: fontawesome/brands/github 48 | link: https://github.com/openSUSE 49 | name: openSUSE GitHub 50 | 51 | extra_css: 52 | - styles.css 53 | 54 | markdown_extensions: 55 | - admonition 56 | - def_list 57 | - pymdownx.details 58 | - pymdownx.superfences 59 | - toc: 60 | permalink: ⚓︎ 61 | toc_depth: 5 62 | 63 | nav: 64 | - Home: index.md 65 | - Version Selector: "../" 66 | - Before installing: 67 | - Choosing a distribution: pick_an_image.md 68 | - Preparing the installation media: image_choice.md 69 | - Installing: 70 | - Step by step guide: yast_installer.md 71 | - Quick install for experienced users: 72 | - microOS specials: microos_getting_started.md 73 | - Distro basics: 74 | - Post-installation best-of: best_of_post.md 75 | - KDE Plasma basics: kde.md 76 | - GNOME basics: "" 77 | - Interlude -- Fundamental openSUSE concepts: 78 | - Zypper: zypper.md 79 | - YaST2: "" 80 | - Updating, upgrading, snapshots best practices: updating_upgrading.md 81 | - Snapper and Btrfs: snapper.md 82 | - Additional software: 83 | - Software procurement: alternative_procurement.md 84 | - Building from source: "" 85 | - Troubleshooting with autonomy: "" 86 | - Completing and fine-tuning your setup: 87 | - Audio & Video: 88 | - Codecs: codecs.md 89 | - Pipewire: pipewire.md 90 | - Graphic Drivers: 91 | - Getting started: install_proprietary.md 92 | - Dual GPUs ("Optimus"): hybrid_graphics.md 93 | - Setting up a containerized environment: install_podman.md 94 | - Power management: power.md 95 | - Pairing, syncing, sharing: 96 | - Bluetooth: bluetooth.md 97 | - KDE Connect: kdeconnect.md 98 | - Advanced fine-tunings: 99 | - Transparent compression (zstd): zstd.md 100 | - Giving back to the community: 101 | - The art of reporting bugs: "" 102 | - Resources: "" 103 | - Other sources of documentation: reference_docs.md 104 | - Contribute to this docs: 105 | - Markdown flavour: markdown.md 106 | - Todo: todo.md 107 | - A contributor's checklist: "" -------------------------------------------------------------------------------- /project/docs/image/geeko-color.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | -------------------------------------------------------------------------------- /project/docs/power.md: -------------------------------------------------------------------------------- 1 | ## Power Management 2 | 3 | ### Power-saving methods 4 | On modern hardware Linux-based desktop environments favour a combination of the following methods for saving power: 5 | 6 | 1. monitor dimming 7 | 2. monitor suspension 8 | 3. session / system suspension to RAM (so-called _suspension_) 9 | 4. session / system suspension to disk (so-called _hibernation_) 10 | 11 | _Monitor dimming_ (1), _Monitor suspension_ (2) and _Session suspesion_ (3) should be easy to find: open your desktop environment's settings and search for `power management`. By contrast the last of these methods may require a few helpers. 12 | 13 | ### Suspension to disk (hibernation) 14 | 15 | An openSUSE operating system is ready for hibernation only when: 16 | 17 | (Swap exists) A swap space on the disk must exist (see below for details) 18 | (Swap referenced) The swap space must be referenced in `/etc/fstab`, the configuration file read on every boot and used to mount and integrate the different spaces listed on the file into a proper file structure 19 | (Resume referenced) The partition to which the user wants the hibernation to resume to must be made known to the kernel, usually as the value of a kernel parameter 20 | 21 | Swap space can be created while partioning the disk while installating or after installing. 22 | 23 | __During installation__ 24 | This is adapted from [the installation documentation](/yast_installer#about-partition-schemes) and repeated here for convenience. 25 | 26 | Step by step: Expert partitioning 27 | 28 | 1. From the _Disk_ view, select _Expert Partitioner_ 29 | 2. Click the __Add Partition__ button (bottom left-hand side) 30 | 3. Add a `swap` partition with a size equal to your current RAM + 1 GB. 31 | 32 | __After installing__ 33 | From _Yast2_: 34 | 35 | 1. Click on, or search and then open, the _Partitioner_ module. 36 | 2. Select __Disks__ from the list on your left-hand side, and take note of the identifier of the partition you will want to resume to. Note both the UUID and the `/dev/sda` identifiers. 37 | 3. Click on the __Create partition__ button. 38 | 3. Add a `swap` partition with a size equal to your current RAM + 1 GB, making sure to format it as `swap` 39 | 4. Confirm to apply the changes. 40 | 41 | No matter if you have followed the method before or By now Yast2 should have edited your `/etc/fstab` to reference the freshly created swap partition, which means that conditions (Swap exists) and (Swap referenced) above should be met. You can double check that this is the case with 42 | 43 | ``` 44 | $ blkid | grep "swap" 45 | ``` 46 | 47 | This command should return a line referencing various identifiers for your swap partition. You can compare the UUID visible from this context with the UUID lised in _Yast2_ for good measure (see. step 2 above). If you have created the swap space during installation, don't forget to search for the UUID and the `/dev/sda` identifiers referencing the partition to which you will want to resume to. 48 | 49 | Finally, to fulfill condition (Resume referenced), in _Yast2_: 50 | 51 | 1. Click on, or search and then open, the _Bootloader_ module. 52 | 2. Switch to the __Kernel Parameters__ tab. 53 | 3. In the first text-field, labelled _Optional Kernel Parameters_, simply add the following text: 54 | ``` 55 | resume=/dev/sda # replace '' by the number of the partition you want to resume to 56 | 57 | ``` 58 | or 59 | ``` 60 | resume=UUID= # replace '' with the UUID of the partition you want to resume to. 61 | ``` 62 | 63 | !!! warning 64 | It's preferable to use the UUID over any other identifier for referencing partitions as UUID identifiers are not ambiguous. However, should you recreate a resume or swap partition referenced via UUID, the reference will break and you will need to register it again where appropriate (kernel parameters if resume partition, `/etc/fstab` if swap space.) 65 | 66 | You can finally lay back and admire your configuration. On my machine it looks like this: 67 | 68 | ``` 69 | # kernel parameter 70 | `resume=UUID=19bd024f-76bd-4162-ac37-4d0d51e02c25` 71 | ``` 72 | and 73 | ``` 74 | # /etc/fstab 75 | UUID=e0bac415-cbde-4c9b-8178-7874ac9de70a swap defaults 0 0 76 | ``` 77 | -------------------------------------------------------------------------------- /project/docs/index.md: -------------------------------------------------------------------------------- 1 | !!! warning 2 | This is the construction site for the upcoming Leap and Tumbleweed documentation. Please do not consider any of this official documentation. For official documentation, see: 3 | 4 | * [Standard documentation based on Leap](https://doc.opensuse.org/) 5 | * [Tumbleweed-specific knowledgebase](https://en.opensuse.org/Portal:Tumbleweed) 6 | 7 | # Welcome 8 | Are you looking for **better** Linux documentation? You are in the right place. This is a young project that aims 9 | to provide a user friendly guide for quickly installing and setting up openSUSE with minimum fuss. 10 | 11 | ## For new users 12 | The documentation is laid out in a user friendly way. It caters to beginners and other people new to Linux, and helps you get running quickly. Installing Linux can seem daunting at first, because there are a lot of new concepts, choices, and options. Choice is good, but it can sometimes be overwhelming and confusing. 13 | 14 | Initially, the installation instruction will cover only the necessary options and configuration choices to help you quickly set up a running system with defaults suitable for daily use. With the system running and productive you can learn how to perform different routine system tasks such as installing apps, adjusting the system settings, or customizing openSUSE. And, if you're so inclined, start honing your Linux skills. 15 | 16 | ## For experienced users 17 | For experienced Linux users the documentation includes short pointers on how things are done in 18 | openSUSE and how things are different to other Linux distros. Links to advanced topics are provided to get you acquainted with the system, and quickly up and running. 19 | 20 | ## Documentation sections 21 | 22 | ### Pre-install 23 | The pre-install documentation gives you everything you need to get a system running. This can be a simple installation using default settings, or you can make a few choices, such as choosing a desktop environment. You can find out more about things like desktop environments in this section. 24 | 25 | For experienced users, this section describes what differentiates openSUSE from other distros, and helps you get to know the unique features and make informed choices during the install process. For example, find out about the power of snapshots using Btrfs, advanced distros featuring atomic transactional updates, and distros designed to run container loads. 26 | 27 | ### Install 28 | Now that you have a plan, this section will walk you through preparing installation media, and performing the installation based on the choice you made during pre-install. 29 | 30 | Experienced users will find a quick reference covering notable installation options and procedures. 31 | 32 | > At this stage and with minimum fuss you will have a running system with sane defaults that is ready for daily use. From here you can move forward and find out more as you need. 33 | 34 | ### Operating system (OS) orientation 35 | This section contains walk-throughs for the different features of Linux in general and openSUSE in particular. It covers the user interface, system settings, installing and upgrading 36 | software, and general good computing practices. You will also learn how to use unique openSUSE features like YaST and snapshots. 37 | 38 | ### After install setup 39 | This section covers setting up devices, such as printers, scanners, or a dedicated graphics card. You will also find information on how to install software that is not in the official openSUSE software repositories. 40 | 41 | ### Advanced install 42 | If you are an experienced user you might want to set up your system in a particular way to take 43 | advantage of the latest Linux technologies. This section contains information about how to set up openSUSE with technologies such as advanced partitioning schemes, encryption, 44 | display servers, vulnerability mitigation, and similar. 45 | 46 | ### Advanced topics 47 | Now that you're familiar with Linux and openSUSE, you want to get the most out of it. This section contains information on doing more advanced tasks with YaST, Zypper, Snapper, and other tools. 48 | 49 | ### Other documentation 50 | This section contains reference documentation and more guides suitable for corporate users and system administrators. Documentation is available in HTML, PDF and EPUB. 51 | -------------------------------------------------------------------------------- /ToC.md: -------------------------------------------------------------------------------- 1 | __NB__: Unless mentioned otherwise, a document corresponding to a parent section covers all topics listed as its children sections. 2 | ### Before installing 3 | 1. Choosing a distribution: [pick_and_image.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/pick_an_image.md), [issue](https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/37) 4 | * openSUSE distributions 5 | * desktop Environments 6 | * getting the right installer 7 | * FAQ: Issues & solutions 8 | 2. Preparing the installation media: [image_choice.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/image_choice.md), [issue](https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/26) 9 | * requisites 10 | * step by step guide 11 | ### Installing 12 | 3. Step by step guide: [yast_installer.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/yast_installer.md), [issue](https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/60) touching on 13 | * full disk install 14 | * multiple boot 15 | * disk partitioning 16 | * disk encryption 17 | * snapshots/btrfs 18 | 4. Quick install for experienced users 19 | * MicroOS: [microos_getting_started.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/microos_getting_started.md), [issue](https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/24) 20 | ### Distro basics 21 | 5. Post-install best-of [best_of_post.md](project/docs/best_of_post.md) 22 | 6. KDE Plasma basics [kde.md](project/docs/kde.md) 23 | * X, XWayland & Wayland sessions 24 | * settings & keybindings 25 | * using panes, bars, widgets & docks 26 | * learning more 27 | 7. GNOME basics 28 | * X & Wayland sessions 29 | * settings & keybindings 30 | * using extensions & plugins 31 | * learning more 32 | 8. openSUSE fundamentals 33 | * zypper: 34 | * commands list: [zypper.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/zypper.md), [issue](https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/32) 35 | * `tumbleweed-cli` & Tumbleweed snapshots: 36 | * best-practices for updating / upgrading Leap & Tumbleweed 37 | * YaST 38 | * `snapper` & `btrfs`: [snapper.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/snapper.md), [issue](https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/34) 39 | 9. Getting & installing additional software: [alternative_procurement.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/alternative_procurement.md) 40 | * RPMs, flatpaks, snaps, AppImages 41 | * running with podman 42 | * running with libvirt 43 | * building from source 44 | 10. Troubleshooting with autonomy 45 | * how Linux logs errors 46 | * dmesg & journalctl 47 | * finding the culprit 48 | * exporting evidence & asking for help 49 | ### Completing and fine-tuning your setup 50 | 11. Finding & installing additional software 51 | * codecs [codecs.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/codecs.md), 52 | * pipewire [pipewire.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/pipwire.md), 53 | * proprietary drivers [install_proprietary.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/install_proprietary.md), [issue](https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/28) 54 | * case study: Hybdrid/Optimus: [hybrid_graphics.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/hybrid_graphics.md), [issue](https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/77) 55 | 12. Power management 56 | * hibernating from swap 57 | * hibernating from file 58 | * suspend & lock 59 | * CPU power control 60 | 13. Pairing, syncing, sharing 61 | * bluetooth audio: [bluetooth.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/bluetooth.md), [issue](https://github.com/openSUSE/openSUSE-docs-revamped-temp/issues/27) 62 | * sharing files 63 | * syncing files with other devices 64 | * KDE Connect: [kdeconnect.md](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/project/docs/kdeconnect.md) 65 | 14. Advanced fine-tunings 66 | * transparent compression 67 | * kernel parameters 68 | ### Giving back to the community 69 | 15. The Art of Reporting bugs 70 | * the openSUSE bugzilla 71 | * the KDE bugilla 72 | * GitHub & GitLab Issues 73 | ### Resources 74 | 16. Other sources of documentation 75 | * Reference documentation 76 | * Wiki 77 | ### Contribute to this docs 78 | 17. A contributor's checklist 79 | * get in touch 80 | * open an issue 81 | * make a pull request 82 | * Doc Team onboarding 83 | -------------------------------------------------------------------------------- /project/docs/kdeconnect.md: -------------------------------------------------------------------------------- 1 | # KDE Connect 2 | 3 | __KDE Connect__ is a project that enables all your devices to communicate with each other. Here's a few things KDE Connect can do: 4 | 5 | * Receive your phone notifications on your desktop computer and reply to messages 6 | * Control music playing on your desktop from your phone 7 | * Use your phone as a remote control for your desktop 8 | * Run predefined commands on your PC from connected devices. See the list of example commands for more details. 9 | * Check your phone's battery level from the desktop 10 | * Ring your phone to help find it 11 | * Share files and links between devices 12 | * Browse your phone from your desktop 13 | * Control the desktop's volume using your phone 14 | * Send SMS from your desktop 15 | 16 | ## Installation 17 | KDE Connect is available for openSUSE Leap and Tumbleweed from the main repository. Use the following instructions, should you need to install it. 18 | 19 | !!! info 20 | If you use a desktop environment other than KDE's Plasma, you might also want to install `indicator-kdeconnect`, that provides a system tray as a GUI for other desktops. 21 | 22 | ### Using YaST 23 | 24 | ![YaST Software Management](image/yast_kdeconnect.png) 25 | 26 | 1. Launch `YaST` 27 | 1. Select `Software Management` 28 | 1. Type `kdeconnect` in the `Search` field and click __Search__ 29 | 1. In the result list select `kdeconnect-kde` 30 | 1. Click __Acept__ to confirm the installation 31 | 32 | ### Using the terminal 33 | 1. Refresh your local repository `sudo zypper ref` 34 | 1. Run `sudo zypper install kdeconnect-kde` 35 | 36 | ### Android Installation 37 | The app for Android can be found in both the [Google Play Store](https://play.google.com/store/apps/details?id=org.kde.kdeconnect_tp) and the free store [F-Droid](https://f-droid.org/repository/browse/?fdid=org.kde.kdeconnect_tp). 38 | 39 | 40 | ### Firefox Extension 41 | If you are a Firefox user, this [extension](https://addons.mozilla.org/en-GB/firefox/addon/kde_connect/) might be of your interest. 42 | 43 | ## Configuration 44 | In order for the secure communication to take place, ports in the firewall have to be opened up. We can do this using _YaST Firewall_ or using the command _firewall-cmd_ from the terminal. 45 | 46 | !!! info 47 | Note the zone of your current interface. If you do not specify the zone of the interface, it defaults to public. 48 | 49 | ### Using YaST Firewall to open the ports 50 | ![YaST Firewall](image/yast_firewall.png) 51 | 52 | 1. Launch `YaST` 53 | 1. Select `Firewall` 54 | 1. Within the `Zones` list, select `Public` 55 | 1. From the list of `Known` services search for `kdeconnect`, then click __Add__ 56 | 1. Click __Accept__ 57 | 1. The Firewall Service settings will save and the service will restart 58 | 59 | ### Using firewalld-cmd from the terminal to open the ports 60 | The easiest way to configure firewalld is through the terminal. 61 | 62 | The example below is adjusting the default zone using the kdeconnect service file for firewalld (`/usr/lib/firewalld/services/kdeconnect-kde.xml`). This service holds the list of ports required for a proper operation. For most user cases, this is an acceptable default. 63 | 64 | ``` 65 | $ sudo firewall-cmd --zone=public --permanent --add-service=kdeconnect-kde 66 | $ sudo firewall-cmd --reload 67 | ``` 68 | 69 | ## Android Configuration 70 | Most networks should allow automatic discovery of the devices running KDE Connect. 71 | 72 | ### Pairing devices 73 | 1. Launch `KDE Connect` on your computer 74 | 1. Launch `KDE Connect` application on the Android device 75 | 1. In the Android device, within `Available devices` select your computer 76 | 1. Tap `Request pair` 77 | 78 | Once paired, scroll through the options to determine how much information you want communicated back and forth between devices. 79 | 80 | ## Troubleshooting 81 | ### Devices are running KDE Connect, but they can't see each other 82 | * Ensure that the devices in question are on the same network 83 | * Ensure the necessary firewall ports have been opened. If they have been opened, try restarting the firewall daemon using the YaST Firewall Tool 84 | Go to `KDE Connect Settings` (on Android and/or openSUSE) and manually refresh the devices 85 | ### KDE Connect crashes or restarts when trying to pair with another device 86 | * Some times, a corrupt config file may cause KDE Connect to crash when trying to pair with a device. In that case, deleting the config files in `~/.config/kdeconnect` might help. 87 | ### The devices suddenly stop communicating 88 | If both devices are on the network and the firewall is properly configured but no notifications are being displayed one or the other may device have fallen asleep. Likely the service stopped or was suspended on the mobile device. 89 | 90 | Open the KDE Connect settings on either device and ping the opposite or select Refresh to force connection. 91 | 92 | 93 | ## Learning more 94 | * [KDE Connect site](https://kdeconnect.kde.org) 95 | 96 | ## References 97 | * ["SDB:KDE Connect"](https://en.opensuse.org/SDB:KDE_Connect). _openSUSE Wiki_. Retrieved 5 August 2021. 98 | * ["KDEConnect"](https://community.kde.org/KDEConnect). _KDE Community Wiki_. Retrieved 5 August 2021. -------------------------------------------------------------------------------- /project/docs/hybrid_graphics.md: -------------------------------------------------------------------------------- 1 | ## Dual GPUs setups 2 | This section is meant for users with dual 'graphic cards' (GPUs), often found in high-end laptops and essential to a pleasant video intensive experience (gaming, streaming, video editing, etc.) 3 | 4 | On these hardware configurations, there is a software switch that picks the _integrated_ graphics processor for rendering most desktop applications, switching to the _dedicated_ GPU for more demanding tasks. The switch can be more or less fine-grained. Fine-grained switches, such as the ones used in _Kdenlive_ and _OBS Studio_, are able to use VAAPI and NVENC to offload specific processes of encoding/decoding to the dedicated GPU, while a coarse-grained switch would have to offload an entire program instead. 5 | 6 | Some hardware configurations have a multiplexer (_mux_), a hardware switch that can be configured from the machine's UEFI to select the main graphics processor. A multiplexer is to be preferred if your hardware has one, as it performs better since there is no render offloading involved. This matters especially for users without external monitors, as the HDMI and DisplayPort outputs are usually connected directly to the dedicated GPU. Switching the multiplexer to the dedicated GPU or using an external monitor would thus offer better performance than using the built-in monitor or offloading the rendering to the dedicated GPU. 7 | 8 | Update your system before proceeding to the next steps: 9 | ``` 10 | sudo zypper dup 11 | ``` 12 | 13 | ### Dedicated NVIDIA GPU 14 | To use an external monitor or be able to offload rendering to the NVIDIA GPU, you'll need to follow the next steps. The external monitor will work when you switch to the NVIDIA GPU. This section applies to users interested in the proprietary NVIDIA driver. 15 | 16 | #### Getting the necessary software 17 | 1. [Install the correct Nvidia driver](install_proprietary.md). 18 | 2. Install the __suse-prime__ package using zypper or YaST. If you want to install via zypper run the following command in a terminal session: `sudo zypper in suse-prime`. Users on NVIDIA graphic cards released before GeForce 600 series should instead install __suse-prime-bbswitch__. 19 | : !!! info 20 | In case you are using KDE, a widget called _SUSE Prime Selector_ can be added as graphical way to switch graphics. You can install it with the command `sudo zypper in plasma5-applet-suse-prime`. 21 | 3. See the next sections according to your integrated and dedicated GPU combination. Alternatively, to offload rendering to the dedicated GPU (NVIDIA Optimus), see [Offloading specific applications to the NVIDIA GPU](hybrid_graphics.md#offloading-specific-applications-to-the-nvidia-gpu). This allows you to use both graphical units simultaneously. 22 | 23 | ### Intel and NVIDIA 24 | 25 | Either one of these two options: 26 | 27 | * From a terminal session: to switch to the NVIDIA GPU run `sudo prime-select nvidia`; conversely, for the Intel GPU run `sudo prime-select intel`. After executing either command, log out and back on to apply the changes. 28 | * With the KDE widget _SUSE Prime Selector_, just click it and select _Switch to NVidia_. Then log out and back in and you should be set. 29 | 30 | ### AMD APU and NVIDIA 31 | When using XOrg 1.20.6 or higher: to make the APU the primary GPU and have the ability to offload specific applications to the dedicated GPU, you can skip to the offloading section below. 32 | 33 | If you are using an older release of XOrg, such as the case for Leap 15.2, or you wish to exclusively use the NVIDIA card, pick between the following steps: 34 | 35 | * To enable only the NVIDIA GPU, run `sudo prime-select nvidia` from the command line. 36 | * To enable the AMD GPU, run `sudo prime-select unset`. 37 | 38 | After executing either command, log out and back on to apply the changes. 39 | 40 | ### Offloading specific applications to the Nvidia GPU 41 | 42 | Warning: This section only applies to users with the propietary driver and NVIDIA GeForce 600 series or higher utilizing the __nvidia-glG05__ driver package. 43 | 44 | With the integrated Intel GPU or AMD APU set as your main GPU, you can also offload specific applications using an envoronment variable. For example, to run __supertuxkart__ using the the NVIDIA driver, you can launch it from a terminal session as follows: 45 | 46 | __NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia __VK_LAYER_NV_optimus=NVIDIA_only supertuxkart 47 | 48 | 49 | To offload a game from Steam using the NVIDIA driver, you can modify properties of the game, by right clicking it, going to **Properties** choosing __Set Launch Options__ and adding a line like this: 50 | 51 | __NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia __VK_LAYER_NV_optimus=NVIDIA_only %command% 52 | 53 | For the offload process to work properly on integrated Intel cards, make sure the file `/etc/X11/xorg.conf.d/90-intel.conf` exists. If you do not have it, enable the NVIDIA card once and switch back to the integrated GPU; the required file will be created automatically along the way. Note that this only applies to XOrg sessions. 54 | 55 | If everything worked out fine for you, feel free to copy and modify the _.desktop_ files of your more demanding programs (like MATLAB or Octave) and append the enviroment variables to the `Exec` section of the file: 56 | 57 | Exec=__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia __VK_LAYER_NV_optimus=NVIDIA_only /usr/bin/octave --gui %f 58 | 59 | This makes the desired program offload to the dedicated GPU everytime you launch it from the shortcut. 60 | 61 | ### Dedicated AMD GPU or nouveau 62 | To offload anything to the AMD GPU, simply use the special enviroment variable to launch the desired program, as per the following example: 63 | 64 | DRI_PRIME=1 supertuxkart 65 | 66 | The same applies to users with the open source _nouveau_ driver for NVIDIA cards. -------------------------------------------------------------------------------- /project/docs/kde.md: -------------------------------------------------------------------------------- 1 | ## KDE 2 | KDE is an international technology team that creates free and open source software for desktop and portable computing. 3 | Plasma, made by KDE is the default graphical desktop environment of openSUSE. 4 | The latest version, Plasma 5, is a fresh, elegant and powerful desktop for both beginner and advanced users. 5 | 6 | KDE software is not limited to a desktop environment. The software made by the community includes: 7 | 8 | * Plasma, the graphical desktop. 9 | * KDE Applications, a collection of a wide variety of applications for communication, work, education and entertainment, including famous programs like Kate. 10 | * Additional high-quality applications, such as DigiKam and Krita. 11 | * KDE Frameworks, a series of modules to easily build new applications upon. 12 | 13 | What makes KDE software on openSUSE special: 14 | * It has a team of dedicated engineers who spend much of their time fixing bugs so you can rely on KDE. 15 | * It has a large, active and highly experienced community team around it who bring multiple points of view and different interests to the project so that KDE software 16 | on openSUSE meets many users' needs. 17 | * Through its innovation it stimulates the openSUSE distribution to develop, evolve and progress. 18 | 19 | ### X11, XWayland & Wayland sessions 20 | 21 | ### Settings & Keybindings 22 | 23 | KDE settings can be customized through the __System Settings__ application found in 24 | _Application Launcher --> Settings --> System Settings_. A convenient shortcut for System Settings can be found on the system panel as well. 25 | KDE is extremely customizable,to find more specific help visit the [Plasma Wiki](https://userbase.kde.org/Plasma) 26 | 27 | Keybindings or keyboard shortcuts are an efficient way to interact with KDE without having to use the mouse. 28 | 29 | In __System Settings__ click __Shortcuts__ under the "Workspace" category. 30 | You will be able to find any pre-existing shortcuts for many KDE applications as well as create your own shortcuts for any applications you install yourself. 31 | The __Custom Shortcuts__ menu allows you to create shortcuts for almost any system task. 32 |

33 | The Shortcuts window has three main areas. 34 | 35 | * The shortcut categories, __Shortcuts__ and __Custom Shortcuts__. 36 | * List of applications or custom shortcuts. 37 | * Shortcut editing area. 38 | 39 | ![Shortcut Settings](image/Shortcuts.png) 40 | 41 | Many KDE applications are already in the list. If you want to add additional applications simply 42 | click __Add Application__ and make a selection from the list. Click __OK__ to confirm the selection. 43 | 44 | ![Choose Application](image/Shortcuts_ChooseApplication.png) 45 | 46 | Once this step is done, the new application will be displayed in the Applications column. 47 | 48 | #### Changing Keyboard Shortcuts 49 | 50 | Select the application you want to change the shortcut for from the Applications column. The list of shortcut actions will be displayed in the editing area on the right. Click on any shortcut action to expand its settings (if there is only one shortcut available it will be automatically expanded). 51 |
52 | Shortcut actions can have default and custom keyboard shortcuts. You can disable the default by un-marking the box next to it or leave it active alongside any custom shortcuts you choose. 53 | 54 | Click __Add custom shortcut__, the button will change to indicate it is waiting for the next key combination, whatever keys are pressed next will be recorded as the custom shortcut. Click the "cancel" button, which has now appeared, if you change your mind. When a custom shortcut is recorded, you have the option to delete it by clicking the "trash" icon or additional custom shortcuts can be added. 55 |
56 | 57 | ![Modify Shortcuts](image/Shortcuts_Spectacle.png) 58 | 59 | Once you are satisfied with the changes, click __Apply__ in the bottom right corner of the shortcuts window. 60 | 61 | #### Adding Custom Shortcuts 62 | 63 | Select the __Custom Shortcuts__ category from the left hand column of the __Shortcuts__ settings window. Custom shortcuts allow you to trigger your own events from simple to complex that would not normally be available. For demonstration purposes we are going to setup a keyboard shortcut for a program called _Rofi_. You may not want to use this program yourself but the process is the same for other programs. 64 |

65 | First we will add a new __Custom Shortcut__ by clicking _Edit --> New --> Global Shortcut --> Command/URL_. A new entry will be added to the list in the middle column. 66 | 67 | ![New Custom Shortcut](image/CustomShortcuts_AddNew.png) 68 | 69 | The entry will be highlighted and its name selected so you can rename it immediately just by typing. If you want to change the name later on, simply double-click the name in the list and start typing. 70 | 71 | ![Rename Custom Shortcut](image/CustomShortcuts_NameNew.png) 72 | 73 | Using a name that is descriptive will help us remember what this custom shortcut does. In this case, the program _Rofi_ will display a list of open applications and switch between their windows with the keyboard. 74 |

75 | Now add the command that will be run when the keyboard shortcut is pressed. When an action is selected from the middle column, the right hand area will change to the editing view. You will see tabs near the top for __Comment__, __Trigger__, and __Action__. Click the __Action__ tab and add the command to the text box labeled "Command/URL". 76 | 77 | ![Add Custom Command](image/CustomShortcuts_Command.png) 78 | 79 | Next click the __Trigger__ tab. This is where the keyboard shortcut that triggers the command will be set. Click the button labeled "Shortcut" which will display the current keyboard shortcut if there is one. The button changes color and waits for you to type the desired shortcut. 80 | 81 | ![Add Trigger](image/CustomShortcuts_Trigger.png) 82 | 83 | If this keyboard shortcut is already used, a warning will be displayed. Click "Cancel" to try a different shortcut or click "Reassign" if you wish to use it anyway. For this demonstration, "Reassign" is selected. Click __Apply__ at the bottom right of the window. 84 |

85 | Now the custom keyboard shortcut runs the command system wide, no matter what applications are open. 86 | 87 | ![Demonstrate Custom Shortcut](image/CustomShortcuts_Demonstration.png) 88 | 89 | #### Using panes, bars, widgets & docks 90 | 91 | #### Learning more 92 | -------------------------------------------------------------------------------- /project/docs/updating_upgrading.md: -------------------------------------------------------------------------------- 1 | ## Leap 2 | ... 3 | 4 | ## Tumbleweed 5 | ### Introduction 6 | Tumbleweed is a rolling-release distribution. This means it gets updates on a continuous basis, usually several times a week. However, to bring some order and make it easier to manage producing and consuming updates, Tumbleweed fetches updates in batches. A single batch of updates is called a _snapshot_. 7 | 8 | !!! info 9 | Tumbleweed snapshots ought not to be confused with _Btrfs snapshots_, a completely different kind of snapshots. The latter make up the different filesystem states that allow _Btrfs_ users, using tools like YaST2 and `snapper`, to control which state they want to actualize). 10 | 11 | Tumbleweed snapshots are thus batches of updates which are tested in openQA -- openSUSE's very best testing pipeline. The tests are thorough and check not only that each upgraded package is healthy, but also that all updates in the same snapshot play nice with one another. A snapshot is thus as healthy as the individual updates it holds, and as the compatibility between one another. 12 | 13 | It should be emphasized that by default, Tumbleweed updates across all available updates, whether or not they belong to the same snapshots. In other words, the distribution of updates into snapshots is, by default, only used for production purposes. To take advantage of it at the user level, consider the [tumbleweed-cli section below](#tumbleweed-cli). 14 | 15 | ### Updating and upgrading 16 | As for Leap updating Tumbleweed is done with 17 | 18 | `sudo zypper dup` 19 | 20 | What this command does is to check whether all repositories registered against the system provide packages with available updates, collect and return the results. Upon confirmation from the user (`y` in a terminal window) it will download and then install them. 21 | 22 | !!! info 23 | On Tumbleweed you will never have to use **zypper-up**, which is how you would update packages on Leap. The reason is that since Tumbleweed is a rolling-release distribution, updating it means not just updating an arbitrary collection of packages; it also means using the updated packages as _the new snapshot_ which Tumbleweed is to realize. In addition to this **zypper-dup** enjoys some extra power over **zypper-up**, being able to not only edit packages, but to remove them when they are no longer required. 24 | 25 | It may occur that some repositories, when registered against the system, have not been configured to automatically look for new available updates during a `zypper-dup`. For this reason it might be useful to accompany this command with another one forcing all repositories to check for new updates, resulting in the pair: 26 | 27 | `sudo zypper ref && sudo zypper dup` 28 | 29 | That said, you can ensure that all repositories have been properly configured by listing them and, where applicable, by enabling their autorefresh feature. From the list of repositories obtained from: 30 | 31 | `zypper lr` 32 | 33 | identify repositories whose autorefresh value you want to tweak. For example: 34 | 35 | ``` 36 | # | Alias | Name | Enab-> | GPG Check | Refresh 37 | ---+----------------------------------+---------------------+--------+-------------+------------- 38 | 2 | brave-browser-beta | brave-browser-beta | Yes | (r ) Yes | No 39 | ``` 40 | 41 | shows that our `brave-browser-beta` repository has its refresh feature disabled. We can now set it to `enabled` with: 42 | 43 | `sudo zypper mr -f 2` 44 | 45 | which is a compact instance of 46 | 47 | `sudo zypper modifyrepo --refresh ` 48 | 49 | ### tumbleweed-cli 50 | 51 | !!! warning 52 | This section needs some rework as `tumbleweed-cli` introduces some safety issues in that: 53 | a) the evaluation algorithm used to [collect statistics](https://review.tumbleweed.boombatower.com/) about the 'health condition' of available Tumbleweed snapshots has been alleged to produce false positives. 54 | b) the advantages of rolling back to a previous Tumbleweed snapshot comes with the drawback that the user is no longer in sync with possible upcoming security fixes, which are shipped to target only the latest available snapshot. 55 | 56 | If you have not already, please read the short [introduction](#introduction). 57 | 58 | Tumbleweed users are gifted with the very useful command line utility `tumbleweed-cli`. This program lets you control finely your update process my making explicit which snapshot you are upgrading to, and by allowing you to roll in or back from snapshots. This comes in handy in cases where you know for sure that some outstanding issue is caused by one or by a combination of packages from the same snapshot, and go back to a previous snapshot which created no trouble. In addition to your own testing you can get some heads-up on which snapshots are deemed healthy or not from this [web application](https://review.tumbleweed.boombatower.com/). 59 | 60 | To install `tumbleweed-cli`: 61 | 62 | `zypper in tumbleweed-cli` 63 | 64 | Then intialize it: 65 | 66 | `tumbleweed init` 67 | 68 | The developer suggests to run this command to verify that the URLs of the repos contain a snapshot version: 69 | 70 | `zypper lr -EUP` 71 | 72 | Once this is done you can finally take advantage of the snapshotting system employed for producing Tumbleweed packages, keeping your system aligned with the latest healthy snapshot released. This is done by simply running: 73 | 74 | `tumbleweed update` 75 | 76 | It is worth noting that external repositories, that is, repositories manually added and whose packages are not included in Tumbleweed snaphshots, will not be updated just by running this command. You will still have to run `(sudo zypper ref &&) sudo zypper dup`. This is simply a consequence of the fact that the updates provided by Tumbleweed snapshots are but a subset of all the packages in reach of `zypper-dup`, which has access to the updates provided by external repositories. 77 | 78 | At any time you can then check the status of your system with respect to the latest snapshots released: 79 | 80 | `tumbleweed status` 81 | 82 | that returns for example: 83 | 84 | ``` 85 | latest : 20210414 86 | target : 20210414 87 | installed: 20210414 88 | ``` 89 | 90 | where `target` refers to the next snapshot the system is going to update to with `tumbleweed-update`. 91 | 92 | Setting the target to the previous snapshot and reverting to it is performed with: 93 | 94 | `tumbleweed revert --install` 95 | 96 | or if the previous snapshot is for instance 20210411, the equivalent: 97 | 98 | ``` 99 | tumbleweed switch 20210411 100 | sudo zypper dup 101 | ``` 102 | 103 | `tumbleweed-switch` is thus the more generic option allowing you to set the target to whichever snapshot you fancy, provided it is available. The full list of snapshots available for switching is obtained with: 104 | 105 | `tumbleweed history` 106 | 107 | Should you want to uninstall `tumbleweed-cli`, make sure you deactive its particular update mechanism before. This is done with: 108 | 109 | `tumbleweed uninit` 110 | 111 | From now on `zypper-dup` will again fetch updates across all snapshots, which is the default. You can remove `tumbleweed-cli` with: 112 | 113 | `sudo zypper rm tumbleweed-cli` 114 | 115 | ## Further reading 116 | * [tumbleweed-cli](https://github.com/boombatower/tumbleweed-cli) 117 | * [snapshow reviewer](https://review.tumbleweed.boombatower.com/) 118 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ## Get in touch? 2 | We often hang out on [this Telegram chat](https://t.me/opensuse_docs), which by the way is bridged to the IRC `#docs:opensuse.org` and to `#docs` on [this Discord channel](https://discord.gg/opensuse). 3 | 4 | ## Reviewing process 5 | ``` 6 | new document ------> review on structure and contents #1 ------> review on language, style and punctuation #1 7 | | 8 | | 9 | marked "ready for release" <--- review on language #2 <--- review on contents #2 <------ 10 | ``` 11 | 12 | ## Getting started 13 | ### Understand the repo structure 14 | ``` 15 | ... 16 | Pipfile <<< project dependencies in pipenv format. That is what 'pipenv install' operates on. 17 | requirements.txt <<< project dependencies in pip format. Added for compatibility. 18 | pyproject.toml <<< project dependencies in poetry format. That is what 'poetry install' operates on. 19 | project/ <<< 'cd' in here to run mkdocs commands (pipenv commands are to be run from the root directory) 20 | docs/ <<< WHERE YOU CONTRIBUTE. You will be adding or editing files there. 21 | mkdocs.yml <<< build config, but also used as Table of Contents. If you add a new file, reference it there. 22 | ... 23 | ... 24 | ``` 25 | `.gitignore` should not let you commit any `build` directory. Please make sure that is the case. 26 | 27 | ### Setup your work environment 28 | You can either install mkdocs from pip or from a virtual environment. 29 | 30 | It's highly recommended to use a virtual environment manager and not `pip`, so that the dependencies of this project won't mess with your system-wide python packages / modules. You still need to run pip once to install your favorite virtual environment manager. 31 | 32 | ## Pipenv installation 33 | 34 | We like using pipenv, which you install on openSUSE distributions with: `pip3 install --user pipenv`. Then you'll need to add `~/.local/bin` to your `PATH`. The best method for that depends on your shell: 35 | * for `bash` add `PATH=$PATH:/home/your-user-name/.local/bin` to `~/.bashrc`; reload to apply changes with `source ~/.bashrc` 36 | * for `fish` run the following command once from a fish shell: `set -Ua fish_user_paths /home/your-user-name/.local/bin`; start a fresh shell with `exec fish` 37 | * for `zsh` add `export PATH=$PATH/home/your-user-name/.local/bin` to `~/.zshrc`; reload to apply changes with `source ~/.zshrc` 38 | 39 | ## Poetry installation (requires python3.5+) 40 | 41 | Install via poetry installer : `curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -` 42 | 43 | After installation command complete you will find your poetry install under `$HOME/.poetry/bin` 44 | This directory will be automatically added to your $PATH environment variable, by appending a statement to your $HOME/.profile configuration (or equivalent files). If you do not feel comfortable with this, please pass the --no-modify-path flag to the installer and manually add the Poetry's bin directory to your path. 45 | 46 | Another ways to install poetry are via openSUSE repository `zypper install python38-poetry` for python 3.8 and `zypper install python36-poetry` for python 3.6. 47 | 48 | ### Enable tab completion for `poetry` 49 | ``` 50 | # Bash 51 | poetry completions bash > /etc/bash_completion.d/poetry.bash-completion 52 | 53 | # Bash (Homebrew) 54 | poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion 55 | 56 | # Fish 57 | poetry completions fish > ~/.config/fish/completions/poetry.fish 58 | 59 | # Fish (Homebrew) 60 | poetry completions fish > (brew --prefix)/share/fish/vendor_completions.d/poetry.fish 61 | 62 | # Zsh 63 | poetry completions zsh > ~/.zfunc/_poetry 64 | 65 | # Oh-My-Zsh 66 | mkdir $ZSH_CUSTOM/plugins/poetry 67 | poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry 68 | 69 | # prezto 70 | poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry 71 | ``` 72 | 73 | ### Clone, edit, test 74 | 1. clone this repo where you want in your home folder 75 | 2. `cd` to it and run `pipenv install` or `poetry install` to install the dependencies, and then `pipenv shell` or `poetry shell` to run the environment. 76 | 3. finally `cd` to `project` and run you `mkdocs` commands from there. 77 | 78 | The only important command is `mkdocs serve`; it generates the website from the source files and service it on http://127.0.0.1:8000/. 79 | 80 | Use it now to make sure you can build and display the website. 81 | 82 | Now you are read to work on the docs. You can either shut down the server with `CTRL + c` or let it run. It will auto-reload and refresh your browser whenever you save your changes. 83 | 84 | ### Get ready to open a Pull Request 85 | If you are new to `git` and GitHub, read https://jarv.is/notes/how-to-pull-request-fork-github/. 86 | 87 | When you are done working, go through the checklist before opening a Pull Request against our repository. 88 | 89 | __Checklist__: 90 | - [x] When doing `git checkout -b <...>`, did you make sure that `meaningful name` satisfied the schema described under __Branches__ below? If not, you can still rename it using `git branch -m `. 91 | - [x] Have you followed the style guidelines below under __Style__? 92 | - [x] If you have added a new article: 93 | - a) did it land in `/project/docs`? If not, move it there. 94 | - b) have you added it to [table of contents](https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/ToC.md)? Just follow the examples already there. The urls look like `https://github.com/openSUSE/openSUSE-docs-revamped-temp/blob/dev/` 95 | - [x] Have you tested your work? If not consider the __Clone, edit, test__ section above. 96 | - [x] Are you going to make your PR editabled for us? If you don't know how, you will have to check the `Allow edits from maintainers` checkbox on the Pull Request screen, in GitHub. Otherwise we won't be able to work with you on your PR. 97 | 98 | ## Formal constraints 99 | ### Branches 100 | * The default branch -- the working branch -- is not `main` or `master` but `dev`. I will merge from one milestone to the other. 101 | * 4 types of branch names, named after the type of commits you want to contribute. PRs should whenever possible concern just one type of commit. 102 | * `structure` (how the textual and multimedia contents breaks down into different parts) 103 | * `design` (web and non-web visuals) 104 | * `web-functions` (functionalities invoked from the web release of the docs) 105 | * `contents` (textual and multimedia contents) 106 | 107 | ### Style 108 | _Structure_. Each document should start with an intro stating the end goal, the important presuppositions (typically about pre-requirements) that the document is making, and an outline of the main steps on the path to the goal. 109 | 110 | _Technical jargon_. Important and unavoidable jargon should be defined (typically inlined, with info boxes). Overall the document should be understanble by a teenager (think secondary school textbook). 111 | 112 | _Format_: 113 | * reference points and path items in italics, ex: "_Settings_ > _Energy Saving_" 114 | * action in bold, ex. "click __Yes__" 115 | * code instructions part of a stepwise recipe between line breaks in code, ex. 116 | ``` 117 | $ sudo zypper dup 118 | ``` 119 | * short snippets of code or not part of a stepwise recipe can be inlined as in "... run `sudo zypper dup` before anything else". 120 | * first occurrence(s) of technical terms: italics 121 | -------------------------------------------------------------------------------- /project/docs/best_of_post.md: -------------------------------------------------------------------------------- 1 | # Our "post installation" best of 2 | Some of the material covered below is presented and discussed in more details elsewhere in this documentation. Use the links if you'd like to learn more. 3 | 4 | The order in which you carry out these recommendations is not crucial, but we advise you to follow our order, as certain steps feel more natural if you have followed previous ones on the list. 5 | 6 | The list takes the point of view of a user who has just rebooted and logged in to an openSUSE distribution. 7 | 8 | ## Tumbleweed 9 | 10 | ### Update 11 | Even if you have installed Tumbleweed with repositories enabled, who knows if there isn't a bunch of updates pending already? 12 | ``` 13 | $ sudo zypper dup 14 | ``` 15 | 16 | ### Get used to adding repositories with auto-refresh on 17 | When you add repositories to Tumbleweed, those do not have their auto-refresh setting on by default. This means that doing `sudo zypper dup` might report no pending updates when in fact there __are__ updates, but those were not just seen by the package manager. To change this behavior and ensure that your system will always hook up to repositories with auto-refresh enabled, make sure you add repositories with auto-refresh on: 18 | ``` 19 | sudo zypper ar --refresh # you can use '-f' instead of '--refresh', they are synonyms 20 | ``` 21 | 22 | ### Shell and Terminal 23 | Even though Tumbleweed is a very accessible Linux distribution, you will have to spend some time talking to your system via a shell so better get one you feel comfortable with. We personally recommand [fish](https://fishshell.com/) and [zsh](https://ohmyz.sh/), both of which provide auto-completion for commands you have previously used and commands that are provided by the programs that the shell has discovered (including file paths!). _fish_ is a bit more friendly to the beginner, whereas _zsh_ is more feature-ful and implements a protocol that is a bit closer to the one use by the built-in shell (_bash_). 24 | 25 | Refer to the documentation provided by the developers to make your favorite shell the default. Also, don't overlook _aliases_ -- user-defined synonyms for shell commands. You won't regret creating a few aliases should you need a command that you don't remember from a _tty_ console. 26 | 27 | For a terminal application we recommend to stick to the one provided by your desktop environment. Users interested in having a collapsible, HUD-like terminal can turn to the excellent _Yakuake_ terminal, based on KDE's _Konsole_. 28 | 29 | ### (KDE Plasma only) Disable Discover notifications 30 | On Tumbleweed software are better installed using the official package manager, at your own pace (although we recommend updating at least once a month) using either a terminal or Yast. This means that Discover update notifications will feel annoying at best, and will push to frantically update even in cases where you'd want to postpone updating for a couple of days or weeks. To regain your peace of mind: 31 | 32 | Go to _Plasma settings_ > _Notification_ > _Applications: Configure_ > Select _Discover_ in the list > Untick as many boxes as you need. 33 | 34 | ### Setup your Tumbleweed for Flatpaks 35 | Flatpaks are covered in more details in this guide, but they are an invaluable source of stable and frequently updated software: 36 | ``` 37 | $ sudo zypper in flatpak 38 | $ flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo 39 | ``` 40 | 41 | ### Customize your .desktop files for a better user experience 42 | Most user applications shipping their own GUI install with a desktop file (`.desktop`) providing the application with some parameters discovered at the installation. Some of these parameters are key to a comfortable user experience. 43 | 44 | Consider for examples Electron apps, which as of today (26th of July 2021) offload rendering to the X11 instead of the Wayland client. This means that your Desktop Environment, which is likely to run with Wayland enabled by default, will not be able to make the most of the application's GUI. 45 | 46 | We can improve the situation as follows: 47 | 1. Locate the application's desktop file, most likely at `/usr/share/applications`. For instance you can go a simple: 48 | ``` 49 | $ ls /usr/share/applications | grep "name of the application" 50 | ``` 51 | 2. Once you're certain of the file name, you can edit it on the fly: 52 | ``` 53 | $ sudo nano /usr/share/applications/code.desktop 54 | ``` 55 | For instance it makes sense to require vscode -- an Electron application -- to use Wayland. Change this: 56 | ``` 57 | Exec=/usr/share/code/code --unity-launch %F 58 | ``` 59 | to that: 60 | ``` 61 | Exec=/usr/share/code/code --enable-features=UseOzonePlatform --ozone-platform=wayland 62 | ``` 63 | It might take a reboot for your applications to acknowledge the change to their `.desktop` file. If you want to compare the result of your changes -- if any -- to a run where these changes are known to be in force, just launch the application from a command line: 64 | ``` 65 | code --enable-features=UseOzonePlatform --ozone-platform=wayland 66 | ``` 67 | 68 | ### Codecs 69 | openSUSE distributions do not ship with proprietary software, and for most cases there are Free and Open Source alternatives, such as the free codecs shipped with certain applications (most modern web browsers such as the Chromium-based ones and Firefox). 70 | 71 | If however you do need proprietary codecs, you can add them manually. To do this we recommend using the `opi` -- Open Build Service Package Installer, which is able to fetch software sitting just outside of the official system repositories: 72 | 73 | ``` 74 | sudo zypper in opi 75 | opi codecs 76 | ``` 77 | 78 | Notice that some applications come packaged with proprietary codecs; that is the case for `VLC` for instance. If you install these applications from the official repositories you don't need to install codecs manually. 79 | 80 | ### Setup you GPU driver 81 | Check out the following documentation for this step: 82 | * [single GPUs](install_proprietary.md) 83 | * [integrated + dedicated GPUs](hybrid_graphics.md) 84 | 85 | ### Use a password manager 86 | KDE's _kwallet_ and _gnome-keyring_ are decent password managers as far as storing identifiers meant to be consumed by third-party applications, but some users might feel they fall short when it comes at providing a comfortable interface for auto-completion and daily management (especially the latter). 87 | 88 | For alternatives you can consider _KeePass Password Safe_ (https://keepass.info/) and _Password Safe_ (https://gitlab.gnome.org/World/PasswordSafe). 89 | 90 | ### Have your backup plan ready 91 | Tumbleweed snapshots protect your system by allowing you to rollback to and from the snapshot of your liking. One noticeable exceptions to this protection is `/home` (for the simple reason that it allows the user to backup their `home` at their own pace, independently from system snapshots.) 92 | 93 | To protect your users' `/home` directory you may want to use a third-party application to manage user-defined backups. We can recommend [restic](https://restic.net/) and the easier to the new user [rclone](https://rclone.org/). 94 | 95 | !!! info 96 | If `/boot` is not on the same partition as `/`, it won't be covered by system snapshots either. In that case your bootloader (eg. _GRUB)_ will not benefit from snapshots. 97 | 98 | ### Fine-tune Btrfs snapshots settings 99 | Tumbleweed comes pre-configured with a generous _Btrfs_ snapshot policy that is likely to produce more snapshots than you need, leaving too significant a footprint on your storage device to be really worth it. If that is the case, please refer to the documentation on [Snapper](snapper.md) to change the defaults. Bear in mind that this is a fundamentally important aspect of Tumbleweed, so read the documentation thoroughly. 100 | -------------------------------------------------------------------------------- /project/docs/markdown.md: -------------------------------------------------------------------------------- 1 | # Markdown example 2 | 3 | !!! NOTE 4 | This page is temporary for onboarding and will be removed in doc releases. 5 | 6 | ## Admonitions Blocks 7 | Examples of supported admonitions blocks I enabled in the theme and mkdocs. 8 | 9 | - All blocks can be made collapsable like the second example. 10 | - Blocks icons and styling can be modified and new ones can be added 11 | 12 | !!! Note 13 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 14 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 15 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 16 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 17 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 18 | ``` python 19 | def bubble_sort(items): 20 | for i in range(len(items)): 21 | for j in range(len(items) - 1 - i): 22 | if items[j] > items[j + 1]: 23 | items[j], items[j + 1] = items[j + 1], items[j] 24 | ``` 25 | 26 | ???+ Note 27 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 28 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 29 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 30 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 31 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 32 | 33 | !!! info 34 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 35 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 36 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 37 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 38 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 39 | 40 | !!! seealso 41 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 42 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 43 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 44 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 45 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 46 | 47 | !!! abstract 48 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 49 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 50 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 51 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 52 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 53 | 54 | !!! todo 55 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 56 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 57 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 58 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 59 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 60 | 61 | !!! tip 62 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 63 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 64 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 65 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 66 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 67 | 68 | !!! done 69 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 70 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 71 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 72 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 73 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 74 | 75 | !!! question 76 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 77 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 78 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 79 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 80 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 81 | 82 | !!! warning 83 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 84 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 85 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 86 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 87 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 88 | 89 | !!! fail 90 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 91 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 92 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 93 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 94 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 95 | 96 | !!! danger 97 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 98 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 99 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 100 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 101 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 102 | 103 | !!! bug 104 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 105 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 106 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 107 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 108 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 109 | 110 | !!! example 111 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 112 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 113 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 114 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 115 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 116 | 117 | !!! quote 118 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut 119 | labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 120 | laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 121 | voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat 122 | non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | -------------------------------------------------------------------------------- /project/docs/image_choice.md: -------------------------------------------------------------------------------- 1 | ## Choosing an installation media 2 | The installers and images can be obtained on the [Tumbleweed](https://software.opensuse.org/distributions/tumbleweed) and [Leap](https://software.opensuse.org/distributions/leap) pages. 3 | 4 | Most users are used to Live images, packing a full-blown environment where they can test 5 | out a Linux distribution before installing. 6 | 7 | !!! note for Tumbleweed 8 | Users interested in Tumbleweed should bear in mind that, because of the way Tumbleweed is built, Tumbleweed Live images are missing a handful of tests in comparison to Tumbleweed DVD images (see below). So even if Live images can be considered reasonably safe for most users, we cannot guarantee the same quality assurance as for DVD images. 9 | 10 | Our live images (~950 MBs) provide the following desktop environments: 11 | 12 | - KDE 13 | - GNOME 14 | - XFCE 15 | 16 | They each come in different flavours tailor-suited to your CPU architecture: 17 | 18 | - x86_64 (64-bit) 19 | - i686 (32-bit) 20 | - aarch64 (Armv8-A "ARM" 64-bit) 21 | 22 | The two other installation media we provide are DVD images and Network installer. 23 | 24 | - DVD images are quite bulky (~4.5 GBs), but allow you to install an entire distribution without relying on network for retrieving components. 25 | - Networks installers are much lighter (~150 MBs); they require a stable and hopefully fast connection to fetch components over the network. 26 | 27 | ## Authenticity & integrity checks (*NIX) 28 | 29 | !!! note 30 | The following two steps are optional, but are considered good practice. 31 | 32 | You perform an _integrity check_ when you want to make sure that a given file has not been tampered with. It typically involves making sure that a file's checksum matches a certain target. 33 | 34 | You perform an _authenticity check_ when you want to make sure that a file -- typically the file that specifies the checksum target -- was obtained from a legitimate source (i.e. openSUSE). Because performing an integrity check against an inauthentic target does not make sense, you want to first do an authenticity check, and only then do an integrity check. 35 | 36 | ### Assumptions & definitions 37 | In what follows we make the following assumptions: 38 | 39 | 1. You have downloaded an openSUSE Live, Network or DVD image from openSUSE website (hereafter: the __Image__): 40 | * [Tumbleweed](https://software.opensuse.org/distributions/tumbleweed) 41 | * [Leap](https://software.opensuse.org/distributions/leap) 42 | 2. You have obtained the __Target Checksum__ file for your image, by clicking on the _Checksum_ next to the image. 43 | 3. You have obtained openSUSE gpg __Public Key__ by importing it via its keyid into your gpg keyring with 44 | ``` 45 | $ gpg --recv-keys 0x22C07BA534178CD02EFE22AAB88B2FD43DBDC284 46 | ``` 47 | or on a non-*NIX operating system, simply download the file at 48 | 4. You have obtained an openSUSE gpg __Detached Signature__ file corresponding to the image you want to perform the check upon. The Tumbleweed detached signature files are held within a single directory [here](http://download.opensuse.org/tumbleweed/iso/). Regarding Leap however you need to start [there](http://download.opensuse.org/distribution/openSUSE-current/) and use the `/live` subdirectory for the live images and the rescue images (the `/iso` subdirectory does not provide any detached signature for net installers and DVD images). Once you have the address of the signature file, the command looks like this (i.e. for KDE Live): 49 | ``` 50 | $ wget http://download.opensuse.org/tumbleweed/iso/openSUSE-Tumbleweed-KDE-Live-x86_64-Current.iso.sha256.asc 51 | ``` 52 | 53 | ### Authenticity check 54 | For Tumbleweed (all images) and Leap (only live images) the authenticity check is an instance of the command: 55 | ``` 56 | $ gpg --verify 57 | ``` 58 | For Leap non-live images (typically DVD images) the authenticity check uses no signature (clearsign check); it is an instance of the command: 59 | ``` 60 | $ gpg --verify 61 | ``` 62 | The check passes just in case the command outputs calls it a success. 63 | 64 | !!! warning 65 | If the check fails, make sure you are honoring our [assumptions](#assumptions-definitions). 66 | 67 | ### Integrity check 68 | It is an instance of the command: 69 | ``` 70 | $ sha256sum 71 | ``` 72 | The check passes just in case the output of the above equals the checksum written in plain text in the __Target Checksum__ (see [Definitions & assumptions](#assumptions-definitions)). 73 | 74 | ## Authenticity and integrity checks (Windows 10) 75 | 76 | __Preparation__: 77 | 1. Download the filename.iso.sha256 file from the Download section of opensuse.org or download the hash files from here 78 | 79 | * for Tumbleweed: https://download.opensuse.org/tumbleweed/iso/openSUSE-Tumbleweed-DVD-x86_64-Current.iso.sha256 80 | * for Leap: https://download.opensuse.org/distribution/leap/15.3/iso/openSUSE-Leap-15.3-DVD-x86_64-Current.iso.sha256 81 | 82 | Note that it does not matter where exactly you put the files as long as they are all in the same folder and keep their original names. 83 | 84 | 2. Then browse to https://www.gnupg.org/download/index.html and download and install the Windows installer for GnuPG. 85 | 86 | !!! info 87 | For the purposes of this guide it does not matter whether you install the program as administrator or not, so just click yes to install to install without administrator rights if it asks you. 88 | 89 | 3. Find the folder containing the files you downloaded in the first step, hold Shift while right-clicking it (the folder, not the files in it). Select it to open a command window. 90 | 91 | Use whichever command line utility you've got available, but if you used the PowerShell option, type `cmd` followed by `Enter` in the command prompt. 92 | 93 | ### Integrity Check 94 | 95 | 1. Locate the folder of the downloaded ISO image 96 | 2. Open a command prompt. 97 | 3. `cd` to the folder and finally type this command, confirming the command with `Enter`: 98 | ``` 99 | CertUtil -hashfile .iso SHA256 # replace with the actual name of your ISO image 100 | ``` 101 | Example: 102 | ``` 103 | certutil -hashfile openSUSE-Tumbleweed-DVD-x86_64-Snapshot20210611-Media.iso SHA256 104 | ``` 105 | 106 | Note that if you start typing a filename you can press Tab to automatically complete it. 107 | 108 | This will take a little while to complete and eventually present you with an alphanumeric sequence that is called a hash. If this hash is identical to the one listed in your filename.iso.sha256 then the integrity check passed. You can compare them by hand (note that some Windows text editors will not display the line breaks in that document so it may look weirdly formatted) or better use the find command. 109 | 110 | If the same hash is not found in `.iso.sha256`, then your downloaded ISO image did not pass the integrity check. Make sure you downloaded the correct `.iso.sha256` and if yes, try to download the ISO image again from a different mirror server. Try on it the integrity again. 111 | 112 | !!! info 113 | On older versions of Windows, the CertUtil command does not exist. Instead it is recommended to install `7zip` from https://www.7-zip.org/, then find and right-click the .iso file your downloaded in Windows Explorer and select 7-Zip's CRC SHA option to calculate the SHA 256 hash, which must then compare to the one from the filename.iso.sha256 file yourself. 114 | 115 | !!! warning 116 | Never install from an .iso that failed the integrity check. 117 | 118 | ### Authenticity Check 119 | 120 | To perform the authenticity check of the ISO image, 121 | 122 | 1. obtain the official GPG public key and SHA256 hash file from here (http://download.opensuse.org/tumbleweed/iso/) of your required openSUSE iso version. 123 | 2. Download the required "filename.iso.sha256.asc" and "filename.iso.sha256" file and save it named with "sha256sum.txt.gpg" and "sha256sum.txt" in one folder. (Note: ISO file and these two .txt file should be in one folder). 124 | 3. You can then perform the check from a command prompt. 125 | 126 | gpg --verify sha256sum.txt.gpg sha256sum.txt 127 | 128 | {Message for you Ad: you can attach a image of the result of this command line} 129 | 130 | As long as it says Good signature from "openSUSE Tumbleweed ISO Signing Key " and with a fingerprint matching the one shown above and that you used to download the key, then that means your download is authentic. In case it was tampered with the message would be BAD signature from .... 131 | 132 | You can ignore the warning that comes after that, it is expected and perfectly normal. 133 | 134 | ## Get to the installer 135 | In this section you will learn how to get to a running installer for _Tumbleweed_ or _Leap_. This involves: 136 | 137 | - Using a program to write an installation image -- see [Choosing an installation image above](#choosing-an-installation-media) -- to an external device, usually a USB pen drive or some other external storage medium. 138 | - Having the media adequately partioned to host the image, and making it bootable 139 | - Booting on the external media and run the installer. 140 | 141 | We will assume that you have downloaded an installation image and optionally, have performed an authenticity check on it -- see the above sections for details. The next section also assumes that you will be using a USB flash drive as the installation media. The section after that handles external hard drives. 142 | 143 | ### Prepare the installation media (USB flash drive) 144 | The process for preparing the installation media varies depending on the operating system from which you are following these steps. Different operating systems offer different applications. We recommend using any of the following programs, which we have tested and which are known to be simple to use and reliable on their respective platforms: 145 | - Fedora Image Writer ([Windows & Mac](https://getfedora.org/en/workstation/download/), [Linux flatpak](https://flathub.org/apps/details/org.fedoraproject.MediaWriter)) 146 | 147 | For _Fedora Image Writer_: 148 | 149 | 1. Make sure your USB flash drive has enough storage to hold the image (either ~1 GB or ~5 GB) and plug it in. 150 | 2. Run _Fedora Image Writer_. From the main menu pick __Custom image__ and then select the `.iso` image to write to the USB flash drive. Make sure that both the image and flash drive have been correctly selected, as in: ![this screenshot](image/image_choice_fiw_conf_prompt.png) 151 | 3. Finally click on __Write to Disk__. 152 | 153 | Once writing the image is done, you are ready to reboot from the USB drive. Leaving the USB drive plugged in, use the method appropriate to your operating system to restart your computer. 154 | 155 | ### Reboot to the device 156 | Assuming you have successfully installed an openSUSE distribution, you should reboot according to the method relevant to your current operating system. 157 | 158 | #### Windows 159 | 160 | Use [these instructions](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/boot-to-uefi-mode-or-legacy-bios-mode) to reboot to your BIOS or UEFI. From there you will be able to select the USB flash drive hosting the installation image as boot destination. 161 | 162 | #### macOS 163 | Simply hold the `alt` (option) key immediately after restarting and select the openSUSE bootloader from there. 164 | -------------------------------------------------------------------------------- /project/docs/microos_getting_started.md: -------------------------------------------------------------------------------- 1 | ## Setting up MicroOS as a desktop OS 2 | ### Audience and context 3 | This document is meant for users interested in using the openSUSE MicroOS as a desktop. Although this operating system is offered in two flavours (one based on Leap, the other on Tumbleweed), we will only be concerned with the Tumbleweed base, as the Leap base does not provide the required patterns for desktop usage. 4 | 5 | ### Pre-installation 6 | 7 | 1. Download the Tumbleweed base ISO image from [https://en.opensuse.org/Portal:MicroOS/Downloads](https://en.opensuse.org/Portal:MicroOS/Downloads) 8 | 2. Write the ISO on a USB drive and start the installation process. 9 | 3. Select GNOME or KDE Plasma as desktop environment. 10 | 4. If desired, select _encryption_. 11 | 12 | In what follows: 13 | 14 | * commands starting with `$` can be copied straight into your terminal prompt. 15 | * commands starting with `#` can only be run inside a transactional-update shell. 16 | 17 | !!! info 18 | A _transactional-update shell_ is a chroot where you can open the snapshot you want to boot into next. In that context you can make adjustments to the normally immutable root filesystem. It is meant mostly for advanced users, so mind your keystrokes. 19 | 20 | ### Ways to install applications 21 | You can install applications in several ways: 22 | 23 | * flatpaks from flathub -- the _preferred solution_ 24 | * RPM's via a package manager 25 | * RPM's in a toolbox `toolbox -u` 26 | * snaps (requires some extra setup to get snapd installed) 27 | * AppImages 28 | 29 | !!! info 30 | The reason _flatpaks_ are preferred is that they provide a self-contained environment offering a pleasant balance between security, dependence integrity and performance. See [here](https://flatpak.org/) for details. 31 | 32 | ### Package manager options 33 | MicroOS now has a few different package managers as an option during install: 34 | 35 | * transactional-update with zypper `the old default, and still the default for the server version` 36 | * Packagekit + tukit `the new default, using pkcon and tukit` 37 | * microdnf `an experimental package manager based on dnf` 38 | 39 | The reason for changing package managers is because pkcon gives the opportunity to use Gnome Software or Discover for KDE as an installer of RPM's. And currently we are working on the ability to let Gnome Software and Discover perform system upgrades. 40 | 41 | #### Transcational-update _old default_ 42 | commands for transactional-update are: 43 | 44 | * `sudo transactional-update pkg install package_name` install a rpm package 45 | * `sudo transactional-udpdate dup` perform a system upgrade to the next release 46 | * `sudo transactional-update shell` open a shell of the next snapshot (you can use zypper commands there) 47 | 48 | #### Packagekit + tukit _new default_ 49 | commands for Packagekit and tukit: 50 | 51 | * `pkcon install package_name` install a rpm package 52 | * `pkcon update` perform a system upgrade to the next release 53 | * `sudo tukit execute bash` open a shell of the next snapshot (you can use zypper commands there) 54 | 55 | #### Microdnf 56 | commands for microdnf: 57 | 58 | * `microdnf install package_name` install a rpm package 59 | * `microdnf upgrade` perform a system upgrade to the next release 60 | 61 | ### Full drive encryption 62 | If you need full drive encryption you can go through the ISO installer as normal, except for the last screen, where you need to click on _Partitioning_. Then use the guided partitioner to enable encryption. _LVM_ is not necessary for it to work. 63 | 64 | Bear in mind however that with full drive encryption, you will need to enter your password twice: 65 | 66 | 1. the first time to open the grub menu 67 | 2. the second time to decrypt during boot. 68 | 69 | Alternatively, the second decrypt can be performed automatically; instructions are provided at [manual](https://en.opensuse.org/SDB:Encrypted_root_file_system). 70 | 71 | !!! info 72 | Full disk encryption is _not_ recommended for SSD's as trimming is currently not supported due to the read only nature of the / filesystem during boot. 73 | 74 | 75 | ### Installation: GNOME 76 | _Gnome is currently in a beta stage._ 77 | 78 | At first boot flatpaks are enabled and some flatpaks are installed by default (MozillaFirefox, Gedit and Gnome Calculator). 79 | 80 | Make sure to install a browser via transactional-updates if you want to use GNOME extensions. The easiest way to install GNOME extensions is via the website provided by the [GNOME project](https://extensions.gnome.org/). For this to work however, you will need a browser installed on the system via transactional-update, as it will not work inside a containerized environment (like flatpaks, snaps, AppImages or in a toolbox). The browser will need to have the plugin mentioned on the top of the page when you first open it. 81 | 82 | After installation of the plugin, you can reload the page and choose the GNOME Extensions you want to install. 83 | 84 | To get GNOME extensions running, you need the following command to install Chromium directly: 85 | ``` 86 | $ pkcon install chromium 87 | $ sudo reboot 88 | ``` 89 | 90 | ### Installation: KDE 91 | 92 | * In _Discover_, enable the _flatpak_ repository. 93 | * For theming, normal theme installations don’t work in KDE Plasma. But you can install themes via a transactional-update shell: 94 | * (For example the Arc theme and papirus-icon-theme) 95 | ``` 96 | $ sudo transactional-update shell 97 | # cd /tmp 98 | # wget -qO- https://raw.githubusercontent.com/PapirusDevelopmentTeam/arc-kde/master/install.sh | sh 99 | # wget -qO- https://git.io/papirus-icon-theme-install | sh 100 | # exit 101 | $ sudo reboot 102 | ``` 103 | * Other themes (also for GNOME): 104 | * [Qogir-icon-theme](https://github.com/vinceliuice/Qogir-icon-theme) 105 | * [Matcha-gtk](https://github.com/vinceliuice/Matcha-gtk-theme) 106 | * [Matcha-KDE](https://github.com/vinceliuice/Matcha-kde) 107 | * [Akwa-gtk](https://github.com/berkiyo/akwa) 108 | 109 | ### General tips 110 | Updates are now to be initialized manually with: 111 | ``` 112 | $ sudo transactional-update dup 113 | $ sudo reboot 114 | ``` 115 | Or 116 | ``` 117 | $ sudo transactional-update shell 118 | # zypper dup 119 | # exit 120 | $ sudo reboot 121 | ``` 122 | Or 123 | ``` 124 | $ pkcon update 125 | ``` 126 | Or 127 | ``` 128 | $ sudo tukit execute bash 129 | # zypper dup 130 | # exit 131 | $ sudo reboot 132 | ``` 133 | #### Useful extra packages to install 134 | 135 | Some useful extra packages to install include: 136 | 137 | * `ntfs-3g ` for NTFS partitions 138 | * `fuse-exfat` for exfat partitions 139 | * `nano` instead of vim 140 | 141 | You can install both with: 142 | ``` 143 | $ pkcon install tlp ntfs-3g fuse-exfat nano 144 | $ sudo reboot 145 | ``` 146 | 147 | 148 | ### Installing flatpaks 149 | 150 | The `flatpak` package is already installed and the flathub repo enabled within a Gnome install. Within KDE Plasma it is possible to enable the flathub repo from within _Discover_. 151 | 152 | Updating flatpaks via the terminal are done with the command `sudo flatpak update` 153 | 154 | Some flatpaks you could install from [flathub](https://flathub.org/home): 155 | 156 | - [Firefox](https://flathub.org/apps/details/org.mozilla.firefox) 157 | - [Libreoffice](https://flathub.org/apps/details/org.libreoffice.LibreOffice) 158 | - [VLC](https://flathub.org/apps/details/org.videolan.VLC) 159 | - etc. 160 | 161 | ### Installing snaps 162 | 163 | Snaps are mainly used with Ubuntu, but it is possible to install them as well in openSUSE MicroOS with the following commands. 164 | !!! info 165 | _It is NOT recommended to install snaps on openSUSE MicroOS, there is a possibility this will break during an update or reboot_ 166 | 167 | First, Snapd must be installed on the system with transactional-update: 168 | 169 | ``` 170 | $ sudo tukit execute bash 171 | # zypper addrepo --refresh https://download.opensuse.org/repositories/system:/snappy/openSUSE_Tumbleweed snappy 172 | # zypper --gpg-auto-import-keys refresh 173 | # zypper ref 174 | # zypper dup --from snappy 175 | # zypper in snapd 176 | # exit 177 | $ sudo reboot 178 | ``` 179 | 180 | After a reboot, snapd will be installed. Files installed from Snapd will be contained in the [/snap directory](https://snapcraft.io/docs/system-snap-directory) which can be created as a subvolume on MicroOS. 181 | 182 | ``` 183 | $ source /etc/profile 184 | $ sudo mksubvolume /snap 185 | ``` 186 | 187 | Ubuntu uses [AppArmor](https://ubuntu.com/server/docs/security-apparmor) to handle permissions of Snap applications. Ensure AppArmor is enabled with `sudo systemctl status apparmor` - if systemd shows AppArmor is stopped, start it now (and on every boot) with `sudo systemctl enable --now apparmor.service` 188 | 189 | Once AppArmor is running, Snapd can be started with: 190 | 191 | ``` 192 | $ sudo systemctl enable --now snapd 193 | $ sudo systemctl enable --now snapd.apparmor 194 | ``` 195 | You can install snaps via the terminal (for example the snap store where you can find snaps and install them via a graphical interface): 196 | ``` 197 | $ sudo snap install snap-store 198 | ``` 199 | 200 | ### Installing virtualbox 201 | ``` 202 | $ sudo tukit execute bash 203 | # zypper ref 204 | # zypper in virtualbox-qt 205 | # usermod -a -G vboxusers 206 | # exit 207 | $ sudo reboot 208 | ``` 209 | 210 | #### Adding the extension pack for the host 211 | _Installation can be done after you've rebooted into a new snapshot where virtualbox-qt is installed_ 212 | ``` 213 | $ sudo tukit execute bash 214 | # cd /tmp 215 | # LatestVirtualBoxVersion=$(wget -qO - https://download.virtualbox.org/virtualbox/LATEST-STABLE.TXT) && wget "https://download.virtualbox.org/virtualbox/${LatestVirtualBoxVersion}/Oracle_VM_VirtualBox_Extension_Pack-${LatestVirtualBoxVersion}.vbox-extpack" 216 | # VBoxManage extpack install --replace Oracle_VM_VirtualBox_Extension_Pack-${LatestVirtualBoxVersion}.vbox-extpack 217 | # exit 218 | $ sudo reboot 219 | ``` 220 | 221 | ### Adding software from OBS 222 | Find what you need on [https://software.opensuse.org](https://software.opensuse.org). Then choose the openSUSE Tumbleweed repository, as MicroOS desktop is built from the same base as Tumbleweed. Everything that runs on Tumbleweed should in theory run reliably on MicroOS Desktop. 223 | 224 | You can't use the 1-click install as there is no YaST and the 1-click installer has no access to a transactional-update. So for example if you install `zerotier`: 225 | 226 | 1. Pick a _TumbleWeed_ repository. 227 | 2. Click on _Expert Download_. 228 | 3. Choose the option _Add repository and install manually_. 229 | 4. Copy the commands into a _transactional-update shell_ 230 | ``` 231 | $ sudo tukit execute bash 232 | # zypper addrepo -cf https://download.opensuse.org/repositories/home:alphard:RHEL/openSUSE_Tumbleweed/home:alphard:RHEL.repo 233 | # zypper ref 234 | # zypper in zerotier-one 235 | # exit 236 | $ sudo reboot 237 | ``` 238 | If you have added repositories to `zypper` by yourself, it is possible that they will not refresh automatically with a `dup` command. You will have to give them a flag for autorefresh: (or add the `-cf` to the command after `addrepo` or `ar`) 239 | ``` 240 | $ sudo tukit execute bash 241 | # zypper lr -p 242 | # zypper mr -f 243 | # exit 244 | $ sudo reboot 245 | ``` 246 | 247 | ### Tips if you're installing on laptop 248 | Two important packages were found missing for some users: 249 | 250 | * `tlp` for better battery management 251 | * `ModemManager` for laptops with a WWAN modem 252 | 253 | You can install both with: 254 | ``` 255 | $ pkcon install tlp ModemManager libmbim usb_modeswitch NetworkManager-connection-editor 256 | $ sudo reboot 257 | ``` 258 | 259 | ### Some useful aliases for bash to type the commands faster 260 | Edit the file `~/.bashrc` 261 | 262 | And add the following lines in the file at the end: 263 | ``` 264 | #My custom aliases 265 | alias shalt="sudo systemctl halt" 266 | alias sboot="sudo systemctl reboot" 267 | alias pu="pkcon update" 268 | alias steb="sudo tukit execute bash" 269 | alias sts="sudo transactional-update shell" 270 | alias stsc="sudo transactional-update shell --continue" 271 | alias stdc="sudo transactional-update dup --continue" 272 | alias std="sudo transactional-update dup" 273 | alias sfu="sudo flatpak update -y && flatpak update -y" 274 | alias fsu="sudo flatpak update -y && flatpak update -y && sudo snap refresh" 275 | alias dfs="pkcon update && sudo flatpak update -y && flatpak update -y && sudo snap refresh" 276 | ``` 277 | Then for example typing `std` in a terminal prompt will issue the command `sudo transactional-update dup`. 278 | 279 | ## Known Issues 280 | ### No graphical session/login screen in Hyper-V 281 | _Hyper-V_ requires the package `xf86-video-fbdev` for graphical session: 282 | ``` 283 | $ pkcon install xf86-video-fbdev 284 | $ sudo reboot 285 | ``` 286 | 287 | ### Toolbox is not starting ("potentially insufficient UIDs and GIDs") 288 | UUI and GUI need to be set for `toolbox` to work: 289 | ``` 290 | $ sudo tukit execute bash 291 | # echo ":100000:65536" > /etc/subuid 292 | # echo ":100000:65536" > /etc/subgid 293 | # exit 294 | $ sudo reboot 295 | ``` 296 | 297 | ### Graphical applications in the toolbox are missing fonts/icons 298 | They need to be installed inside the toolbox: 299 | ``` 300 | sudo zypper install xorg-x11-fonts-core adwaita-icon-theme 301 | ``` 302 | 303 | ## Alternative for Gnome Extensions 304 | There is an alternative to installing GNOME Extensions, such that no RPM installed browser is necessary. It's currently under development at [Github](https://github.com/ekistece/GetExtensions). You can install it via `toolbox`; the commands are as follows: 305 | ``` 306 | $ toolbox -u 307 | $ sudo zypper in git python38-pip 308 | $ cd /tmp 309 | $ git clone https://github.com/ekistece/GetExtensions.git 310 | $ pip3 install ./GetExtensions --user 311 | $ exit 312 | ``` 313 | You can then open the application _Get Extensions_ that is available from your launchpad. 314 | 315 | To uninstall: 316 | ```pip3 uninstall getextensions``` 317 | 318 | 319 | Old items: 320 | It is recommended to disable both automatic updating and automatic rebooting. They are handy features for servers running 24/7), but the developers are thinking about a different and better integration with desktop usage. For now it is recommended to do the same, at least until you have become more familiar with MicroOS. Then you will be able to come up with the best automatic updating & rebooting strategy for your workflow and use case. So: 321 | ``` 322 | $ sudo systemctl disable --now transactional-update.timer 323 | $ sudo systemctl disable --now rebootmgr.service 324 | ``` 325 | And then let’s check: 326 | ``` 327 | $ sudo rebootmgrctl is-active 328 | *RebootMgr is dead* 329 | $ sudo rebootmgrctl status 330 | *Error: The name org.opensuse.RebootMgr was not provided by any .service files* 331 | ``` 332 | For GNOME you have to use one of the two options below (also possible for a terminal prompt if you don't like Discover): 333 | 334 | If you want to install flathub for only your user (in `/home/~ folder`): 335 | ``` 336 | $ flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo 337 | ``` 338 | Updating flatpaks via the terminal are done with the command `flatpak update` 339 | 340 | If you want to install flathub for all users (in `/var folder`): 341 | ``` 342 | $ flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo 343 | ``` 344 | -------------------------------------------------------------------------------- /project/docs/pick_an_image.md: -------------------------------------------------------------------------------- 1 | # Choosing a distribution 2 | ## openSUSE distributions 3 | If you are a desktop user, openSUSE offers the choice between two Linux distributions designed to meet your needs: 4 | 5 | * [Tumbleweed](https://software.opensuse.org/distributions/tumbleweed) 6 | * [Leap](https://software.opensuse.org/distributions/leap) 7 | 8 | ### Tumbleweed 9 | Tumbleweed is a _rolling-release_ distribution: instead of having fixed points where you will be offered to perform a system upgrade (think of Windows, Ubuntu, or macOS, where each numbered version leads to the next), you will be frequently offered to upgrade multiple components of your system. 10 | 11 | ???+ info 12 | Those components are called _packages_, because they "pack" the programs and resources making up most of your system, along with tools to install them). "Upgrading" means "Upgrading packages" (such as those that constitute your Linux distribution). 13 | 14 | Even though Tumbleweed uses a rolling-release model, it is very stable: openSUSE thoroughly tests every package before going into an update, ensuring the stability of your system. Moreover you can always revert back to the previous state of Tumbleweed (in jargon: "switch to the previous snapshot". Snapshots are explained [here](snapper.md)). 15 | 16 | What you have to bear in mind, however, is that Tumbleweed requires a reliable internet connection and a healthy hard drive to work as designed. It also requires that you sometimes take interest in the updating process. 17 | 18 | ### Leap 19 | Leap is a more traditional distribution: it uses a fixed-points release model, just like Windows, Ubuntu, or macOS. Leap is a very battle-hardened operating system, mostly made up of packages brought over from SUSE Linux Enterprise, a commercial Linux operating system for servers, and of packages from Tumbleweed after they were tested, tried and used by the community. 20 | 21 | It is worth noting that Leap provides a Linux kernel that is several years behind the version offered by Tumbleweed. 22 | 23 | ???+ info 24 | The kernel is the heart of any Linux operating system. It translates your keystrokes and mouse clicks into the ones and zeros the computer understands, and is updated regularly so that the computer can respond to new hardware added to the system. 25 | 26 | This means that you might be better served by Tumbleweed if you have a recent computer or rely extensively on "exotic" hardware. 27 | 28 | ### Our recommendation 29 | Pick Tumbleweed if you intend to use your machine as a desktop machine unless: 30 | 31 | * You have a very limited bandwidth or an unreliable access to the Internet. 32 | * You have an old (7+ years old mechanical hard drive that will struggle with frequent, numerous updates. 33 | * You cannot afford to reboot your computer frequently to install updates. 34 | * You don't want to use, or switch between, different snapshots. 35 | * Your rely on specific versions of important packages, including hardware drivers, and generally speaking you don't want or cannot take advantage of recent packages, including recent kernels. 36 | * You would rather not do package management manually and more generally, you would rather avoid using the command line. 37 | 38 | The more conditions apply to your use case, the stronger we recommend you to install Leap instead of Tumbleweed. 39 | 40 | ???+ info 41 | It is not recommended for new users, however, it is possible to use microOS on a desktop computer, taking advantage of transactional updates. This might appeal to advanced users who want to provide friends or relatives with an operating system that will require little to no maintenance. You might be interested in [our microOS documentation](microos_getting_started.md) for more about this use case. 42 | 43 | ## Desktop Environments 44 | Leap offers the __GNOME__ and __KDE Plasma__ desktop environments by default. Tumbleweed offers __GNOME__, __KDE Plasma__, and __XFCE__. These options are chosen during the __System Role__ section of the installation. Additional options are available in the __Software__ selection of the installer. These desktop environment patterns may also be viewed and modified with the [YaST](/yast/) __Software Management__ module. 45 | 46 | Modern desktop environments have evolved into highly consistent and productive computing experiences. Choosing the right desktop environment for you can be a deeply personal experience; many people feel as passionately about their desktop environment as they do their distribution. 47 | 48 | One of the distinguishing options of openSUSE, during the installation, is the ability to choose a desktop environment. This provides a certain level of assurance that you will have a well-supported desktop experience for that desktop environment, no derivatives or spin-offs needed. 49 | 50 | ## Installation 51 | 52 | During __openSUSE Installation__, there is a section titled __System Role__, which applies patterns to the software selected for the respective installation. This is the primary means to select a desktop environment. There is an additional option titled __Generic Desktop__. If you wish to install a desktop environment available in the installer, but not in the __System Role__, you can select __Generic Desktop__ and customize the Software selection later within the installer. 53 | 54 | The descriptions below are as provided by the respective projects. 55 | 56 | ### GNOME 57 | > GNOME 3 has been designed from the ground up to help you have the best possible computing experience. 58 | > 59 | > GNOME 3 provides a focused working environment that helps you to get things done, and it is packed with features that will make you more productive. A powerful search feature lets you access all your work from one place. Side-by-side windows makes it easy to view several documents at the same time, and we even provide a way to turn off notifications when you really need to concentrate on the task in hand. 60 | > 61 | > [GNOME.org](https://www.gnome.org) 62 | 63 | ???+ info "Install Gnome" 64 | __Installer__ > __System Role__: Select __Desktop with GNOME__ 65 | 66 | ### KDE Plasma 67 | > Plasma is made to stay out of the way as it helps you get things done. But under its light and intuitive surface, it's a powerhouse. So you're free to choose ways of usage right as you need them and when you need them. 68 | > 69 | > With Plasma the user is king. Not happy with the color scheme? Change it! Want to have your panel on the left edge of the screen? Move it! Don't like the font? Use a different one! Download custom widgets in one click and add them to your desktop or panel. 70 | > 71 | > [KDE.org](https://kde.org) 72 | 73 | ???+ info "Install KDE Plasma" 74 | __Installer__ > __System Role__: Select __Desktop with KDE Plasma__ 75 | 76 | ### XFCE 77 | > XFCE is a lightweight desktop environment for UNIX-like operating systems. It aims to be fast and low on system resources, while still being visually appealing and user friendly. 78 | > 79 | > XFCE embodies the traditional UNIX philosophy of modularity and re-usability. It consists of a number of components that provide the full functionality one can expect of a modern desktop environment. They are packaged separately and you can pick among the available packages to create the optimal personal working environment. 80 | > 81 | > Another priority of XFCE is adherence to standards, specifically those defined at [freedesktop.org](https://www.freedesktop.org). 82 | > 83 | > [XFCE.org](https://www.xfce.org) 84 | 85 | ???+ info "Install XFCE" 86 | Tumbleweed: 87 | 88 | * __Installer__ > __System Role__: Select __Desktop with Xfce__ 89 | 90 | Leap: 91 | 92 | * __Installer__ > __System Role__: Select __Generic Desktop__ 93 | * __Installer__ > __Installer Settings__: Select __Software__ 94 | * __Installer__ > __Software Selection and System Tasks__: 95 | * De-Select __A very basic desktop__ 96 | * Select __XFCE Desktop Environment__ 97 | 98 | !!! note 99 | Clicking the __Details...__ button on __Installer__ > __Software Selection and System Tasks__ displays packages associated with the respective patterns. 100 | 101 | ### Generic Desktop 102 | Another option for a __System Role__ is the __Generic Desktop__ environment. This option enables __IceWM__, but also allows selection of one of the optional desktop environments later, during the __Software__ selection of the installation. If you intend to choose one of the other desktop environments, choose __Yes__, when asked "Activate online repositories now?" and ensure __Main Repository (OSS)__ is enabled on the __Online Repositories__ step. 103 | 104 | #### IceWM 105 | > IceWM is a window manager for the X Window System. The goal of IceWM is speed, simplicity, and not getting in the user’s way. It comes with a taskbar with pager, global and per-window keybindings and a dynamic menu system. Application windows can be managed by the keyboard and mouse. Windows can be iconified to the taskbar, to the tray, to the desktop or be hidden. They are controllable by a quick switch window (Alt+Tab) and in a window list. 106 | > 107 | > [Ice-WM.org](https://ice-wm.org/) 108 | 109 | ???+ info "Install IceWM" 110 | __Installer__ > __System Role__: Select __Generic Desktop__ 111 | 112 | ### Additional Choices 113 | Before confirming the installation, an overview is provided with the selected installation options, titled __Installer Settings__. At this point, you can modify the __Software__ selected to be installed. In addition to reducing or adding packages, you can also select other desktop environments to install. 114 | 115 | If you prefer one of these desktop environments, de-select the __A very basic desktop__ pattern, then select one of the below patterns: 116 | #### Enlightenment 117 | > Enlightenment is classified as a "desktop shell" as it provides everything you need to operate your desktop or laptop, but it is not a full application suite. This covers functionality including launching applications, managing their windows and performing system tasks like suspending, rebooting, managing files and so on. 118 | > 119 | >[Enlightenment.org](https://www.enlightenment.org) 120 | 121 | ???+ info "Install Enlightment" 122 | 123 | * __Installer__ > __System Role__: Select __Generic Desktop__ 124 | * __Installer__ > __Installer Settings__: Select __Software__ 125 | * __Installer__ > __Software Selection and System Tasks__: 126 | * De-Select __A very basic desktop__ 127 | * Select __Enlightenment__ 128 | 129 | !!! note 130 | Clicking the __Details...__ button on __Installer__ > __Software Selection and System Tasks__ displays packages associated with the respective patterns. 131 | #### LXDE 132 | > LXDE, which stands for Lightweight X11 Desktop Environment, is a desktop environment which is lightweight and fast. It is designed to be user friendly and slim, while keeping the resource usage low. LXDE uses less RAM and less CPU while being a feature rich desktop environment. Unlike other tightly integrated desktops LXDE strives to be modular, so each component can be used independently with few dependencies. This makes porting LXDE to different distributions and platforms easier. 133 | > 134 | > [LXDE.org](http://www.lxde.org/) 135 | 136 | ???+ info "Install LXDE" 137 | 138 | * __Installer__ > __System Role__: Select __Generic Desktop__ 139 | * __Installer__ > __Installer Settings__: Select __Software__ 140 | * __Installer__ > __Software Selection and System Tasks__: 141 | * De-Select __A very basic desktop__ 142 | * Select __LXDE Desktop Environment__ 143 | 144 | !!! note 145 | Clicking the __Details...__ button on __Installer__ > __Software Selection and System Tasks__ displays packages associated with the respective patterns. 146 | #### LXQt 147 | > LXQt is a Lightweight Qt Desktop Environment. It will not get in your way. It will not hang or slow down your system. It is focused on being a classic desktop with a modern look and feel. 148 | > Historically, LXQt is the product of the merge between LXDE-Qt, an initial Qt flavour of LXDE, and Razor-qt, a project aiming to develop a Qt based desktop environment with similar objectives as the current LXQt. 149 | > 150 | > [LXQt-Project.org](https://lxqt-project.org) 151 | 152 | ???+ info "Install LXQt" 153 | 154 | * __Installer__ > __System Role__: Select __Generic Desktop__ 155 | * __Installer__ > __Installer Settings__: Select __Software__ 156 | * __Installer__ > __Software Selection and System Tasks__: 157 | * De-Select __A very basic desktop__ 158 | * Select __LXQt Desktop Environment__ 159 | 160 | !!! note 161 | Clicking the __Details...__ button on __Installer__ > __Software Selection and System Tasks__ displays packages associated with the respective patterns. 162 | #### MATE 163 | > The MATE Desktop Environment is the continuation of GNOME 2. It provides an intuitive and attractive desktop environment using traditional metaphors for Linux and other Unix-like operating systems. 164 | > 165 | > MATE is under active development to add support for new technologies while preserving a traditional desktop experience. 166 | > 167 | > [Mate-Desktop.org](https://mate-desktop.org/) 168 | 169 | ???+ info "Install MATE" 170 | 171 | * __Installer__ > __System Role__: Select __Generic Desktop__ 172 | * __Installer__ > __Installer Settings__: Select __Software__ 173 | * __Installer__ > __Software Selection and System Tasks__: 174 | * De-Select __A very basic desktop__ 175 | * Select __MATE Desktop Environment__ 176 | 177 | !!! note 178 | Clicking the __Details...__ button on __Installer__ > __Software Selection and System Tasks__ displays packages associated with the respective patterns. 179 | #### Sway 180 | > Sway allows you to arrange your application windows logically, rather than spatially. Windows are arranged into a grid by default which maximizes the efficiency of your screen and can be quickly manipulated using only the keyboard. 181 | > 182 | > [SwayWM.org](https://swaywm.org/) 183 | 184 | ???+ info "Install Sway" 185 | 186 | * __Installer__ > __System Role__: Select __Generic Desktop__ 187 | * __Installer__ > __Installer Settings__: Select __Software__ 188 | * __Installer__ > __Software Selection and System Tasks__: 189 | * De-Select __A very basic desktop__ 190 | * Select __The openSUSEway desktop environment pattern__ 191 | 192 | 193 | !!! note 194 | Clicking the __Details...__ button on __Installer__ > __Software Selection and System Tasks__ displays packages associated with the respective patterns. 195 | 196 | ### Advanced Options 197 | #### Cinnamon 198 | > Cinnamon is a Linux desktop which provides advanced innovative features and a traditional user experience. 199 | > 200 | > The desktop layout is similar to Gnome 2 with underlying technology forked from Gnome Shell. Cinnamon makes users feel at home with an easy to use and comfortable desktop experience. 201 | > 202 | > [LinuxMint.com](https://projects.linuxmint.com/cinnamon/) 203 | 204 | ???+ info "Install Cinnamon" 205 | Tumbleweed: 206 | 207 | * __Installer__ > __System Role__: Select __Generic Desktop__ 208 | * __Installer__ > __Installer Settings__: Select __Software__ 209 | * __Installer__ > __Software Selection and System Tasks__: 210 | * De-Select __A very basic desktop__ 211 | * Ensure Selection of __X Windows System__ 212 | * Click __Details...__ 213 | * Click __Search__ tab 214 | * Search for and Select __cinnamon__ 215 | * Click __Accept__ and __Continue__ 216 | 217 | !!! note 218 | In this setup configuration, you shouldn't have any Desktop Environment patterns selected, unless you desire multiple desktop environments. 219 | 220 | Clicking the __Details...__ button on __Installer__ > __Software Selection and System Tasks__ displays packages associated with the respective patterns. 221 | -------------------------------------------------------------------------------- /project/docs/snapper.md: -------------------------------------------------------------------------------- 1 | ## Snapper 2 | Snapper is a tool for filesystem snapshot management. _Snapshots_ are fully defined state in your system at one point in time, just like a photography is a fully defined moment in a movie, for example. Snapper is able to create, delete and compare snapshots, and to undo changes that occurred between snapshots. It is thus a powerful maintenance tool that allows you to 'cheat' the flow of time: if you run into an outstanding bug you can use Snapper to _rollback_ to a past snapshot, typically one where the bug didn't exist yet. Or if you've already moved to a past snapshot, you are able to _switch_ move to a snapshot that lies in the 'future' relative to it. 3 | 4 | Snapper has both a __Command Line Interface__ (CLI) and __Graphical Interface__. Not all functionality is available through the graphical interface but inexperienced users should find it sufficient for basic tasks. 5 | 6 | Snapper is deeply integrated with the Btrfs filesystem, serving as an easy to use helper for the built in functions of Btrfs. The most common Btrfs tasks can be conducted with Snapper, however, there may be instances when it is necessary to interact with Btrfs directly. 7 | 8 | Tumbleweed users should note that understanding how to use Snapper is an important step in maintaining a stable, functional system. As a rolling release, Tumbleweed, is subjected to less testing overall and the occasional system breaking update can be installed. Such problems are quickly and easily resolved with Snapper. 9 | 10 | !!! info 11 | Even though Snapper is key to a healthy Tumbleweed experience, it also benefits Leap as it allows you to quickly recover from breakages occuring before login, typically involving the GRUB bootloader or the loading of the kernel with unhealthy parameter values. 12 | 13 | ### Snapper capabilities 14 | - Undo system changes made by `zypper` and YaST. 15 | - Restore files from previous snapshots. 16 | - Do a system rollback by booting from a snapshot. 17 | - Manually create and manage snapshots, within the running system. 18 | 19 | ### Defaults 20 | By default, openSUSE Tumbleweed formats your hard drive with the Btrfs filesystem which provides the powerful snapshot capabilities. Snapshots are automatically enabled for the root partition `/`. 21 | 22 | The default snapshot configuration should only be changed by experienced users but it is important to note some default behaviour for new users as well. 23 | 24 | * Snapshots are automatically enabled for the root `/` partition if it is larger than 16 Gigabytes. This is to ensure there is enough disk space for the snapshots and important system tasks to occur, which may include moving, writing or deleting files. 25 | 26 | * If the root `/` partition is smaller than 16 Gigabytes a different kind of snapshot is used, known as "Timeline Snapshots". These snapshots are created every hour. By default only the first snapshot of the last ten days, months, and years are kept. This ensures there are some snapshots for system rollbacks while taking up very minimal disk space. 27 | 28 | * The users `/home` directory is not included in snapshots and should not be relied on as a data backup for personal files. This prevents data loss if a system rollback is conducted. Changes to personal files would also be "undone". 29 | 30 | * Directories `/opt` and `/usr/local`, where various software and third-party products are installed are not included in snapshots by default. This prevents uninstalling the software if a system rollback is conducted. 31 | 32 | ### Snapshot Types 33 | `snapper` features 3 types of snapshots: _Timeline_, _Installation_, and _Administration_. 34 | 35 | * __Timeline__ snapshots are single snapshots, created every hour and old snapshots are automatically deleted. By default, the first snapshot of the last ten days, months, and years are kept. Disabled by default on partitions larger than 16 Gigabytes. The only single snapshots present may be the ones created when openSUSE was installed. 36 | * __Installation__ snapshots are created in pairs (_Pre_ and _Post_) when packages are installed with YaST or Zypper. Snapshot pairs are marked as __important__ if an important system component, such as the kernel, has been installed. Enabled by default. 37 | * __Administration__ snapshots are created in pairs (_Pre and Post_) when system administration is performed using YaST. The Pre snapshot is created when a YaST module is started and the Post snapshot is created when the module is closed. Enabled by default. 38 | 39 | !!! note 40 | By default, the last ten important and the last ten regular snapshot pairs are kept. This total encompasses both Installation and Administration snapshot types. Snapshots are automatically deleted when they take up too much space on the disk, but four important and two regular snapshots are always kept. 41 | 42 | ### Configuring Snapper 43 | By default Snapper is configured for access with sudo privileges (typically `root`). This is because under the hood Snapper works hand-in-hand with the Btrfs file system, which is set up for `root`. Thus in this section we will assume that you will use Snapper accordingly. 44 | 45 | To get started you can display all current configurations: 46 | 47 | `$ sudo snapper list-configs` 48 | 49 | That would typically return: 50 | 51 | ``` 52 | Configuration | Subvolume 53 | --------------+------------ 54 | root | / 55 | ``` 56 | 57 | To show this configuration, we is by default the current user's configuration: 58 | 59 | `$ sudo snapper -c root get-config` 60 | 61 | returning for example: 62 | 63 | ``` 64 | -----------------------+------- 65 | ALLOW_GROUPS | 66 | ALLOW_USERS | 67 | BACKGROUND_COMPARISON | yes 68 | EMPTY_PRE_POST_CLEANUP | yes 69 | EMPTY_PRE_POST_MIN_AGE | 1800 70 | FREE_LIMIT | 0.2 71 | FSTYPE | btrfs 72 | NUMBER_CLEANUP | yes 73 | NUMBER_LIMIT | 4 74 | NUMBER_LIMIT_HOURLY | 3 75 | NUMBER_LIMIT_IMPORTANT | 2 76 | NUMBER_MIN_AGE | 1800 77 | QGROUP | 1/0 78 | SPACE_LIMIT | 0.2 79 | SUBVOLUME | / 80 | SYNC_ACL | no 81 | TIMELINE_CLEANUP | yes 82 | TIMELINE_CREATE | no 83 | TIMELINE_LIMIT_DAILY | 10 84 | TIMELINE_LIMIT_HOURLY | 10 85 | TIMELINE_LIMIT_MONTHLY | 10 86 | TIMELINE_LIMIT_WEEKLY | 0 87 | TIMELINE_LIMIT_YEARLY | 10 88 | TIMELINE_MIN_AGE | 1800 89 | ``` 90 | 91 | Notice the snapshot types discussed in the previous section, but don't take this for reference (you will want superior values for the `NUMBER_LIMITS` options). 92 | 93 | To change a value, do 94 | 95 | `$ sudo snapper -c root set-config "{option name}={new value}"` 96 | 97 | as in: 98 | 99 | `$ sudo snapper -c root set-config "NUMBER_LIMIT=4"` 100 | 101 | You can create configuration profiles for various purposes. To create a new profile, do 102 | 103 | `$ sudo snapper -c create-config ` 104 | 105 | as in: 106 | 107 | `$ sudo snapper -c foo create-config /foo` 108 | 109 | You can later remove any config with: 110 | 111 | `$ sudo snapper -c delete-config ` 112 | 113 | as in: 114 | 115 | `$ sudo snapper -c foo delete-config /foot` 116 | 117 | ### Creating and Deleting Snapshots 118 | You can create snapshots at any time. For example, to create a new snapshot for `root` (the default consumer of snapshots on openSUSE distributions): 119 | 120 | `$ sudo snapper -c root create -d ""` 121 | 122 | or more tersely: 123 | 124 | `$ sudo snapper create -d ""` 125 | 126 | !!! info 127 | Notice the `" "` surrounding the placeholder. It's a good practice to wrap text strings in this way, so as to make it easier to discern them from other types of values. 128 | 129 | It's advisable to use a meaningful description to make it easier to recognize your manually created snapshots later. 130 | 131 | To remove a snapshot, regardless of whether it was automatically or manually created, do: 132 | 133 | `$ sudo snapper -c / delete ` 134 | 135 | or the terser 136 | 137 | `$ sudo snapper delete ` 138 | 139 | ### Rolling back 140 | #### Identifying Snapshots 141 | 142 | There are two ways to identify which snapshot you may want to rollback to: 143 | * with the `snapper` command line utility 144 | * with the _YaST_ utility at _YaST_ > _Filesystem Snapshots_ 145 | 146 | Snapper command line: 147 | 148 | `$ sudo snapper list` 149 | 150 | __Snapper CLI Example__ 151 | ``` 152 | $ sudo snapper list 153 | [sudo] password for root: 154 | # | Type | Pre # | Date | User | Cleanup | Description | UserData 155 | ----+--------+-------+---------------------------------+------+---------+-----------------------+-------------- 156 | 0 | single | | | root | | current | 157 | 1* | single | | Thu 17 Dec 2020 10:59:10 PM MST | root | | first root filesystem | 158 | 2 | single | | Fri 18 Dec 2020 12:02:05 AM MST | root | number | after installation | important=yes 159 | 39 | pre | | Sat 19 Dec 2020 01:58:34 PM MST | root | number | zypp(zypper) | important=no 160 | 40 | post | 39 | Sat 19 Dec 2020 01:58:54 PM MST | root | number | | important=no 161 | 41 | pre | | Sat 19 Dec 2020 01:59:02 PM MST | root | number | zypp(zypper) | important=no 162 | 42 | post | 41 | Sat 19 Dec 2020 01:59:59 PM MST | root | number | | important=no 163 | 43 | pre | | Sun 20 Dec 2020 05:30:27 PM MST | root | number | yast firewall | 164 | 44 | pre | | Sun 20 Dec 2020 05:31:17 PM MST | root | number | yast firewall | 165 | 45 | post | 43 | Sun 20 Dec 2020 05:31:17 PM MST | root | number | | 166 | 46 | post | 44 | Sun 20 Dec 2020 05:31:38 PM MST | root | number | | 167 | 47 | pre | | Sun 20 Dec 2020 05:36:25 PM MST | root | number | zypp(zypper) | important=no 168 | 48 | post | 47 | Sun 20 Dec 2020 05:37:00 PM MST | root | number | | important=no 169 | 49 | pre | | Tue 22 Dec 2020 07:40:20 PM MST | root | number | yast snapper | 170 | 50 | pre | | Tue 22 Dec 2020 07:42:33 PM MST | root | number | zypp(zypper) | important=yes 171 | 51 | post | 50 | Tue 22 Dec 2020 07:46:28 PM MST | root | number | | important=yes 172 | 173 | ``` 174 | __Snapper YaST interface example__ 175 | 176 | ![YaST filesystem snapshots](image/snapper_post_zypper.png) 177 | 178 | !!! note 179 | As snapshots are viewed, `snapper` will create more snapshots, because administrative tasks are being performed. 180 | 181 | Moving forward with the assumption there was an issue with the last `zypper` update, #47 is chosen as the snapshot to recover. 182 | 183 | #### Initiating a rollback 184 | Upon identification of a recovery snapshot, reboot openSUSE. At the boot menu, scroll down to, and select, __Start bootloader from a read-only snapshot__. 185 | 186 | ![Boot Menu Selection](image/snapper_boot_selection.png) 187 | 188 | On the Read-only Snapshot menu, scroll down to, and select, the desired recovery snapshot. Snapshot #47 is used here as an example. openSUSE will appear to boot as normal. 189 | 190 | !!! tip 191 | There isn't a scroll indicator on the Read-only Snapshot Menu, but it is possible to scroll down to select more options, if available. 192 | 193 | ![Boot Snapshot Selection](image/snapper_snapshot_selection.png) 194 | 195 | #### Confirming a rollback 196 | Once your system has booted, make sure you're satisfied with the current state of your system. Run some tests. Make sure any outstanding bug is not or no longer present. Then if you're satisfied, perform the rollback: 197 | 198 | `$ sudo snapper rollback` 199 | 200 | Your system should then be rebooted and the recovered snapshot will be the new default boot option. 201 | 202 | In rare cases rolling back with fail as snapper is not able to find the default sub-volume (this may happen if snapper's configuration and the state of your system have diverged in a problematic way, typically if you've made a mistake by accident). To perform a rollack nonetheless you can use the following command: 203 | 204 | `$ sudo snapper --ambit classic rollback ` 205 | 206 | replacing `` with the id of the snapshot you wish to roll back to. 207 | 208 | ### Disk Space Management 209 | Snapshots don't occupy much space but certain configurations might still want to remove uneeded snapshots to preventing running out of disk space. 210 | 211 | Start with a simple list: 212 | 213 | `$ sudo snapper list` 214 | 215 | The list features a column mentioning an estimate of the space occupied by each snapshot. You can remove unneeded snapshots with 216 | 217 | `$ sudo snapper delete ` 218 | 219 | You will find the value of `` in the first column ('#'). 220 | 221 | 222 | ### Subvolumes Health Check 223 | For illustration here is a healthy structure of subvolumes obtained with 224 | 225 | `$ sudo btrfs subvolume list -p /` 226 | 227 | ``` 228 | ID 256 gen 70064 parent 5 top level 5 path @ 229 | ID 257 gen 198577 parent 256 top level 256 path @/var 230 | ID 258 gen 198574 parent 256 top level 256 path @/usr/local 231 | ID 259 gen 198574 parent 256 top level 256 path @/srv 232 | ID 260 gen 198574 parent 256 top level 256 path @/root 233 | ID 261 gen 198574 parent 256 top level 256 path @/opt 234 | ID 262 gen 198577 parent 256 top level 256 path @/home 235 | ID 263 gen 198574 parent 256 top level 256 path @/boot/grub2/x86_64-efi 236 | ID 264 gen 198574 parent 256 top level 256 path @/boot/grub2/i386-pc 237 | ID 265 gen 198573 parent 256 top level 256 path @/.snapshots 238 | ID 1034 gen 198573 parent 265 top level 265 path @/.snapshots/224/snapshot 239 | ID 1141 gen 195869 parent 265 top level 265 path @/.snapshots/325/snapshot 240 | ID 1142 gen 195876 parent 265 top level 265 path @/.snapshots/326/snapshot 241 | ID 1143 gen 196235 parent 265 top level 265 path @/.snapshots/327/snapshot 242 | ID 1144 gen 196320 parent 265 top level 265 path @/.snapshots/328/snapshot 243 | ``` 244 | 245 | Notice how all snapshots are immediately nested under `@/.snapshots/`. If your structure does not match this, you should probably sanitize it. Generally unhealthy structures have the shape: 246 | 247 | `@/.snapshots//` 248 | 249 | where `` is anything else than just `snapshot`. If you happen to be in this situation consider removing all badly nested snapshots with: 250 | 251 | `$ sudo btrfs subvolume delete -i ` 252 | 253 | as in for example: 254 | 255 | `sudo btrfs subvolume delete -i 1031 /.snapshots/171/snapshot/.snapshots/420/snapshot/.snapshots/1/snapshot`. 256 | 257 | You might also want to make sure the `/.snapshots` entry point is correctly registered against `fstab`: 258 | 259 | `$ cat /etc/fstab` 260 | 261 | `UUID=22e658f2-1586-4ac2-8aeb-a6862c8c9a25 /.snapshots btrfs subvol=/@/.snapshots 0 0` 262 | 263 | If this is not the case edit the `fstab` file accordingly: 264 | 265 | `$ sudo nano /etc/fstab` 266 | 267 | pasting on a new line 268 | 269 | `UUID={your UUID} /.snapshots btrfs subvol=/@/.snapshots 0 0` 270 | 271 | where the value of your UUID can be determined simply by copying from neighbour lines in the file. Look in particular for lines meeting in the pattern: 272 | 273 | ``` 274 | UID=22e658f2-1586-4ac2-8aeb-a6862c8c9a25 /var btrfs subvol=/@/var 0 0 275 | UUID=22e658f2-1586-4ac2-8aeb-a6862c8c9a25 /usr/local btrfs subvol=/@/usr/local 0 0 276 | UUID=22e658f2-1586-4ac2-8aeb-a6862c8c9a25 /srv btrfs subvol=/@/srv 0 0 277 | UUID=22e658f2-1586-4ac2-8aeb-a6862c8c9a25 /root btrfs subvol=/@/root 0 0 278 | UUID=22e658f2-1586-4ac2-8aeb-a6862c8c9a25 /opt btrfs subvol=/@/opt 0 0 279 | UUID=22e658f2-1586-4ac2-8aeb-a6862c8c9a25 /home btrfs subvol=/@/home 0 0 280 | ``` 281 | 282 | ### Further reading 283 | * [Snapper.io](http://snapper.io "Snapper.io") 284 | * [openSUSE Wiki Portal:Snapper](https://en.opensuse.org/Portal:Snapper "openSUSE Wiki Portal:Snapper") 285 | -------------------------------------------------------------------------------- /project/docs/alternative_procurement.md: -------------------------------------------------------------------------------- 1 | # Obtaining software 2 | 3 | ## Introduction 4 | 5 | When it comes at getting software, modern Linux operating systems have access to a wide array of methods and formats. The openSUSE distributions are no exception: 6 | 7 | * the official and unofficial repositories, which you interact with from zypper, and which provide binaries packaged as RPMs files 8 | * third-party providers, which you interact with from a command prompt through `wget` or `curl` or `git`, and which either provide you with a complete installation solution, including binaries and installation scripts, or include just the source files along with build scripts 9 | * _flatpaks_, which you typically interact with from the `flatpak` command line utility, providing you containerized applications along with all their dependencies 10 | * _Ubuntu snaps_, which you install from the `snapd` command line utility, providing you (just like flatpaks) containerized applications with their dependencies 11 | * _AppImages_, which you manually download from websites and various hosts, providing you with a single executable file which your system will treat as an application, much like what you would see in a macOS environment 12 | 13 | The goal of this document is to help you understand these various formats and methods, as well as their strong and weak points, so that you can seamlessly include them in your daily usage. Assuming you are using an openSUSE distribution, we will make a few recommendations specific to these distributions along the way. 14 | 15 | ## Official and third-party repositories (.rpm) 16 | 17 | `.rpm` packages are the traditional and most common way of obtaining new software on openSUSE distributions. You are likely already familiar with the method for obtaining these packages, but to be sure: 18 | 19 | 1. Find the repository providing the package you are looking for. 20 | * If the package is provided by an official repository, such as http://download.opensuse.org/update/tumbleweed/, (use `zypper lr -d` to show the exact endpoint of all your repositories), then the desired package will show up in `zypper search `. 21 | * If the package is _not_ provided by an official repository, you will need to first add the repository. 22 | 2. Install the target package with `sudo zypper in `. In certain cases you won't know the exact name of the package, so after adding the corresponding repository you can simply do `sudo zypper dup` to make sure that the package is installed among all the pending updates. 23 | 24 | ### Detailed instructions for external repositories 25 | 26 | Certain application providers provide you with an `.rpm` file that will automatically add the require repository and install the desired application. When so you can simply point __zypper__ to the said file and install from there, as in: 27 | 28 | ``` 29 | cd ~/Downloads 30 | sudo zypper in .rpm 31 | ``` 32 | 33 | When doing so make sure the package is safe and the provider trustworthy. Most trustworthy providers sign their `.rpm`s with cryptographic keys, providing you with an `.asc` file containing a public key. You can the use the public key to verify the package, as in: 34 | 35 | ``` 36 | $ rpm --import .asc 37 | $ rpm --checksig .rpm 38 | ``` 39 | 40 | We recommend making sure that third-party repositories for the applications you use the most be added with the __refresh__ setting enabled, as in: 41 | 42 | ``` 43 | $ sudo zypper addrepo --refresh 44 | ``` 45 | 46 | On some configurations not doing so might result in `sudo zypper dup` not automatically acquiring new updates for the package provided by that repository. You can make sure your repositories __refresh__ automatically by listing them and paying attention at the (r) column -- the last -- obtained from `zypper lr`. 47 | 48 | ### Pros, cons, when 49 | 50 | __Pros__: 51 | 52 | * the most 'natural' way to install programs in the openSUSE ecosystem 53 | * has the best performance (startup time + execution speed) of all solutions 54 | * has the smallest footprint on your RAM and hard drive 55 | 56 | __Cons__: 57 | 58 | * heavily depends the libraries and other dependencies provided by your operating system, which means that drastic changes in your system-wide dependencies might prevent the program from running at all 59 | * depends on the availability of the distribution's packagers and maintainers, as opposed to solutions "closer" to the developers or that can benefit from cross-distribution maintainership (_flatpaks_, _AppImages_, _Ubuntu snaps_) 60 | 61 | __Go for it when__: 62 | 63 | * you are aiming for core utilities or libraries (e.g. _curl_, _gcc_, _python-devel_) and you know beforehand that you won't need to have several versions of these installed at the same time 64 | * you need maximal performance / minimal footprint 65 | * you can afford a marginally slower update pace than with other solutions 66 | 67 | ## Third-party remote providers 68 | 69 | We call _third-party remote providers_ as a catch-all term for websites, services or remote machines offering you an automatic installation solution provided by installation scripts provided along with the desired application. 70 | 71 | Since all the details fo the installation depends on custom made installation scripts, your experience with this method can vary significantly from one provider to another. Here your best bet is to thoroughly follow the instructions mentioned by the provider. For example, installing the Rust developer stack is a simple as copy-pasting into your command line the line: 72 | 73 | ``` 74 | $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 75 | ``` 76 | 77 | and following the interactive instructions. 78 | 79 | !!! warning 80 | Installation scripts might require sudo rights, so be mindful about what you are installing, and who you are installing from. 81 | 82 | ### Pros, cons, when 83 | 84 | __Pros__: 85 | 86 | * has the best performance (startup time + execution speed) of all solutions 87 | * has the smallest footprint on your RAM and hard drive 88 | 89 | __Cons__: 90 | 91 | * no control over the behaviour of the script -- especially if the script asks to be run as `sudo` -- which may incur some risk 92 | * heavily depends the libraries and other dependencies provided by your operating system, which means that drastic changes in your system-wide dependencies might prevent the program from running at all 93 | * depends on the availability of the distribution's packagers and maintainers, as opposed to solutions "closer" to the developers or that can benefit from cross-distribution maintainership (_flatpaks_, _AppImages_, _Ubuntu snaps_) 94 | 95 | __Go for it when__: 96 | 97 | * you are 100% sure you can trust the provider 98 | * you are aiming for core utilities or libraries (e.g. _curl_, _gcc_, _python-devel_) and you know beforehand that you won't need to have several versions of these installed at the same time 99 | * you need maximal performance / minimal footprint 100 | * you can afford a marginally slower update pace than with other solutions 101 | 102 | ## Flatpaks 103 | 104 | _Flatpak_ is a complete solution for installing, updating and running desktop applications from a containerized environment. It makes use of the following components: 105 | 106 | * the `flatpak` command line utility 107 | * a remote application store at https://flathub.org/home 108 | * application references, such as `com.spotify.Client`, organized by the flathub store 109 | * a local repository used to store applications along with their dependencies (by default, `/var/lib/flatpak`) 110 | 111 | On openSUSE distributions, you can install flatpak as follows: 112 | 113 | Install the command line utility (not required if it's installed already; to double-check see if `flatpak --version` returns something): 114 | ``` 115 | $ sudo zypper in flatpak 116 | ``` 117 | 118 | Add the flathub store as flatpak external repository: 119 | ``` 120 | $ flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo 121 | ``` 122 | 123 | And finally restart your system. From now on you will be able to install any of the very numerous apps provided from _flathub_, as in: 124 | ``` 125 | $ flatpak install --user flathub com.spotify.Client 126 | ``` 127 | 128 | Two things are important to bear in mind: 129 | 130 | 1. Using the `--user` flag is recommended for this reason: if the user has a separate `/home` and installs flatpaks using the `--user` flag, these applications will remain even after the entire file system is reinstalled, which means that the installed flatpaks can be reused after restoring the system. 131 | 2. Installing applications (with or without `--user` should automatically export a `.desktop` file to `/var/lib/flatpak/exports/share/applications` and add the corresponding symlinks to your system. This means applications will show up in your desktop environment's application launchers and other menus right after you have installed them (no reboot required). 132 | 133 | Updating your flatpaks is then as easy as: 134 | ``` 135 | $ flatpak update 136 | ``` 137 | 138 | To update a single flatpak application, do instead: 139 | ``` 140 | $ flatpak update 141 | ``` 142 | 143 | ### Additional details 144 | 145 | #### How it works 146 | 147 | The two main themes behind flatpaks are _binary versioning control_ and _containerization_. 148 | 149 | Binary versioning control (BVC) ensures that the system sees flatpak applications not just as a bunch of files with a given name, but in a way that tracks them against the context of a full versioning control system, such as Git. Flatpak applications are thus much like Git branches, in that they "wear their orgin up their sleeves". For example, the complete reference of the Spotify application on my machine as of this writing is: 150 | ``` 151 | $ flatpak list 152 | Spotify com.spotify.Client 1.1.55.498.gf9a83c60 stable system 153 | ``` 154 | 155 | which amounts to, in this order: a human-friendly name, the exact name as fixed by the provider, the (git) snapshot it is built from, the (git) branch hosting the snapshot (here _stable_), as well as the installation site on my machine (here, it is installed for the _system_, which means it can be run by any other user on my machine.) 156 | 157 | Under this constraint, any difference in the name or snapshot or branch or installation site will determine a different flatpak application reference. Two applications that are byte-for-byte identical will not collide with one another if they are different under other aspects of their reference. This means that, at any point, you can identify the portion of the codebase from which the application stems and that is relevant to the binary you are running. This also means you can have multiple versions of "the same" application through multiple application references. 158 | 159 | The other main theme behind flatpaks is containerization. Here it means that flatpak applications run in isolation from one another. This is made possible by taking advantage of the binary versioning control system mentioned above. Indeed, flatpak allows developers to specify a particular _runtime_ for their app, which is the context against which their applications is to run, and that serves as a proxy for the full operating system. Because of BVC developers are free to specify different runtimes for the same byte-to-byte identical binaries, or conversely, the same runtime for widely different binaries, should they happen to have similar requirements. The flatpak system then makes sure that runtimes meet the requirements of the applications they are associated with by their developers, and are executing in mutually inaccessible memory spaces. 160 | 161 | !!! info 162 | Even though the sharing of runtimes means that flatpak applications will share some of their dedependencies, there is no reliable way of ensuring that all their dependencies are thus shared, or that a developer has specified the same runtime as the one specified by the developers of the other flatpak applications installed by the user. This means that some duplication is to be expected, wasting some disk space. 163 | 164 | #### Improving desktop integration (KDE Plasma) 165 | 166 | The degree of independence that flatpaks enjoy with respect to the host operating system means that some frictions may occur now and then. This is particularily true for applications (or for runtimes) which do not always play nice with recent rendering and compositing frameworks. For example, drag-dropping a file for sending via a messaging application run as flatpak might not work as seamlessly as exepcted. For these corner cases, there is not much choice but to tinker with the runtime's parameters. 167 | 168 | Consider for example `org.telegram.desktop`. Should your version of this app seem to be affected by the above bug, you can try to run the application as: 169 | ``` 170 | $ flatpak run --env=QT_QPA_PLATFORM=xcb org.telegram.desktop 171 | ``` 172 | 173 | which basically instructs the runtime to use X11 instead of Wayland as the compositing client. They are countless other environment parameters you can use, and the right approach is usually to read the documentation and Git Issues of your favorite flatpak applications. 174 | 175 | !!! info 176 | Every single flatpak has is a public repository (often on GitHub) where you read Issues and participate to the conversation. Do not hesitate to go there now and then, as the tips you might learn are likely to serve you for many other flatpak applications. 177 | 178 | When you are satisfied with the results, you can attach a runtime setting to an application permanently to the current user as in: 179 | ``` 180 | $ flatpak override --user --env=QT_QPA_PLATFORM=xcb org.telegram.desktop 181 | ``` 182 | 183 | (Remove the --user flag to apply the override system-wide.) 184 | 185 | This will ensure that the application is always run with the corresponding environment parameter. More on the override option in the [official Flatpak documentation](https://docs.flatpak.org/en/latest/flatpak-command-reference.html?highlight=override#flatpak-override). 186 | 187 | #### Flatseal 188 | Please refer to Flatseal's [official documentation](https://github.com/tchx84/Flatseal/blob/master/DOCUMENTATION.md). 189 | 190 | ### Pros, cons, when 191 | 192 | __Pros__: 193 | 194 | * decent performance (it runs as fast as "bare" binaries and launches almost as fast) 195 | * excellent safety for your operating system (because most dependencies are not shared with the host operating system and because flatpaks installed with `--user` survive system reinstallations/restorations) 196 | * easy to update (`flatpak update`) 197 | 198 | __Cons__: 199 | 200 | * eats up significantly more hard drive space than the alternative methods and formats (because not all dependencies can be shared between flatpaks) 201 | * sometimes rough around the edges in terms of integration with the desktop environment 202 | 203 | __Go for it when__: 204 | 205 | * you are using many applications with a graphical interface and you don't want to expose them or your system to conflicts of dependencies (useful for Tumbleweed and microOS, whose core packages change frequently) 206 | * you want to have freshly updated and widely tested applications (the same as most other Linux distributions) 207 | * you plan on using many user applications (the more flatpaks you have, the more dependencies they can share) 208 | 209 | ## Snaps 210 | 211 | !!! warning 212 | Please help finish this section. 213 | 214 | ### Pros, cons, when 215 | 216 | !!! warning 217 | Please help finish this section. 218 | 219 | ## AppImages 220 | 221 | !!! warning 222 | Please help finish this section. 223 | 224 | ### Pros, cons, when 225 | 226 | !!! warning 227 | Please help finish this section. 228 | 229 | ## Summary and conclusion 230 | Even though Leap and Tumbleweed's official repositories are numerous, you will find yourself in search of alternatives at times. Here are some simple rules of thumbs that emerge from the Pros and cons discussed above: 231 | 232 | If you are looking for a program with a graphical interface that... 233 | 234 | 1. updates often; or 235 | 2. relies on very recent dependencies; or 236 | 3. requires you to install dependencies that: 237 | * are provided by the official repositories; but 238 | * differ in version from those provided by the official repositories; then 239 | you will be better off using ; then snaps, flapaks or appimages offer you serious alternatives to official repositories, which may update less frequently. This applies to both Leap and Tumbleweed's official repositories. 240 | 241 | When wondering which to use, between snaps, flatpaks and appimages: 242 | 243 | 1. favour __flatpaks__ if you want a streamlined experience or precise maintenance options via the command line or if you plan on using several other flatpaks (the more flatpaks, the most cost-efficient the sacrifice of storage space they demand) 244 | 2. favour __appimages__ if you need a handful of "fire-and-forget" or "portable" (no installation needed) applications. 245 | 246 | ## References 247 | * Comparison between AppImage, Flatpak and Ubuntu Snap: https://github.com/AppImage/AppImageKit/wiki/Similar-projects#comparison -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU Free Documentation License 2 | Version 1.2, November 2002 3 | 4 | 5 | Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 6 | 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 7 | Everyone is permitted to copy and distribute verbatim copies 8 | of this license document, but changing it is not allowed. 9 | 10 | 11 | 0. PREAMBLE 12 | 13 | The purpose of this License is to make a manual, textbook, or other 14 | functional and useful document "free" in the sense of freedom: to 15 | assure everyone the effective freedom to copy and redistribute it, 16 | with or without modifying it, either commercially or noncommercially. 17 | Secondarily, this License preserves for the author and publisher a way 18 | to get credit for their work, while not being considered responsible 19 | for modifications made by others. 20 | 21 | This License is a kind of "copyleft", which means that derivative 22 | works of the document must themselves be free in the same sense. It 23 | complements the GNU General Public License, which is a copyleft 24 | license designed for free software. 25 | 26 | We have designed this License in order to use it for manuals for free 27 | software, because free software needs free documentation: a free 28 | program should come with manuals providing the same freedoms that the 29 | software does. But this License is not limited to software manuals; 30 | it can be used for any textual work, regardless of subject matter or 31 | whether it is published as a printed book. We recommend this License 32 | principally for works whose purpose is instruction or reference. 33 | 34 | 35 | 1. APPLICABILITY AND DEFINITIONS 36 | 37 | This License applies to any manual or other work, in any medium, that 38 | contains a notice placed by the copyright holder saying it can be 39 | distributed under the terms of this License. Such a notice grants a 40 | world-wide, royalty-free license, unlimited in duration, to use that 41 | work under the conditions stated herein. The "Document", below, 42 | refers to any such manual or work. Any member of the public is a 43 | licensee, and is addressed as "you". You accept the license if you 44 | copy, modify or distribute the work in a way requiring permission 45 | under copyright law. 46 | 47 | A "Modified Version" of the Document means any work containing the 48 | Document or a portion of it, either copied verbatim, or with 49 | modifications and/or translated into another language. 50 | 51 | A "Secondary Section" is a named appendix or a front-matter section of 52 | the Document that deals exclusively with the relationship of the 53 | publishers or authors of the Document to the Document's overall subject 54 | (or to related matters) and contains nothing that could fall directly 55 | within that overall subject. (Thus, if the Document is in part a 56 | textbook of mathematics, a Secondary Section may not explain any 57 | mathematics.) The relationship could be a matter of historical 58 | connection with the subject or with related matters, or of legal, 59 | commercial, philosophical, ethical or political position regarding 60 | them. 61 | 62 | The "Invariant Sections" are certain Secondary Sections whose titles 63 | are designated, as being those of Invariant Sections, in the notice 64 | that says that the Document is released under this License. If a 65 | section does not fit the above definition of Secondary then it is not 66 | allowed to be designated as Invariant. The Document may contain zero 67 | Invariant Sections. If the Document does not identify any Invariant 68 | Sections then there are none. 69 | 70 | The "Cover Texts" are certain short passages of text that are listed, 71 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that 72 | the Document is released under this License. A Front-Cover Text may 73 | be at most 5 words, and a Back-Cover Text may be at most 25 words. 74 | 75 | A "Transparent" copy of the Document means a machine-readable copy, 76 | represented in a format whose specification is available to the 77 | general public, that is suitable for revising the document 78 | straightforwardly with generic text editors or (for images composed of 79 | pixels) generic paint programs or (for drawings) some widely available 80 | drawing editor, and that is suitable for input to text formatters or 81 | for automatic translation to a variety of formats suitable for input 82 | to text formatters. A copy made in an otherwise Transparent file 83 | format whose markup, or absence of markup, has been arranged to thwart 84 | or discourage subsequent modification by readers is not Transparent. 85 | An image format is not Transparent if used for any substantial amount 86 | of text. A copy that is not "Transparent" is called "Opaque". 87 | 88 | Examples of suitable formats for Transparent copies include plain 89 | ASCII without markup, Texinfo input format, LaTeX input format, SGML 90 | or XML using a publicly available DTD, and standard-conforming simple 91 | HTML, PostScript or PDF designed for human modification. Examples of 92 | transparent image formats include PNG, XCF and JPG. Opaque formats 93 | include proprietary formats that can be read and edited only by 94 | proprietary word processors, SGML or XML for which the DTD and/or 95 | processing tools are not generally available, and the 96 | machine-generated HTML, PostScript or PDF produced by some word 97 | processors for output purposes only. 98 | 99 | The "Title Page" means, for a printed book, the title page itself, 100 | plus such following pages as are needed to hold, legibly, the material 101 | this License requires to appear in the title page. For works in 102 | formats which do not have any title page as such, "Title Page" means 103 | the text near the most prominent appearance of the work's title, 104 | preceding the beginning of the body of the text. 105 | 106 | A section "Entitled XYZ" means a named subunit of the Document whose 107 | title either is precisely XYZ or contains XYZ in parentheses following 108 | text that translates XYZ in another language. (Here XYZ stands for a 109 | specific section name mentioned below, such as "Acknowledgements", 110 | "Dedications", "Endorsements", or "History".) To "Preserve the Title" 111 | of such a section when you modify the Document means that it remains a 112 | section "Entitled XYZ" according to this definition. 113 | 114 | The Document may include Warranty Disclaimers next to the notice which 115 | states that this License applies to the Document. These Warranty 116 | Disclaimers are considered to be included by reference in this 117 | License, but only as regards disclaiming warranties: any other 118 | implication that these Warranty Disclaimers may have is void and has 119 | no effect on the meaning of this License. 120 | 121 | 122 | 2. VERBATIM COPYING 123 | 124 | You may copy and distribute the Document in any medium, either 125 | commercially or noncommercially, provided that this License, the 126 | copyright notices, and the license notice saying this License applies 127 | to the Document are reproduced in all copies, and that you add no other 128 | conditions whatsoever to those of this License. You may not use 129 | technical measures to obstruct or control the reading or further 130 | copying of the copies you make or distribute. However, you may accept 131 | compensation in exchange for copies. If you distribute a large enough 132 | number of copies you must also follow the conditions in section 3. 133 | 134 | You may also lend copies, under the same conditions stated above, and 135 | you may publicly display copies. 136 | 137 | 138 | 3. COPYING IN QUANTITY 139 | 140 | If you publish printed copies (or copies in media that commonly have 141 | printed covers) of the Document, numbering more than 100, and the 142 | Document's license notice requires Cover Texts, you must enclose the 143 | copies in covers that carry, clearly and legibly, all these Cover 144 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 145 | the back cover. Both covers must also clearly and legibly identify 146 | you as the publisher of these copies. The front cover must present 147 | the full title with all words of the title equally prominent and 148 | visible. You may add other material on the covers in addition. 149 | Copying with changes limited to the covers, as long as they preserve 150 | the title of the Document and satisfy these conditions, can be treated 151 | as verbatim copying in other respects. 152 | 153 | If the required texts for either cover are too voluminous to fit 154 | legibly, you should put the first ones listed (as many as fit 155 | reasonably) on the actual cover, and continue the rest onto adjacent 156 | pages. 157 | 158 | If you publish or distribute Opaque copies of the Document numbering 159 | more than 100, you must either include a machine-readable Transparent 160 | copy along with each Opaque copy, or state in or with each Opaque copy 161 | a computer-network location from which the general network-using 162 | public has access to download using public-standard network protocols 163 | a complete Transparent copy of the Document, free of added material. 164 | If you use the latter option, you must take reasonably prudent steps, 165 | when you begin distribution of Opaque copies in quantity, to ensure 166 | that this Transparent copy will remain thus accessible at the stated 167 | location until at least one year after the last time you distribute an 168 | Opaque copy (directly or through your agents or retailers) of that 169 | edition to the public. 170 | 171 | It is requested, but not required, that you contact the authors of the 172 | Document well before redistributing any large number of copies, to give 173 | them a chance to provide you with an updated version of the Document. 174 | 175 | 176 | 4. MODIFICATIONS 177 | 178 | You may copy and distribute a Modified Version of the Document under 179 | the conditions of sections 2 and 3 above, provided that you release 180 | the Modified Version under precisely this License, with the Modified 181 | Version filling the role of the Document, thus licensing distribution 182 | and modification of the Modified Version to whoever possesses a copy 183 | of it. In addition, you must do these things in the Modified Version: 184 | 185 | A. Use in the Title Page (and on the covers, if any) a title distinct 186 | from that of the Document, and from those of previous versions 187 | (which should, if there were any, be listed in the History section 188 | of the Document). You may use the same title as a previous version 189 | if the original publisher of that version gives permission. 190 | B. List on the Title Page, as authors, one or more persons or entities 191 | responsible for authorship of the modifications in the Modified 192 | Version, together with at least five of the principal authors of the 193 | Document (all of its principal authors, if it has fewer than five), 194 | unless they release you from this requirement. 195 | C. State on the Title page the name of the publisher of the 196 | Modified Version, as the publisher. 197 | D. Preserve all the copyright notices of the Document. 198 | E. Add an appropriate copyright notice for your modifications 199 | adjacent to the other copyright notices. 200 | F. Include, immediately after the copyright notices, a license notice 201 | giving the public permission to use the Modified Version under the 202 | terms of this License, in the form shown in the Addendum below. 203 | G. Preserve in that license notice the full lists of Invariant Sections 204 | and required Cover Texts given in the Document's license notice. 205 | H. Include an unaltered copy of this License. 206 | I. Preserve the section Entitled "History", Preserve its Title, and add 207 | to it an item stating at least the title, year, new authors, and 208 | publisher of the Modified Version as given on the Title Page. If 209 | there is no section Entitled "History" in the Document, create one 210 | stating the title, year, authors, and publisher of the Document as 211 | given on its Title Page, then add an item describing the Modified 212 | Version as stated in the previous sentence. 213 | J. Preserve the network location, if any, given in the Document for 214 | public access to a Transparent copy of the Document, and likewise 215 | the network locations given in the Document for previous versions 216 | it was based on. These may be placed in the "History" section. 217 | You may omit a network location for a work that was published at 218 | least four years before the Document itself, or if the original 219 | publisher of the version it refers to gives permission. 220 | K. For any section Entitled "Acknowledgements" or "Dedications", 221 | Preserve the Title of the section, and preserve in the section all 222 | the substance and tone of each of the contributor acknowledgements 223 | and/or dedications given therein. 224 | L. Preserve all the Invariant Sections of the Document, 225 | unaltered in their text and in their titles. Section numbers 226 | or the equivalent are not considered part of the section titles. 227 | M. Delete any section Entitled "Endorsements". Such a section 228 | may not be included in the Modified Version. 229 | N. Do not retitle any existing section to be Entitled "Endorsements" 230 | or to conflict in title with any Invariant Section. 231 | O. Preserve any Warranty Disclaimers. 232 | 233 | If the Modified Version includes new front-matter sections or 234 | appendices that qualify as Secondary Sections and contain no material 235 | copied from the Document, you may at your option designate some or all 236 | of these sections as invariant. To do this, add their titles to the 237 | list of Invariant Sections in the Modified Version's license notice. 238 | These titles must be distinct from any other section titles. 239 | 240 | You may add a section Entitled "Endorsements", provided it contains 241 | nothing but endorsements of your Modified Version by various 242 | parties--for example, statements of peer review or that the text has 243 | been approved by an organization as the authoritative definition of a 244 | standard. 245 | 246 | You may add a passage of up to five words as a Front-Cover Text, and a 247 | passage of up to 25 words as a Back-Cover Text, to the end of the list 248 | of Cover Texts in the Modified Version. Only one passage of 249 | Front-Cover Text and one of Back-Cover Text may be added by (or 250 | through arrangements made by) any one entity. If the Document already 251 | includes a cover text for the same cover, previously added by you or 252 | by arrangement made by the same entity you are acting on behalf of, 253 | you may not add another; but you may replace the old one, on explicit 254 | permission from the previous publisher that added the old one. 255 | 256 | The author(s) and publisher(s) of the Document do not by this License 257 | give permission to use their names for publicity for or to assert or 258 | imply endorsement of any Modified Version. 259 | 260 | 261 | 5. COMBINING DOCUMENTS 262 | 263 | You may combine the Document with other documents released under this 264 | License, under the terms defined in section 4 above for modified 265 | versions, provided that you include in the combination all of the 266 | Invariant Sections of all of the original documents, unmodified, and 267 | list them all as Invariant Sections of your combined work in its 268 | license notice, and that you preserve all their Warranty Disclaimers. 269 | 270 | The combined work need only contain one copy of this License, and 271 | multiple identical Invariant Sections may be replaced with a single 272 | copy. If there are multiple Invariant Sections with the same name but 273 | different contents, make the title of each such section unique by 274 | adding at the end of it, in parentheses, the name of the original 275 | author or publisher of that section if known, or else a unique number. 276 | Make the same adjustment to the section titles in the list of 277 | Invariant Sections in the license notice of the combined work. 278 | 279 | In the combination, you must combine any sections Entitled "History" 280 | in the various original documents, forming one section Entitled 281 | "History"; likewise combine any sections Entitled "Acknowledgements", 282 | and any sections Entitled "Dedications". You must delete all sections 283 | Entitled "Endorsements". 284 | 285 | 286 | 6. COLLECTIONS OF DOCUMENTS 287 | 288 | You may make a collection consisting of the Document and other documents 289 | released under this License, and replace the individual copies of this 290 | License in the various documents with a single copy that is included in 291 | the collection, provided that you follow the rules of this License for 292 | verbatim copying of each of the documents in all other respects. 293 | 294 | You may extract a single document from such a collection, and distribute 295 | it individually under this License, provided you insert a copy of this 296 | License into the extracted document, and follow this License in all 297 | other respects regarding verbatim copying of that document. 298 | 299 | 300 | 7. AGGREGATION WITH INDEPENDENT WORKS 301 | 302 | A compilation of the Document or its derivatives with other separate 303 | and independent documents or works, in or on a volume of a storage or 304 | distribution medium, is called an "aggregate" if the copyright 305 | resulting from the compilation is not used to limit the legal rights 306 | of the compilation's users beyond what the individual works permit. 307 | When the Document is included in an aggregate, this License does not 308 | apply to the other works in the aggregate which are not themselves 309 | derivative works of the Document. 310 | 311 | If the Cover Text requirement of section 3 is applicable to these 312 | copies of the Document, then if the Document is less than one half of 313 | the entire aggregate, the Document's Cover Texts may be placed on 314 | covers that bracket the Document within the aggregate, or the 315 | electronic equivalent of covers if the Document is in electronic form. 316 | Otherwise they must appear on printed covers that bracket the whole 317 | aggregate. 318 | 319 | 320 | 8. TRANSLATION 321 | 322 | Translation is considered a kind of modification, so you may 323 | distribute translations of the Document under the terms of section 4. 324 | Replacing Invariant Sections with translations requires special 325 | permission from their copyright holders, but you may include 326 | translations of some or all Invariant Sections in addition to the 327 | original versions of these Invariant Sections. You may include a 328 | translation of this License, and all the license notices in the 329 | Document, and any Warranty Disclaimers, provided that you also include 330 | the original English version of this License and the original versions 331 | of those notices and disclaimers. In case of a disagreement between 332 | the translation and the original version of this License or a notice 333 | or disclaimer, the original version will prevail. 334 | 335 | If a section in the Document is Entitled "Acknowledgements", 336 | "Dedications", or "History", the requirement (section 4) to Preserve 337 | its Title (section 1) will typically require changing the actual 338 | title. 339 | 340 | 341 | 9. TERMINATION 342 | 343 | You may not copy, modify, sublicense, or distribute the Document except 344 | as expressly provided for under this License. Any other attempt to 345 | copy, modify, sublicense or distribute the Document is void, and will 346 | automatically terminate your rights under this License. However, 347 | parties who have received copies, or rights, from you under this 348 | License will not have their licenses terminated so long as such 349 | parties remain in full compliance. 350 | 351 | 352 | 10. FUTURE REVISIONS OF THIS LICENSE 353 | 354 | The Free Software Foundation may publish new, revised versions 355 | of the GNU Free Documentation License from time to time. Such new 356 | versions will be similar in spirit to the present version, but may 357 | differ in detail to address new problems or concerns. See 358 | https://www.gnu.org/licenses/. 359 | 360 | Each version of the License is given a distinguishing version number. 361 | If the Document specifies that a particular numbered version of this 362 | License "or any later version" applies to it, you have the option of 363 | following the terms and conditions either of that specified version or 364 | of any later version that has been published (not as a draft) by the 365 | Free Software Foundation. If the Document does not specify a version 366 | number of this License, you may choose any version ever published (not 367 | as a draft) by the Free Software Foundation. 368 | 369 | 370 | ADDENDUM: How to use this License for your documents 371 | 372 | To use this License in a document you have written, include a copy of 373 | the License in the document and put the following copyright and 374 | license notices just after the title page: 375 | 376 | Copyright (c) YEAR YOUR NAME. 377 | Permission is granted to copy, distribute and/or modify this document 378 | under the terms of the GNU Free Documentation License, Version 1.2 379 | or any later version published by the Free Software Foundation; 380 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 381 | A copy of the license is included in the section entitled "GNU 382 | Free Documentation License". 383 | 384 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 385 | replace the "with...Texts." line with this: 386 | 387 | with the Invariant Sections being LIST THEIR TITLES, with the 388 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 389 | 390 | If you have Invariant Sections without Cover Texts, or some other 391 | combination of the three, merge those two alternatives to suit the 392 | situation. 393 | 394 | If your document contains nontrivial examples of program code, we 395 | recommend releasing these examples in parallel under your choice of 396 | free software license, such as the GNU General Public License, 397 | to permit their use in free software. -------------------------------------------------------------------------------- /project/docs/yast_installer.md: -------------------------------------------------------------------------------- 1 | # Step by step guide for openSUSE Leap 2 | ## Before you continue 3 | 4 | This guide targets **openSUSE Leap**; however the differences between the installers for the openSUSE variants -- like Tumbleweed, MicroOS and Kubic -- are minor and most parts of the installer will be identical. 5 | 6 | !!! warning 7 | Expect slight differences in *System Role* and *Installation Settings*. 8 | 9 | ### Minimum system requirements 10 | 11 | * Any AMD64/Intel* EM64T processor (32-bit processors are not supported). 12 | * 1 GB physical RAM (4 GB or more strongly recommended). 13 | * 10 GB available disk space for a minimal installation, 16 GB for a graphical desktop (more is recommended). In case you plan to use _Btrfs_ snapshots, a minimum of 40 GB for the root partition is recommended. 14 | * Supports most modern sound and graphics cards, 1024 x 768 display resolution (higher recommended). 15 | 16 | ### Precautions 17 | 18 | * Make sure that you have backed up all your data from the disk where you're planning to install openSUSE to. 19 | * If installing on a separate drive, it is recommended to disconnect the drives not in use. You can always probe a foreign operating systems to Grub from a finalized installation with *YaST*, but selecting the wrong drive to install openSUSE will overwrite the disk destroying the data on it. 20 | * In case you are using a Network image (Netiso) make sure that you have a strong internet connection. A wired connection is always more reliable than a wifi one. 21 | * If installing on a laptop, it is good practice to plug in the AC charger. 22 | 23 | You are now ready to boot the USB drive, which you have previously prepared - as explained in the [Preparing the installation media](image_choice.md) section - and turn on your computer. Boot from the USB drive and select installation from the boot menu. 24 | 25 | If you want to see the details of the installation while the installer is booting you can press the `ESC` key. 26 | 27 | ???+ info 28 | On the left you will see a list of items where you can follow the steps you will take next or have already taken. You can always press `Back` in case you want to change something you configured earlier. 29 | ## Getting started 30 | ## Welcome 31 | ### Language, keyboard and license agreement 32 | 33 | *Welcome to the YaST installer!* 34 | 35 | Here you can change the language under `Language` (Alt+L), change the keyboard layout under `Keyboard Layout` (Alt+K) and you have a chance to test your selected keyboard layout in the field under `Keyboard Test` (Alt+y). 36 | 37 | The `License Agreement` informs you on roles, responsibilities and potential limitations. 38 | 39 | ## Network activation 40 | !!! note "Online repositories" 41 | If you have an active internet conenction over an ethernet cable connected to your computer, right after you pass the *"Language, Keyboard and License Agreement"* section you will be prompted, asking if you want to *"Activate online repositories now?"*.It is recommended to select *Yes* which will provide you with a list of repositories, pre-selecting the main ones in advance and will download updated packages from the online repository during the installation. If you're on a metered connection you press "No". 42 | 43 | ### Network settings 44 | You can skip this part if: 45 | * you have an active wired internet connection which can be automatically configured by the system; or 46 | * you're not planning to use online repositories during the installation process and rely on the packages provided by the DVD installer. 47 | 48 | If you don't have a network connection -- because you have don't have an ethernet port or you're using wireless connections only -- you will be prompted to configure your network settings. By default the YaST system installer is using _Wicked_ as the network controller. Keep in mind that if you choose to use _Network Manager_ (NM) instead of _Wicked_, your network configuration will not be transferred from _Wicked_ to _Network Manager_. 49 | 50 | You will see a list of available network adapters in a list from which you can select the one that you wish to configure and press `Edit`. In case of configuring a wireless adapter you will see the `Wireless Specific` tab open. Here you can `Scan Network`, select the name of your wireless network (SSID), select the authentication mode -- which in most cases will be WPA-PSK "home" -- and input your password. 51 | On the `Addresses` tab you will be able to configure the IP address of your adapter. You can select `Dynamic Address` in which case you will receive an address from your router/other dhcp server on your network or `Statically Assigned IP Address` in which case you need to type an ip address, a subnet mask and a hostname. Click `Next` when finished. 52 | ![Wireless configuration](image/yast_wireless_specific.png) 53 | 54 | ???+ info 55 | Wireless networks configured here will be transferred to the finalized system as well, regardless the solution you are choosing to use to manage your connections. 56 | 57 | **If** you configured a statically assigned IP address: 58 | 1. Switch to the `Routing` tab. 59 | 2. Press `Add`, add your default gateway address and select the network adapter to which you want this route assigned to. 60 | 3. Press `OK` then `Next` to apply your changes and continue the installation. 61 | 62 | ## Online repositories 63 | ### List of online repositories 64 | 65 | These repositories are the following: 66 | 67 | * _Update Repository (Non-Oss)_: Non-free -- as in Free Open-Source Software (FOSS) -- update repository. Provides security and maintenance updates for the distribution. _Selected by default._ 68 | * _Non-OSS Repository_: Non-free repository. Provides packages like Steam. _Selected by default._ 69 | * _Main Update Repository_: Main free -- as in FOSS -- update repository. Provides security and maintenance updates for the distribution. _Selected by default._ 70 | * _Main Repository_: Main free repository provides FOSS only. _Selected by default._ 71 | * _Update Repository (Debug)_: A repository for those who want to debug application updates for openSUSE, for experts only. 72 | * _Untested Updates_: Security and maintenance updates that requires testing. Add this repository if you want to participate in testing. 73 | * _Source Repository_: Provides all source packages in the distribution, for experts only. 74 | * _Debug Repository_: A repository for those who want to debug applications for openSUSE, for experts only. 75 | 76 | ???+ info 77 | Keep in mind that if you're on a metered network and you choose to add the online repos, the installer will download packages with newer versions. 78 | 79 | ### System role 80 | 81 | At this section of the preparation you can select from a list of predefined use cases which will tailor the system for the selected scenario. It is recommended to take a look at the [Choosing the right image](pick_an_image.md) page prior to continuing as it provides a brief explanation of desktop environments. Do note if you're using a DVD installer without an active internet connection, some of the listed desktop environments will not be available. 82 | 83 | * _Desktop with KDE Plasma_: the Plasma desktop with KDE applications. 84 | * _Desktop with GNOME_: the GNOME desktop with GNOME applications. 85 | * _Generic Desktop_: IceWM, a minimal desktop environment with minimal amount of packages. 86 | * _Server_: A server installation without providing any graphical environment. _Not recommended for inexperienced users._ 87 | * _Transactional Server_: A server installation with a read-only root filesystem in an immutable server style. This will provide atomic, automatic updates and packages can be installed with `transactional-update` only. _Not recommended for inexperienced users._ 88 | 89 | Select one and press __Next__ to continue. 90 | 91 | ## Disk 92 | ### Suggested Partitioning 93 | ![Suggested Partitioning](image/yast_suggested_partitioning.png) 94 | 95 | ### Guided Setup 96 | 97 | ### Expert Partitioner 98 | #### About partition schemes 99 | Most Linux distributions use the same "base" partition scheme: 100 | 101 | * a _bootloader partition_, hosting a small program called a _bootloader_, whose purpose is to take over from the UEFI/BIOS of your computer and set up the initial conditions for your operating system to get running 102 | * a main _data partition_ (or _OS partition_), which is where the operating system (i.e. _Leap_) is installed, optionally along with your personal user data. 103 | * (recommended but not necessary) a swap partition of the size of your machine's RAM, + 1 GB 104 | 105 | If you are not interested in keeping whatever data or operating system is installed on the target machine, you can simply proceed with the base partition scheme. In that cases, simply run the installer and, on the _Disk_ screen, pick the _Suggested Partitioning_ option, and accept all recommendations there. 106 | 107 | Chances are, however, that you will want to install Leap on a disk with an already functional operating system (i.e. Windows, macOS, or another Linux distribution). Or that you will want to install more operating systems alongside _Leap_ easily and reliably in the future. These families of scenarios require some extra steps with respect ot to the "base" partition scheme above. 108 | #### Installing Leap alongside preexistent Windows partitions 109 | If you have Windows installed already, you are likely to have the following (physical) partitions already: 110 | 111 | * one 'recovery partition', about 500 MB large, usually using the _Fat32_ filesystem (we won't consider it further as it is not relevant to what comes next) 112 | * one 'Windows data' partition, usually using the _Fat32_ filesystem, hosting both Windows and your user data (you want to leave it untouched) 113 | * one 'Windows bootloader' partition, about 100 MB large, using the _Fat32_ filesystem, hosting the Windows bootloader. 114 | 115 | We recommend adding to these physical partitions a single 'Leap OS' partition, at least 40 GB large, using the _Btrfs_ filesystem. Please scroll down to [pick a filesystem for data partitions](yast_installer.md#picking-a-file-system-for-data-partitions) to for more details as to why we recommend _Btrfs_. 116 | 117 | ???+ info 118 | The 'Leap OS' partition will host the Leap bootloader under the `/boot` subvolume, the operating system directly under `/` and your user data under the `/home` subvolume. Do note that, by default, a `/home` directory will be installed to store your user data. Also by default, this directory will be excluded from the snapshotting system, which means that there will be no _Btrfs_ backups for your user data. This permits rollbacks between snapshots to proceed smoothly, leaving your user data in no incoherent state. This also means that you will need to manually manage your user data [back ups](backing_up.md). 119 | 120 | Alternatively, you might want to install your user data under a separate partition, also mounted as `/home`, using any file system of your liking. This might come in handy if you plan on using multiple operating systems reading from, and writing to, a single user data partition. 121 | 122 | Whichever option you choose, you can refer to the following instructions: 123 | 124 | Step by step: Expert partitioning for Windows 125 | 126 | 1. From the _Disk_ view, select _Expert Partitioner_ 127 | 2. Click the __Add Partition__ button (bottom left-hand side) 128 | 3. Assign it at least 40 GBs, and set its filesystem to _Btrfs_, and the mount point to `/`. You could label this partition 'Leap OS'. 129 | 4. If it is not set already, set the `/boot/efi` flag your 'Windows bootloader' partition (the ~100MB partition probably using the _Fat32_ filesystem) 130 | 5. (recommended) Add a `swap` partition with a size equal to your current RAM + 1 GB. 131 | 132 | ???+ info 133 | Even though this makes no difference from the installer's point of view, we recommend assigning meaningful labels to each partition, to make them easier to reidentify them. 134 | 135 | The result should look like this: 136 | 137 | Check list: Expert partitioning for Windows 138 | 139 | * (old) ... some other Windows partitions ... 140 | * (old) `/boot/efi`, _Fat32_, ~ 100 MB 141 | * (new) `/`, _Btrfs_, > 40 GB 142 | 143 | !!! warning 144 | Because you are installing the Leap bootloader on a non-btrfs partition, the bootloader will be outside of the scope of the snapshotting system. This means that you won't be able to rollback from a misconfigured bootloader settings, and that in general rolling back won't suffice to fix issues with your bootloader configuration. See [Introduction to snapper](snapper.md) for details. Consider also [the official documentation](https://doc.opensuse.org/documentation/leap/reference/html/book.opensuse.reference/cha-snapper.html#sec-snapper-snapshot-boot) on snapper rollbacks. 145 | 146 | Optionally, you could create a new partition for your user data under `/home`. This partition would then be easily accessible to other operating systems installed on your machine. If you do so, make sure there is no `/home` subvolume created inside the partition assigned to `/`. 147 | 148 | ???+ info 149 | After the installation you will want to switch between Leap and Windows. Use [these instructions](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/boot-to-uefi-mode-or-legacy-bios-mode) to learn how to reboot to your UEFI. From there you will be able to select Windows or Leap as boot destination. 150 | 151 | #### Installing Leap alongside preexistent Linux partitions 152 | You can follow the _Step by Step_ from the previous section, making sure that: 153 | 154 | * you flag your already existent bootloader partition as `/boot/efi` 155 | * (if it already exists on the disk before installing _Leap_) you flag your user data partition as `/home`, or alternatively, that you apply steps (4 & 5) if you need to have a `/home` partition outside of `/`. 156 | 157 | !!! warning 158 | Make sure there is enough space (>100 MB is fine) on whatever partition you're installing your bootloader(s) to. Resize it if necessary. 159 | 160 | Check list: Expert partitioning for multiple Linux distributions 161 | 162 | * (old) ... some other partitions ... 163 | * (old) `/boot/efi`, preferably _Btrfs_, > 100 MB 164 | * (new) `/`, _Btrfs_, > 40 GB 165 | 166 | Optionally, you could create a new partition for your user data under `/home`. This partition would then be easily accessible to other operating systems installed on your machine. If you do so, make sure there is no `/home` subvolume created inside the partition assigned to `/`. 167 | 168 | ???+ info 169 | After the installation you will want to switch between Leap and whichever operating system you're using. Refer to your machine's manufacturer for instructions. If your machine had Windows preinstalled, use [these instructions](https://docs.microsoft.com/en-us/windows-hardware/manufacture/desktop/boot-to-uefi-mode-or-legacy-bios-mode) to learn how to reboot to your UEFI. From there you will be able to select the desired boot destination. 170 | 171 | #### Installing Leap alongside preexistent macOS partitions 172 | The installation process for Mac users interested in dual-booting Leap alongside their mac OS partitions is simple: 173 | 174 | Step by step: Expert partitioning for Mac 175 | 176 | 1. From the _Disk_ view, select _Expert Partitioner_ 177 | 2. Click the __Add Partition__ button (bottom left-hand side) 178 | 3. Create a new _Btrfs_ partition of at least 100 MB for the Leap bootloader. Set it the `/boot/efi` mount point. You could label this partition 'Leap bootloader'. 179 | 4. Create a new _Btrfs_ partition of at least 40 GBs by repeating (2). Set it the `/` mount point. You could label this partition 'Leap OS'. 180 | 5. (recommended) Create a `swap` partition with a size equal to your current RAM + 1 GB. 181 | 182 | Check list: Expert partitioning for macOS 183 | 184 | * (old) ... some macOS partitions ... 185 | * (new) `/boot/efi`, _Btrfs_, > 100 MB 186 | * (new) `/`, _Btrfs_, > 40 GB 187 | 188 | Optionally, you could create a new partition for your user data under `/home`. This partition would then be easily accessible to other operating systems installed on your machine. If you do so, make sure there is no `/home` subvolume created inside the partition assigned to `/`. 189 | 190 | !!! warning 191 | Some recent Macs have been reported to ship with firmware lock enabled by default. Refer to [this guide](https://support.apple.com/en-gb/HT204455) to disable it. 192 | 193 | ???+ info 194 | After the installation you will want to switch between Leap and macOS. Simply hold the `alt` (option) key immediately after restarting and select Leap or macOS. 195 | 196 | #### Picking a filesystem for data partitions 197 | The _Leap_ installer allows you to pick among several filesystems for _data partitions_, which for the purpose of this section we define as any partition mounted as `/` (root) or having root on its path (i.e. `/home`). Among the supported filesystems for data partitions you will find: 198 | 199 | * _Btrfs_ 200 | * _Ext4_ 201 | * _XFS_ 202 | 203 | However, _Btrfs_ has been the preferred filesystem for all openSUSE distributions for several years. This filesystem boasts a powerful _copy-on-write_ logic, which lies at the heart of openSUSE's approach to stability: _Btrfs_ allows to conveniently create and use _snapshots_, aka 'restoration points' on Windows (see [Introduction to snapper](snapper.md) for details). For this reason we highly recommend you to use it for all your data partitions when installing _Leap_. 204 | 205 | !!! info 206 | Snapshots take advantage of the _copy-on-write_ logic of _Btrfs_. On a copy-on write filesystem, submitted changes do not overwrite the previous state; instead, changes are 'moved' to a different location on the disk, so that the location of origin is left unchanged. Together with 'deduplication' rules aimed at minimizing redundancies between file changes, this logic allows for the layering of several versions of an entire filesystem, with each layer representing different sets of changes. These sets of changes thus correspond to meaningful actions from the end user's perspective, such as 'before installing package X', 'before creating subvolume Y', etc. 207 | Renouncing _Btrfs_ thus means renouncing this feature. Given that _Tumbleweed_ was designed around this feature, it will not work as intended unless you pick this filesystem. 208 | 209 | #### LUKS encryption 210 | If you are installing _Leap_ on a laptop, or generally on any machine accessible to untrusted individuals, we highly recommend protecting your data with a _full disk encryption_. The price to pay is that doing so will entirely wipe out your drive. The obvious advantage, however, is that this will protect your data with a sound security model. 211 | 212 | !!! info 213 | Full disk encryption contrasts with _partition encryption_ in that it protects your entire physical drive using cryptographic techniques. For reasons that go beyond the scope of this document, partition encryption is significantly less secure than full disk encryption. In pictures, partition encryption is like locking your house with an old fashioned padlock and hiding the key in a flowerpot lying on the terrace, while full disk encryption is like locking your house with a digital padlock and keeping the code only in your mind. 214 | 215 | To apply full disk encryption while installing, you can either use the _Guided Setup_ feature or manually create the partition scheme first and then apply encryption. If you do the latter, you can simply reproduce the steps listed below: 216 | 217 | Step by step: Guided partitioning for LUKS on Btrfs 218 | 219 | 1. Select _Guided Setup_ from the _Disk_ screen 220 | 2. Check _Enable Disk Encryption_, and enter a strong password in both text fields 221 | 3. Then, on the _Filesystem Options_ screen: 222 | * Select _Btrfs_. 223 | * Tick the _Enable Snapshots_ checkbox ([scroll up](yast_installer.md#picking-a-file-system-for-data-partitions) or see [this document](snapper.md) to understand the reason why we recommend this). 224 | * Select _Btrfs_ again as _File System Type_ for your any mount point / partition presented to you by the installer. 225 | 226 | Alternatively, if you prefer to turn to a different filesystem than _Btrfs_ (typically _Ext4_) follow the following steps: 227 | 228 | !!! warning 229 | Using _Ext4_ on either `/` or `/boot` will prevent you from using `snapper` snapshots. 230 | 231 | Step by step (Guided Setup: LUKS + LVM + Ext4) 232 | 233 | 1. Select _Guided Setup_'_ from the _Disk_ screen 234 | 2. Check _Enable LVM_'_ and _Enable Disk Encryption_, and enter a strong password in both text fields 235 | 3. Then, on the _Filesystem Options_ screen: 236 | * Select _Ext4_. 237 | * Tick the _Enable Snapshots_ checkbox ([scroll up](yast_installer.md#picking-a-file-system-for-data-partitions) or see [this document](snapper.md) to understand the reason why we recommend this). 238 | * Tick the _Propose Separate Home LVM Logical Volume_ checkbox. 239 | * Select _Ext4_ again as _File System Type_ for your `/home` directory. 240 | * Tick the _Propose Separate Swap LVM Logical Volume_. 241 | 242 | !!! info 243 | The recommended setup mentioned here makes use of the [cryptsetup](https://gitlab.com/cryptsetup/cryptsetup/blob/master/README.md) utility in conjunction with an LVM partition. `cryptsetup` is a popular and trusted tool in the Linux community implementing the LUKS Linux kernel standard, using the `aes-xts-plain64` encryption standard. As for LVM, it is a partitioning scheme that allows your machine to see multiple physical disks as one single (logical) partition, or vice-versa, to see one unique physical disk as multiple (logical) partitions. LVM & LUKS work well together, with LVM considerably simplifying encryption - decryption operations. 244 | 245 | ## Time Zone 246 | ### Clock and Time Zone 247 | 248 | Select your region and the time zone that you want to use for the system. The hardware clock is by default set to UTC. Select _Other Settings_ for other time settings: 249 | 250 | * _Manually_: Set time and date manually. 251 | * _Synchronize with NTP Server_: Automatically synchronize time and date with the provided NTP servers which you can initiate right now by selecting *"Synchronize now"*. 252 | * _Run NTP as daemon_: Run NTP as a daemon so the service always runs and starts automatically on boot and sets the time and date based on the received values from the NTP server. 253 | * _Save NTP Configuration_: save or discard the NTP configuration into the installed system. 254 | 255 | ## User Settings 256 | ### Local User 257 | 258 | At this point you can create a local user or skip that by selecting _Skip User Creation_ you can set up a password for `root`. 259 | You need to fill out the empty fields in order to create a first user: 260 | 261 | * _User's Full Name_: A human-friendly version of your username, which will be shown in login windows for example. 262 | * _Username_: The actual username for your account. This will be used in all login contexts, whether dialogue boxes or terminal prompts, including virtual console (vc) or over Secure Shell (SSH). 263 | * _Password_: The password for your user to secure your account. 264 | 265 | By default you will also use this newly created account to act as the administrator. The password set there will be set for the `root` user as well. 266 | 267 | !!! note "Root user" 268 | openSUSE creates the root user by default, in contrast to other Linux distributions. To avoid using the same password for both users, untick the _Use this password for system administrator_ checkbox. Clicking __Next__ will take you to the page where you can set a different password for root. At this page you can also import existing SSH public keys. This is useful if you're installing openSUSE over another distribution. 269 | 270 | ## Installation 271 | ## Installation Overview 272 | ### Installation Settings 273 | This is the final and probably the an important section of the installer, __don't skip it__! You can and should review your settings, fine tune your installation if you need to and can even gain access to the _YaST Software Installer_ which can be used to install additional packages or patterns. To change any of the settings just click the _headlines_ (like "Software" or "Security"). 274 | After you reviewed the settings you can move on with the installation which will finalize your openSUSE deployment based on your provided informations. 275 | 276 | ???+ info 277 | Patterns are a group of packages that allows the user to easily install otherwise complex packages and configurations - like KDE Plasma or Gnome -. --------------------------------------------------------------------------------