diff --git a/docs/Gemfile b/docs/Gemfile index 0805eafbe..d131b5981 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -9,7 +9,7 @@ source "https://rubygems.org" # Happy Jekylling! gem "jekyll", "~> 4.2.1" # This is the default theme for new Jekyll sites. You may change this to anything you like. -gem "minima", "~> 2.5" +gem "just-the-docs" # If you want to use GitHub Pages, remove the "gem "jekyll"" above and # uncomment the line below. To upgrade, run `bundle update github-pages`. # gem "github-pages", group: :jekyll_plugins @@ -27,3 +27,4 @@ end # Performance-booster for watching directories on Windows gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin] + diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 0a5e4d664..f50d59a0e 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -5,14 +5,14 @@ GEM public_suffix (>= 2.0.2, < 5.0) colorator (1.1.0) concurrent-ruby (1.1.9) - em-websocket (0.5.2) + em-websocket (0.5.3) eventmachine (>= 0.12.9) - http_parser.rb (~> 0.6.0) + http_parser.rb (~> 0) eventmachine (1.2.7) ffi (1.15.4) forwardable-extended (2.6.0) - http_parser.rb (0.6.0) - i18n (1.8.10) + http_parser.rb (0.8.0) + i18n (1.8.11) concurrent-ruby (~> 1.0) jekyll (4.2.1) addressable (~> 2.4) @@ -37,6 +37,10 @@ GEM jekyll (>= 3.8, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) + just-the-docs (0.3.3) + jekyll (>= 3.8.5) + jekyll-seo-tag (~> 2.0) + rake (>= 12.3.1, < 13.1.0) kramdown (2.3.1) rexml kramdown-parser-gfm (1.1.0) @@ -46,13 +50,10 @@ GEM rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) mercenary (0.4.0) - minima (2.5.1) - jekyll (>= 3.5, < 5.0) - jekyll-feed (~> 0.9) - jekyll-seo-tag (~> 2.1) pathutil (0.16.2) forwardable-extended (~> 2.6) public_suffix (4.0.6) + rake (13.0.6) rb-fsevent (0.11.0) rb-inotify (0.10.1) ffi (~> 1.0) @@ -66,15 +67,15 @@ GEM unicode-display_width (1.8.0) PLATFORMS - ruby + x86_64-darwin-21 DEPENDENCIES jekyll (~> 4.2.1) jekyll-feed (~> 0.12) - minima (~> 2.5) + just-the-docs tzinfo (~> 1.2) tzinfo-data wdm (~> 0.1.1) BUNDLED WITH - 2.1.4 + 2.2.33 diff --git a/docs/_config.yml b/docs/_config.yml index a55ef9de1..4a993961e 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -8,7 +8,7 @@ # For technical reasons, this file is *NOT* reloaded automatically when you use # 'bundle exec jekyll serve'. If you change this file, please restart the server process. # -# If you need help with YAML syntax, here are some quick references for you: +# If you need help with YAML syntax, here are some quick references for you: # https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml # https://learnxinyminutes.com/docs/yaml/ # @@ -18,20 +18,47 @@ # You can create any custom variable you would like, and they will be accessible # in the templates via {{ site.myvariable }}. -title: Firezone Documentation -email: feedback-docs@firez.one +title: Docs | Firezone +email: support@firez.one description: >- # this means to ignore newlines until "baseurl:" - Firezone Reference Documentation. - Open-source, WireGuard-based VPN server and firewall for Linux. -baseurl: "" # the subpath of your site, e.g. /blog -url: "https://docs.firez.one" # the base hostname & protocol for your site, e.g. http://example.com + Documentation site for Firezone's VPN and firewall server. +baseurl: "/docs" # the subpath of your site, e.g. /blog +url: "https://www.firez.one" # the base hostname & protocol for your site, e.g. http://example.com +permalink: pretty twitter_username: firezonevpn github_username: firezone +# Set a path/url to a logo that will be displayed instead of the title +logo: "/assets/images/firezone-logo-wordmark-dark.svg" + # Build settings -theme: minima +theme: just-the-docs plugins: - jekyll-feed +color_scheme: fz + +# Footer content +# appears at the bottom of every page's main content + +# footer_content: "" + +# Footer last edited timestamp +last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter +last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true # show or hide edit this page link +gh_edit_link_text: "Edit on GitHub" +gh_edit_repository: "https://github.com/firezone/firezone" # the github URL for your repo +gh_edit_branch: "master" # the branch that your docs is served from +# gh_edit_source: docs # the source that your files originate from +gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately + +# Aux links for the upper right navigation +aux_links: + "Schedule a Demo": + - "https://e04kusl9oz5.typeform.com/to/BkWP2ys1" + # Exclude from processing. # The following items will not be processed, by default. diff --git a/docs/_includes/footer_custom.html b/docs/_includes/footer_custom.html new file mode 100644 index 000000000..c4dbbeb1c --- /dev/null +++ b/docs/_includes/footer_custom.html @@ -0,0 +1,5 @@ +{%- if site.footer_content -%} +
+ Company | Github | Twitter +
+{%- endif -%} \ No newline at end of file diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html new file mode 100644 index 000000000..79ea6beda --- /dev/null +++ b/docs/_layouts/default.html @@ -0,0 +1,199 @@ +--- +layout: table_wrappers +--- + + + + +{% include head.html %} + + + + Link + + + + + + Search + + + + + + Menu + + + + + + Expand + + + + + + Document + + + + + + +
+
+ {% include title.html %} + + + +
+ +
+
+
+ {% if site.search_enabled != false %} +
+
+ + +
+
+
+ {% endif %} + {% include header_custom.html %} + {% if site.aux_links %} + + {% endif %} +
+
+ {% unless page.url == "/" %} + {% if page.parent %} + {%- for node in pages_list -%} + {%- if node.parent == nil -%} + {%- if page.parent == node.title or page.grand_parent == node.title -%} + {%- assign first_level_url = node.url | absolute_url -%} + {%- endif -%} + {%- if node.has_children -%} + {%- assign children_list = pages_list | where: "parent", node.title -%} + {%- for child in children_list -%} + {%- if page.url == child.url or page.parent == child.title -%} + {%- assign second_level_url = child.url | absolute_url -%} + {%- endif -%} + {%- endfor -%} + {%- endif -%} + {%- endif -%} + {%- endfor -%} + + {% endif %} + {% endunless %} +
+ {% if site.heading_anchors != false %} + {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %} + {% else %} + {{ content }} + {% endif %} + + {% if page.has_children == true and page.has_toc != false %} +
+

Table of contents

+
    + {%- assign children_list = pages_list | where: "parent", page.title | where: "grand_parent", page.parent -%} + {% for child in children_list %} +
  • + {{ child.title }}{% if child.summary %} - {{ child.summary }}{% endif %} +
    • + {% endfor %} +
+ {% endif %} + + {% capture footer_custom %} + {%- include footer_custom.html -%} + {% endcapture %} + {% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %} +
+
+ {% if site.back_to_top %} +

{{ site.back_to_top_text }}

+ {% endif %} + + {{ footer_custom }} + + {% if site.last_edit_timestamp or site.gh_edit_link %} +
+ {% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %} +

+ Page last modified: {{ page.last_modified_date | date: site.last_edit_time_format }}. +

+ {% endif %} + {% if + site.gh_edit_link and + site.gh_edit_link_text and + site.gh_edit_repository and + site.gh_edit_branch and + site.gh_edit_view_mode + %} +

+ {{ site.gh_edit_link_text }} +

+ {% endif %} +
+ {% endif %} +
+ {% endif %} + +
+
+ + {% if site.search_enabled != false %} + {% if site.search.button %} + + + + {% endif %} + +
+ {% endif %} +
+ + diff --git a/docs/_posts/2021-12-08-welcome-to-jekyll.markdown b/docs/_posts/2021-12-08-welcome-to-jekyll.markdown new file mode 100644 index 000000000..71e6ed3ff --- /dev/null +++ b/docs/_posts/2021-12-08-welcome-to-jekyll.markdown @@ -0,0 +1,29 @@ +--- +layout: post +title: "Welcome to Jekyll!" +date: 2021-12-08 10:08:59 -0800 +categories: jekyll update +--- +You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated. + +Jekyll requires blog post files to be named according to the following format: + +`YEAR-MONTH-DAY-title.MARKUP` + +Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is the file extension representing the format used in the file. After that, include the necessary front matter. Take a look at the source for this post to get an idea about how it works. + +Jekyll also offers powerful support for code snippets: + +{% highlight ruby %} +def print_hi(name) + puts "Hi, #{name}" +end +print_hi('Tom') +#=> prints 'Hi, Tom' to STDOUT. +{% endhighlight %} + +Check out the [Jekyll docs][jekyll-docs] for more info on how to get the most out of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub repo][jekyll-gh]. If you have questions, you can ask them on [Jekyll Talk][jekyll-talk]. + +[jekyll-docs]: https://jekyllrb.com/docs/home +[jekyll-gh]: https://github.com/jekyll/jekyll +[jekyll-talk]: https://talk.jekyllrb.com/ diff --git a/docs/_sass/color_schemes/fz.scss b/docs/_sass/color_schemes/fz.scss new file mode 100644 index 000000000..1b1c7d8f5 --- /dev/null +++ b/docs/_sass/color_schemes/fz.scss @@ -0,0 +1,34 @@ +// Colors + +$fz-grey-dk-000: #90867f; +$fz-grey-dk-100: #766a60; +$fz-grey-dk-200: #4c3e33; +$fz-grey-dk-300: #1b140e; + +$fz-grey-lt-000: #fcfcfc; +$fz-grey-lt-100: #f8f7f7; +$fz-grey-lt-200: #ebebea; +$fz-grey-lt-300: #dfdedd; + +$fz-purple-000: #4805ff; +$fz-purple-100: #3400c2; +$fz-purple-200: #37007f; +$fz-purple-300: #28005c; + +$fz-orange: #FF7300; + +$link-color: $fz-purple-000; +$btn-primary-color: $fz-purple-100; + +// Fonts + +$body-font-family: "Open Sans", sans-serif; + +@font-face { + font-family: "Open Sans"; + src: url("../assets/fonts/OpenSans-Italic-VariableFont_wdth,wght.ttf"); +} + +// Borders + +$border-color: $fz-grey-lt-100; \ No newline at end of file diff --git a/docs/assets/fonts/OpenSans-Italic-VariableFont_wdth,wght.ttf b/docs/assets/fonts/OpenSans-Italic-VariableFont_wdth,wght.ttf new file mode 100644 index 000000000..0fea34ba2 Binary files /dev/null and b/docs/assets/fonts/OpenSans-Italic-VariableFont_wdth,wght.ttf differ diff --git a/docs/assets/images/firezone-logo-wordmark-dark.svg b/docs/assets/images/firezone-logo-wordmark-dark.svg new file mode 100644 index 000000000..3d7b990a9 --- /dev/null +++ b/docs/assets/images/firezone-logo-wordmark-dark.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/docs/deploying-and-configuring.md b/docs/docs/deploying-and-configuring.md new file mode 100644 index 000000000..5fae43e0e --- /dev/null +++ b/docs/docs/deploying-and-configuring.md @@ -0,0 +1,139 @@ +--- +layout: default +title: Deploying and Configuring +nav_order: 1 +--- + +# Deploying and Configuring +{: .no_toc } + + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + + +Firezone consists of a single distributable Linux package that you install and +manage yourself. Management of the Firezone installation is handled by the +`firezone-ctl` utility while management of the VPN and firewall themselves are +handled by the Web UI. + +Firezone acts as a frontend to both the WireGuard kernel module and +[netfilter](https://netfilter.org) kernel subsystem. It creates a WireGuard +interface (by default called `wg-firezone`) and +`firezone` netfilter table and adds appropriate routes to the routing +table. Other programs that modify the Linux routing table or netfilter firewall +may interfere with Firezone's operation. + +### SSL + +Firezone requires a valid SSL certificate and a matching DNS record to run in +production. We recommend using [Let's Encrypt](https://letsencrypt.org) to +generate a free SSL cert for your domain. + +### Security Considerations + +Firezone is **beta** software. We highly recommend **limiting network access to +the Web UI** (by default port tcp/443) to prevent exposing it to the public Internet. + +The WireGuard listen port (by default port udp/51821) should be exposed to allow user +devices to connect. + +## Supported Linux Distributions + +Firezone currently supports the following distributions and architectures: + +| Name | Architectures | Status | Notes | +| --- | --- | --- | --- | +| AmazonLinux 2 | `amd64` | **Fully-supported** | See [AmazonLinux 2 Notes](#amazonlinux-2-notes) | +| CentOS 7 | `amd64` | **Fully-supported** | See [CentOS 7 Notes](#centos-7-notes) | +| CentOS 8 | `amd64` | **Fully-supported** | Works as-is | +| Debian 10 | `amd64` | **Fully-supported** | See [Debian 10 Notes](#debian-10-notes)| +| Debian 11 | `amd64` | **Fully-supported** | Works as-is | +| Fedora 33 | `amd64` | **Fully-supported** | Works as-is | +| Fedora 34 | `amd64` | **Fully-supported** | Works as-is | +| Ubuntu 18.04 | `amd64` | **Fully-supported** | See [Ubuntu 18.04 Notes](#ubuntu-1804-notes) | +| Ubuntu 20.04 | `amd64` | **Fully-supported** | Works as-is | +| openSUSE Leap 15.3 | `amd64` | **Fully-supported** | See [openSUSE Notes](#opensuse-notes) | + +If your distro isn't listed here please +[open an issue](https://github.com/firezone/firezone/issues/new/choose) and let +us know. New distros are being supported on a regular basis and there's a good +chance yours will be added soon. + +### AmazonLinux 2 Notes + +Kernel upgrade required: + +```bash +sudo amazon-linux-extras install -y kernel-5.10 +``` + +### CentOS 7 Notes + +Kernel upgrade to 4.19+ required. See [this guide +](https://medium.com/@nazishalam07/update-centos-kernel-3-10-to-5-13-latest-9462b4f1e62c) +for an example. + +### Ubuntu 18.04 Notes + +Kernel upgrade to 4.19+ required. E.g. `apt install linux-image-generic-hwe-18.04` + +### Debian 10 Notes + +Kernel upgrade to 4.19+ required. See [this guide +](https://jensd.be/968/linux/install-a-newer-kernel-in-debian-10-buster-stable) +for an example. + +### openSUSE Notes + +Firezone requires the `setcap` utility, but some recent openSUSE releases may +not have it installed by default. To fix, ensure `libcap-progs` is installed: + +```bash +sudo zypper install libcap-progs +``` + +## Installation Instructions + +Assuming you're running Linux kernel 4.19+ on one of the supported distros +listed above, follow these steps to setup and install Firezone: + +1. [Install WireGuard](https://www.wireguard.com/install/) for your distro. If using Linux kernel 5.6 or higher, skip + this step. +2. Download the relevant package for your distribution from the + [releases page](https://github.com/firezone/firezone/releases). +3. Install with `sudo rpm -i firezone*.rpm` or `sudo dpkg -i firezone*.deb` + depending on your distro. +4. Bootstrap the application with `sudo firezone-ctl reconfigure`. This will initialize config files, set up needed services and generate the default configuration. +5. Edit the default configuration located at `/etc/firezone/firezone.rb`. + At a minimum, you'll need to review the following configuration variables: + + ```ruby + # Auto-generated based on the server's hostname. + # Set this to the FQDN used to access the Web UI. + default['firezone']['fqdn'] = 'firezone.example.com' + + # ... + + # Specify the path to your SSL cert and private key. + # If set to nil, a self-signed cert will be generated for you. + default['firezone']['ssl']['certificate'] = '/path/to/cert.pem' + default['firezone']['ssl']['certificate_key'] = '/path/to/key.pem' + ``` +6. Reconfigure the application to pick up the new changes: `sudo firezone-ctl reconfigure`. +7. Finally, create an admin user with `sudo firezone-ctl create-or-reset-admin`. + The login credentials will be printed to the console output. +8. Now you should be able to log into the web UI at the FQDN you specified in + step 5 above, e.g. `https://firezone.example.com` + +## Configuration File + +User-configurable settings can be found in `/etc/firezone/firezone.rb`. + +Changing this file **requires re-running** `sudo firezone-ctl reconfigure` to pick up +the changes and apply them to the running system. \ No newline at end of file diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 000000000..71776b11a Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/index.markdown b/docs/index.markdown index 37e799728..bb04b25f5 100644 --- a/docs/index.markdown +++ b/docs/index.markdown @@ -3,8 +3,4 @@ # To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults layout: home ---- - -Firezone Documentation - -WIP +--- \ No newline at end of file