RomanNum3ral
/
archinstall
mirror of https://github.com/archlinux/archinstall.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve the README (#2174) 

Co-authored-by: Anton Hvornum <anton@hvornum.se>
This commit is contained in:
aidanthewiz 2024-03-07 07:47:45 -05:00 committed by GitHub
parent 0d5e1cf752
commit 1bf68311c2
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 57 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
README.md
View File

@ -6,7 +6,7 @@
[![Lint Python and Find Syntax Errors](https://github.com/archlinux/archinstall/actions/workflows/flake8.yaml/badge.svg)](https://github.com/archlinux/archinstall/actions/workflows/flake8.yaml)
Just another guided/automated [Arch Linux](https://wiki.archlinux.org/index.php/Arch_Linux) installer with a twist.
The installer also doubles as a python library to install Arch Linux and manage services, packages and other things inside the installed system *(Usually from a live medium)*.
The installer also doubles as a python library to install Arch Linux and manage services, packages, and other things inside the installed system *(Usually from a live medium)*.
* archinstall [discord](https://discord.gg/cqXU88y) server
* archinstall [matrix.org](https://app.element.io/#/room/#archinstall:matrix.org) channel
@ -14,58 +14,66 @@ The installer also doubles as a python library to install Arch Linux and manage
* archinstall [documentation](https://archinstall.archlinux.page/)
# Installation & Usage
$ sudo pacman -S archinstall
```shell
sudo pacman -S archinstall
```
Alternative ways to install are `git clone` the repository or `pip install --upgrade archinstall`.
## Running the [guided](https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py) installer
Assuming you are on an Arch Linux live-ISO or installed via `pip`:
# archinstall
```shell
archinstall
```
## Running the [guided](https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py) installer using `git`
```shell
# cd archinstall-git
# python -m archinstall
```
#### Advanced
Some additional options that are not needed by most users are hidden behind the `--advanced` flag.
Some additional options that most users do not need are hidden behind the `--advanced` flag.
## Running from a declarative configuration file or URL
`archinstall` can be run with a JSON configuration file. There are 2 different configuration files to consider,
the `user_configuration.json` contains all general installation configuration, whereas the `user_credentials.json`
contains the sensitive user configuration such as user password, root password and encryption password.
contains the sensitive user configuration such as user password, root password, and encryption password.
An example of the user configuration file can be found here
[configuration file](https://github.com/archlinux/archinstall/blob/master/examples/config-sample.json)
and example of the credentials configuration here
and an example of the credentials configuration here
[credentials file](https://github.com/archlinux/archinstall/blob/master/examples/creds-sample.json).
**HINT:** The configuration files can be auto-generated by starting `archinstall`, configuring all desired menu
points and then going to `Save configuration`.
To load the configuration file into `archinstall` run the following command
```
```shell
archinstall --config <path to user config file or URL> --creds <path to user credentials config file or URL>
```
# Help or Issues
If any issues are encountered please submit an issue here on Github or submit a post in the discord help channel.
If you come across any issues, kindly submit your issue here on Github or post your query in the
[discord](https://discord.gg/cqXU88y) help channel.
When submitting an issue, please:
* Provide the stacktrace of the output if there is any
* Provide the stacktrace of the output if applicable
* Attach the `/var/log/archinstall/install.log` to the issue ticket. This helps us help you!
* To extract the log from the ISO image, one way is to use<br>
```curl -F'file=@/var/log/archinstall/install.log' https://0x0.st```
```shell
curl -F'file=@/var/log/archinstall/install.log' https://0x0.st
```
# Available Languages
Archinstall is available in different languages which have been contributed and are maintained by the community.
The language can be switched inside the installer (first menu entry). Bare in mind that not all languages provide
The language can be switched inside the installer (first menu entry). Bear in mind that not all languages provide
full translations as we rely on contributors to do the translations. Each language has an indicator that shows
how much has been translated.
@ -73,11 +81,11 @@ Any contributions to the translations are more than welcome,
to get started please follow [the guide](https://github.com/archlinux/archinstall/blob/master/archinstall/locales/README.md)
## Fonts
The ISO does not ship with ship with all fonts needed for different languages.
Fonts that are using a different character set than Latin will not be displayed correctly. If those languages
want to be selected than a proper font has to be set manually in the console.
The ISO does not ship with all fonts needed for different languages.
Fonts that use a different character set than Latin will not be displayed correctly. If those languages
want to be selected then a proper font has to be set manually in the console.
All available console fonts can be found in `/usr/share/kbd/consolefonts` and can be set with `setfont LatGrkCyr-8x16`.
All available console fonts can be found in `/usr/share/kbd/consolefonts` and set with `setfont LatGrkCyr-8x16`.
# Scripting your own installation
@ -135,22 +143,22 @@ with Installer(
installation.create_users(user)
```
This installer will perform the following:
This installer will perform the following actions:
* Prompt the user to configurate the disk partitioning
* Prompt the user to configure the disk partitioning
* Prompt the user to setup disk encryption
* Create a file handler instance for the configured disk and the optional disk encryption
* Perform the disk operations (WARNING: this will potentially format the disks and erase all data)
* Installs a basic instance of Arch Linux *(base base-devel linux linux-firmware btrfs-progs efibootmgr)*
* Installs and configures a bootloader to partition 0 on uefi. On BIOS, it sets the root to partition 0.
* Install a basic instance of Arch Linux *(base base-devel linux linux-firmware btrfs-progs efibootmgr)*
* Install and configures a bootloader to partition 0 on UEFI. On BIOS, it sets the root to partition 0.
* Install additional packages *(nano, wget, git)*
* Create a new user
> **Creating your own ISO with this script on it:** Follow [ArchISO](https://wiki.archlinux.org/index.php/archiso)'s guide on how to create your own ISO.
> **To create your own ISO with this script in it:** Follow [ArchISO](https://wiki.archlinux.org/index.php/archiso)'s guide on creating your own ISO.
## Script non-interactive automated installation
For an example of a fully scripted, automated installation please see the example
For an example of a fully scripted, automated installation please refer to the example
[full_automated_installation.py](https://github.com/archlinux/archinstall/blob/master/examples/full_automated_installation.py)
## Unattended installation based on MAC address
@ -159,16 +167,16 @@ Archinstall comes with an [unattended](https://github.com/archlinux/archinstall/
example which will look for a matching profile for the machine it is being run on, based on any local MAC address.
For instance, if the machine the code is executed on has the MAC address `52:54:00:12:34:56` it will look for a profile called
[52-54-00-12-34-56.py](https://github.com/archlinux/archinstall/blob/master/archinstall/default_profiles/tailored.py).
If it's found, the unattended installation will commence and source that profile as its installation procedure.
If it's found, the unattended installation will begin and source that profile as its installation procedure.
# Profiles
`archinstall` ships with a set of pre-defined profiles that can be chosen during the installation process.
`archinstall` comes with a set of pre-configured profiles available for selection during the installation process.
- [Desktop](https://github.com/archlinux/archinstall/tree/master/archinstall/default_profiles/desktops)
- [Server](https://github.com/archlinux/archinstall/tree/master/archinstall/default_profiles/servers)
The definitions of the profiles and what packages they will install can be seen directly in the menu or
The profiles' definitions and the packages they will install can be directly viewed in the menu, or
[default profiles](https://github.com/archlinux/archinstall/tree/master/archinstall/default_profiles)
@ -176,10 +184,10 @@ The definitions of the profiles and what packages they will install can be seen
## Using a Live ISO Image
If you want to test a commit, branch or bleeding edge release from the repository using the vanilla Arch Live ISO image,
you can replace the version of archinstall with a new version and run that with the steps described below.
If you want to test a commit, branch, or bleeding edge release from the repository using the standard Arch Linux Live ISO image,
replace the archinstall version with a newer one and execute the subsequent steps defined below.
*Note: When booting from a live USB then the space on the ramdisk is limited and may not be sufficient to allow
*Note: When booting from a live USB, the space on the ramdisk is limited and may not be sufficient to allow
running a re-installation or upgrade of the installer. In case one runs into this issue, any of the following can be used
- Resize the root partition on the fly https://wiki.archlinux.org/title/Archiso#Adjusting_the_size_of_root_partition_on_the_fly
- The boot parameter `copytoram=y` (https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio-archiso/-/blob/master/docs/README.bootparams#L26)
@ -220,36 +228,36 @@ It will go through everything from packaging, building and running *(with qemu)*
## How to dual boot with Windows
`archinstall` can be used to install Arch alongside an existing Windows installation.
Below are the necessary steps:
* After the Windows installation make sure there is some unallocated space for a Linux installation available
* Boot into the ISO and run`archinstall`
* Select `Disk configuration` -> `Manual partitioning`
* Select the disk on which Windows resides
* Chose `Create a new partition`
* Select a filesystem type
* Now the location of the new partition has to be specified as start and end sectors (values can be suffixed with various units)
* Assign mountpoint `/`
* Back in the partitioning menu, assign the `Boot/ESP` partition the mountpoint `/boot`
* This is all for the partitioning menu, select `Confirm and exit` to return to the main menu
* Set any additional settings you would like to have for the installation
* After completing the setup start the installation
To install Arch Linux alongside an existing Windows installation using `archinstall`, follow these steps:
1. Ensure some unallocated space is available for the Linux installation after the Windows installation.
2. Boot into the ISO and run `archinstall`.
3. Choose `Disk configuration` -> `Manual partitioning`.
4. Select the disk on which Windows resides.
5. Select `Create a new partition`.
6. Choose a filesystem type.
7. Determine the start and end sectors for the new partition location (values can be suffixed with various units).
8. Assign the mountpoint `/` to the new partition.
9. Assign the `Boot/ESP` partition the mountpoint `/boot` from the partitioning menu.
10. Confirm your settings and exit to the main menu by choosing `Confirm and exit`.
11. Modify any additional settings for your installation as necessary.
12. Start the installation upon completion of setup.
# Mission Statement
Archinstall promises to ship a [guided installer](https://github.com/archlinux/archinstall/blob/master/archinstall/scripts/guided.py) that follows
the [Arch Principles](https://wiki.archlinux.org/index.php/Arch_Linux#Principles) as well as a library to manage services, packages and other Arch Linux aspects.
the [Arch Linux Principles](https://wiki.archlinux.org/index.php/Arch_Linux#Principles) as well as a library to manage services, packages, and other Arch Linux aspects.
The guided installer will provide user-friendly options along the way, but the keyword here is options, they are optional and will never be forced upon anyone.
The guided installer itself is also optional to use if so desired and not forced upon anyone.
The guided installer ensures a user-friendly experience, offering optional selections throughout the process. Emphasizing its flexible nature, these options are never obligatory.
In addition, the decision to use the guided installer remains entirely with the user, reflecting the Linux philosophy of providing full freedom and flexibility.
---
Archinstall has one fundamental function which is to be a flexible library to manage services, packages and other aspects inside the installed system.
This library is in turn used by the provided guided installer but is also for anyone who wants to script their own installations.
Archinstall primarily functions as a flexible library for managing services, packages, and other elements within an Arch Linux system.
This core library is the backbone for the guided installer that Archinstall provides. It is also designed to be used by those who wish to script their own custom installations.
Therefore, Archinstall will try its best to not introduce any breaking changes except for major releases which may break backwards compatibility after notifying about such changes.
Therefore, Archinstall will try its best to not introduce any breaking changes except for major releases which may break backward compatibility after notifying about such changes.
# Contributing