Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixed Readme #6

Merged
merged 1 commit into from
Sep 15, 2024
Merged

Fixed Readme #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
161 changes: 127 additions & 34 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,138 @@
# Custom WSL OS

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://img.shields.io/github/license/gvatsal60/project-template)
[![build status](https://github.com/gvatsal60/project-template/actions/workflows/readme-checker.yaml/badge.svg)](https://github.com/gvatsal60/project-template/actions/workflows/readme-checker.yaml)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/gvatsal60/project-template/master.svg)](https://results.pre-commit.ci/latest/github/gvatsal60/project-template/HEAD)
![GitHub pull-requests](https://img.shields.io/github/issues-pr/gvatsal60/project-template)
![GitHub Issues](https://img.shields.io/github/issues/gvatsal60/project-template)
![GitHub forks](https://img.shields.io/github/forks/gvatsal60/project-template)
![GitHub stars](https://img.shields.io/github/stars/gvatsal60/project-template)

This repository serves as a foundational template for new projects, equipped with essential tools for
maintaining code quality and documentation consistency. It includes:

1. README.md
2. LICENSE
3. .gitignore
4. CODE_OF_CONDUCT.md
5. CONTRIBUTING.md
6. FUNDING.yml
7. CHANGELOG.md

## Installation

To install Project Template, follow these steps:

1. **Customize According to Your Project:**
* Replace `[Project Name]`
* Update `[contact email]`
* Follow `[coding style guide]`

## Build Image
```bash
docker compose build
```
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://img.shields.io/github/license/gvatsal60/Custom-WSL-OS)
[![Build and Push Docker Image](https://github.com/gvatsal60/Custom-WSL-OS/actions/workflows/docker-img-push.yaml/badge.svg)](https://github.com/gvatsal60/Custom-WSL-OS/actions/workflows/docker-img-push.yaml)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/gvatsal60/Custom-WSL-OS/master.svg)](https://results.pre-commit.ci/latest/github/gvatsal60/Custom-WSL-OS/HEAD)
![GitHub pull-requests](https://img.shields.io/github/issues-pr/gvatsal60/Custom-WSL-OS)
![GitHub Issues](https://img.shields.io/github/issues/gvatsal60/Custom-WSL-OS)
![GitHub forks](https://img.shields.io/github/forks/gvatsal60/Custom-WSL-OS)
![GitHub stars](https://img.shields.io/github/stars/gvatsal60/Custom-WSL-OS)

Welcome! This guide will walk you through the process of setting up Windows Subsystem for Linux (WSL) with a custom image.

## Prerequisites

1. Windows Version: Ensure you're running Windows 10 version 1903 or later, or Windows 11

2. WSL Installed: If you haven't installed WSL yet, follow the instructions on Microsoft's official [WSL documentation](https://learn.microsoft.com/en-us/windows/wsl/install) before proceeding

3. Custom Ubuntu Image: You should have your custom Ubuntu image ready in .tar format

4. Docker: Ensure Docker and Docker Compose are installed on your system. Follow Docker’s [installation instructions](https://docs.docker.com/engine/install/) if you haven't installed Docker yet.

### Steps for Installation

1. Install WSL and Ubuntu

If you haven’t already installed WSL, you can do so with the following steps:

1. Open PowerShell as Administrator:
Right-click the Start menu and select "Windows PowerShell (Admin)"

2. Install WSL:

```sh
wsl --install
```

This command will install the WSL feature and download the default Linux distribution.

3. Restart Your Computer:
A restart may be required for the WSL feature to be fully installed.

2. Download and Install the Custom Ubuntu Image

1. Open PowerShell as Administrator:

- Ensure you're running PowerShell with administrative privileges.

2. Import the Custom Image:

- Replace `path\to\your\custom-image.tar` with the path to your custom Ubuntu .tar image and YourCustomUbuntu with a name for your WSL instance.

```sh
wsl --import YourCustomUbuntu path\to\installation\folder path\to\your\custom-image.tar
```

- YourCustomUbuntu: The name you assign to your WSL instance.

- `path\to\installation\folder`: Directory where you want to store the WSL instance. For example, `C:\WSL\YourCustomUbuntu`

3. Set Default Distribution (Optional):

- If you want to make your custom image the default WSL distribution, run:

```sh
wsl --set-default YourCustomUbuntu
```

4. Launch Your Custom Ubuntu Instance:

You can now start your custom Ubuntu instance with:

```sh
wsl -d YourCustomUbuntu
```

3. Verify the Installation

1. Check WSL Versions:

- To verify that your custom image is installed and recognized, you can list your WSL distributions:

```sh
wsl -l -v
```

This command will list all installed WSL distributions and their versions.

2. Verify Ubuntu Version:

- Inside your WSL terminal, check the Ubuntu version to ensure it’s correctly installed:

```sh
lsb_release -a
```

4. Troubleshooting

- Custom Image Issues: If you encounter issues with your custom image, ensure that the .tar file is valid and not corrupted. You might need to recreate or download a fresh version.

- Permissions: Ensure you have the necessary permissions for the directory where you are installing the WSL instance.

- Update WSL: Make sure your WSL installation is up-to-date:

```sh
wsl --update
```

5. Build and Run with Docker Compose

Open a terminal (PowerShell or Command Prompt) and navigate to the directory containing docker-compose.yml.

Build and run the Docker containers:

```sh
docker-compose up --build
```

This command will build the Docker image according to the Dockerfile and start the container as specified in docker-compose.yml.

## Additional Resources

[Microsoft WSL Documentation](https://docs.microsoft.com/en-us/windows/wsl/)

[Ubuntu WSL Guide](https://ubuntu.com/wsl)

[Troubleshooting WSL](https://docs.microsoft.com/en-us/windows/wsl/install-troubleshoot)

## Contributing

Contributions are welcome! Please read our
[Contribution Guidelines](https://github.com/gvatsal60/project-template/blob/HEAD/CONTRIBUTING.md)
[Contribution Guidelines](https://github.com/gvatsal60/Custom-WSL-OS/blob/HEAD/CONTRIBUTING.md)
before submitting pull requests.

## License

This project is licensed under the Apache License 2.0 License - see the
[LICENSE](https://github.com/gvatsal60/project-template/blob/HEAD/LICENSE) file for details.
[LICENSE](https://github.com/gvatsal60/Custom-WSL-OS/blob/HEAD/LICENSE) file for details.