mirror of https://github.com/wg-easy/wg-easy
Bernd Storath
7 months ago
committed by
Bernd Storath
Bernd Storath
12 changed files with 304 additions and 23 deletions
|
After Width: | Height: | Size: 2.9 KiB |
|
After Width: | Height: | Size: 3.0 KiB |
@ -0,0 +1,3 @@ |
|||
--- |
|||
title: 'Optional Configuration' |
|||
--- |
|||
@ -0,0 +1,5 @@ |
|||
--- |
|||
title: Podman |
|||
--- |
|||
|
|||
TODO |
|||
@ -0,0 +1,23 @@ |
|||
--- |
|||
title: 'General Information' |
|||
--- |
|||
|
|||
## Coding Style |
|||
|
|||
When refactoring, writing or altering files, adhere to these rules: |
|||
|
|||
1. **Adjust your style of coding to the style that is already present**! Even if you do not like it, this is due to consistency. There was a lot of work involved in making all files consistent. |
|||
2. **Use `pnpm lint` to check your scripts**! Your contributions are checked by GitHub Actions too, so you will need to do this. |
|||
3. **Use the provided `.vscode/settings.json`** file. |
|||
|
|||
## Documentation |
|||
|
|||
Make sure to select `nightly` in the dropdown menu at the top. Navigate to the page you would like to edit and click the edit button in the top right. This allows you to make changes and create a pull-request. |
|||
|
|||
Alternatively you can make the changes locally. For that you'll need to have Docker installed. Navigate into the `docs/` directory. Then run: |
|||
|
|||
```sh |
|||
docker run --rm -it -p 8000:8000 -v "${PWD}:/docs" squidfunk/mkdocs-material |
|||
``` |
|||
|
|||
This serves the documentation on your local machine on port `8000`. Each change will be hot-reloaded onto the page you view, just edit, save and look at the result. |
|||
@ -0,0 +1,55 @@ |
|||
--- |
|||
title: 'Issues and Pull Requests' |
|||
--- |
|||
|
|||
This project is Open Source. That means that you can contribute on enhancements, bug fixing or improving the documentation. |
|||
|
|||
## Opening an Issue |
|||
|
|||
!!! attention |
|||
|
|||
**Before opening an issue**, read the [`README`][github-file-readme] carefully, study the docs for your version (maybe [latest][docs-latest]) and your search engine you trust. The issue tracker is not meant to be used for unrelated questions! |
|||
|
|||
When opening an issue, please provide details use case to let the community reproduce your problem. |
|||
|
|||
!!! attention |
|||
|
|||
**Use the issue templates** to provide the necessary information. Issues which do not use these templates are not worked on and closed. |
|||
|
|||
By raising issues, I agree to these terms and I understand, that the rules set for the issue tracker will help both maintainers as well as everyone to find a solution. |
|||
|
|||
Maintainers take the time to improve on this project and help by solving issues together. It is therefore expected from others to make an effort and **comply with the rules**. |
|||
|
|||
### Filing a Bug Report |
|||
|
|||
Thank you for participating in this project and reporting a bug. wg-easy is a community-driven project, and each contribution counts! |
|||
|
|||
Maintainers and moderators are volunteers. We greatly appreciate reports that take the time to provide detailed information via the template, enabling us to help you in the best and quickest way. Ignoring the template provided may seem easier, but discourages receiving any support (_via assignment of the label `meta/no template - no support`_). |
|||
|
|||
Markdown formatting can be used in almost all text fields (_unless stated otherwise in the description_). |
|||
|
|||
Be as precise as possible, and if in doubt, it's best to add more information that too few. |
|||
|
|||
When an option is marked with "not officially supported" / "unsupported", then support is dependent on availability from specific maintainers. |
|||
|
|||
## Pull Requests |
|||
|
|||
!!! question "Motivation" |
|||
|
|||
You want to add a feature? Feel free to start creating an issue explaining what you want to do and how you're thinking doing it. Other users may have the same need and collaboration may lead to better results. |
|||
|
|||
### Submit a Pull-Request |
|||
|
|||
The development workflow is the following: |
|||
|
|||
1. Fork the project and clone your fork with `git clone --recurse-submodules ...` or run `git submodule update --init --recursive` after you cloned your fork |
|||
2. Write the code that is needed :D |
|||
5. Document your improvements if necessary |
|||
6. [Commit][commit] (and [sign your commit][gpg]), push and create a pull-request to merge into `master`. Please **use the pull-request template** to provide a minimum of contextual information and make sure to meet the requirements of the checklist. |
|||
|
|||
Pull requests are automatically tested against the CI and will be reviewed when tests pass. When your changes are validated, your branch is merged. CI builds the new `:nightly` image every night and your changes will be includes in the next version release. |
|||
|
|||
[docs-latest]: https://wg-easy.github.io/wg-easy/latest |
|||
[github-file-readme]: https://github.com/wg-easy/wg-easy/blob/master/README.md |
|||
[commit]: https://help.github.com/articles/closing-issues-via-commit-messages/ |
|||
[gpg]: https://docs.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key |
|||
@ -0,0 +1,34 @@ |
|||
--- |
|||
title: Home |
|||
hide: |
|||
- navigation |
|||
--- |
|||
|
|||
# Welcome to the Documentation for `wg-easy` |
|||
|
|||
!!! info "This Documentation is Versioned" |
|||
|
|||
**Make sure** to select the correct version of this documentation! It should match the version of the image you are using. The default version corresponds to the `:latest` image tag - [the most recent stable release][docs-tagging]. |
|||
|
|||
This documentation provides you not only with the basic setup and configuration of wg-easy but also with advanced configuration, elaborate usage scenarios, detailed examples, hints and more. |
|||
|
|||
[docs-tagging]: ./usage.md#tagging-convention |
|||
|
|||
## About |
|||
|
|||
`wg-easy` is the easiest way to run WireGuard VPN + Web-based Admin UI. |
|||
|
|||
## Contents |
|||
|
|||
### Getting Started |
|||
|
|||
If you're new to wg-easy, make sure to read the [_Usage_ chapter][docs-usage] first. If you want to look at examples for Docker Run and Compose, we have an [_Examples_ page][docs-examples]. |
|||
|
|||
[docs-usage]: ./usage.md |
|||
[docs-examples]: ./examples/tutorials/basic-installation.md |
|||
|
|||
### Contributing |
|||
|
|||
We are always happy to welcome new contributors. For guidelines and entrypoints please have a look at the [Contributing section][docs-contributing]. |
|||
|
|||
[docs-contributing]: ./contributing/issues-and-pull-requests.md |
|||
@ -0,0 +1,75 @@ |
|||
--- |
|||
title: Usage |
|||
hide: |
|||
- navigation |
|||
--- |
|||
|
|||
This page explains how to get started with wg-easy. The guide uses Docker Compose as a reference. In our examples, a volume mounts the named volume [`etc_wireguard`][docs::dms-volumes-config] to `/etc/wireguard` inside the container. |
|||
|
|||
[docs::dms-volumes-config]: ./config/advanced/optional-config.md#volumes-config |
|||
|
|||
## Preliminary Steps |
|||
|
|||
Before you can get started with deploying your own VPN, there are some requirements to be met: |
|||
|
|||
1. You need to have a host that you can manage. |
|||
|
|||
### Host Setup |
|||
|
|||
There are a few requirements for a suitable host system: |
|||
|
|||
TODO: Requirements |
|||
|
|||
!!! note "About the Container Runtime" |
|||
|
|||
On the host, you need to have a suitable container runtime (like _Docker_ or _Podman_) installed. We assume [_Docker Compose_][docker-compose] is [installed][docker-compose-installation]. We have aligned file names and configuration conventions with the latest [Docker Compose specification][docker-compose-specification]. |
|||
|
|||
If you're using podman, make sure to read the related [documentation][docs-podman]. |
|||
|
|||
[docker-compose]: https://docs.docker.com/compose/ |
|||
[docker-compose-installation]: https://docs.docker.com/compose/install/ |
|||
[docker-compose-specification]: https://docs.docker.com/compose/compose-file/ |
|||
[docs-podman]: ./config/advanced/podman.md |
|||
|
|||
## Deploying the Actual Image |
|||
|
|||
### Tagging Convention |
|||
|
|||
To understand which tags you should use, read this section carefully. [Our CI][github-ci] will automatically build, test and push new images to the following container registry: |
|||
|
|||
2. GitHub Container Registry ([`ghcr.io/wg-easy/wg-easy`][ghcr-image]) |
|||
|
|||
All workflows are using the tagging convention listed below. It is subsequently applied to all images. |
|||
|
|||
| Event | Image Tags | |
|||
|-------------------------|-------------------------------| |
|||
| `cron` on `master` | `nightly` | |
|||
| `push` a tag (`v1.2.3`) | `1.2.3`, `1.2`, `1`, `latest` | |
|||
|
|||
[github-ci]: https://github.com/wg-easy/wg-easy/actions |
|||
[ghcr-image]: https://github.com/wg-easy/wg-easy/pkgs/container/wg-easy |
|||
|
|||
### Get All Files |
|||
|
|||
Issue the following command to acquire the necessary file: |
|||
|
|||
``` BASH |
|||
wget "https://raw.githubusercontent.com/wg-easy/wg-easy/master/docker-compose.yml" |
|||
``` |
|||
|
|||
### Configuration Steps |
|||
|
|||
1. First edit `docker-compose.yml` to your liking |
|||
2. Then configure the everything in the UI |
|||
|
|||
### Get Up and Running |
|||
|
|||
!!! danger "Using the Correct Commands For Stopping and Starting DMS" |
|||
|
|||
**Use `docker compose up / down`, not `docker compose start / stop`**. Otherwise, the container is not properly destroyed and you may experience problems during startup because of inconsistent state. |
|||
|
|||
Using `Ctrl+C` **is not supported either**! |
|||
|
|||
**That's it! It really is that easy**. |
|||
|
|||
|
|||
@ -0,0 +1,75 @@ |
|||
site_name: "wg-easy" |
|||
site_description: "The easiest way to run WireGuard VPN + Web-based Admin UI." |
|||
site_author: "wg-easy (Github Organization)" |
|||
copyright: '<p>© <a href="https://github.com/wg-easy"><em>Wireguard Easy Organization</em></a><br/><span>This project is licensed under the CC BY-NC-SA 4.0 license.</span></p>' |
|||
|
|||
repo_url: https://github.com/wg-easy/wg-easy |
|||
repo_name: wg-easy |
|||
|
|||
edit_uri: "edit/master/docs/content" |
|||
|
|||
docs_dir: "content/" |
|||
|
|||
site_url: https://wg-easy.github.io/wg-easy |
|||
|
|||
theme: |
|||
name: material |
|||
favicon: assets/logo/favicon.png |
|||
logo: assets/logo/logo.png |
|||
icon: |
|||
repo: fontawesome/brands/github |
|||
features: |
|||
- navigation.tabs |
|||
- navigation.top |
|||
- navigation.expand |
|||
- navigation.instant |
|||
- content.action.edit |
|||
- content.action.view |
|||
- content.code.annotate |
|||
palette: |
|||
# Light mode |
|||
- media: "(prefers-color-scheme: light)" |
|||
scheme: default |
|||
primary: grey |
|||
accent: red |
|||
toggle: |
|||
icon: material/weather-night |
|||
name: Switch to dark mode |
|||
# Dark mode |
|||
- media: "(prefers-color-scheme: dark)" |
|||
scheme: slate |
|||
primary: grey |
|||
accent: red |
|||
toggle: |
|||
icon: material/weather-sunny |
|||
name: Switch to light mode |
|||
|
|||
extra: |
|||
version: |
|||
provider: mike |
|||
|
|||
markdown_extensions: |
|||
- toc: |
|||
anchorlink: true |
|||
- abbr |
|||
- attr_list |
|||
- admonition |
|||
- pymdownx.details |
|||
- pymdownx.superfences: |
|||
custom_fences: |
|||
- name: mermaid |
|||
class: mermaid |
|||
format: !!python/name:pymdownx.superfences.fence_code_format |
|||
- pymdownx.tabbed: |
|||
alternate_style: true |
|||
slugify: !!python/object/apply:pymdownx.slugs.slugify |
|||
kwds: |
|||
case: lower |
|||
- pymdownx.tasklist: |
|||
custom_checkbox: true |
|||
- pymdownx.magiclink |
|||
- pymdownx.inlinehilite |
|||
- pymdownx.tilde |
|||
- pymdownx.emoji: |
|||
emoji_index: !!python/name:material.extensions.emoji.twemoji |
|||
emoji_generator: !!python/name:material.extensions.emoji.to_svg |
|||
Loading…
Reference in new issue