diff --git a/README.md b/README.md index 8387fdd..611974b 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,38 @@ A web frontend for the [headscale](https://github.com/juanfont/headscale) Tailsc ## Installation Headscale-UI is designed to compile to a vanilla SPA that can be statically hosted on any site. Just take the latest build and host using a file server such as [caddy](https://caddyserver.com/), [apache httpd](https://httpd.apache.org/) or [nginx](https://www.nginx.com/). A sample Caddyfile is provided for self signed TLS certificates, and can be easily adjusted to proper HTTPS hosting. -> :warning: Headscale requires special configuration to provide CORS headers for headscale-ui to operate. See [This Github Issue](https://github.com/juanfont/headscale/issues/623) for details +While not currently embedded into the headscale binary, there is no reason why the compiled files couldn't be embedded in the future. + +> :warning: Headscale (not headscale-ui) requires special configuration to provide CORS headers for headscale-ui to operate. See [This Github Issue](https://github.com/juanfont/headscale/issues/623) for details ## Development +Development can be done either by using the official development docker image, or via a normal nodejs installation. +### Quick Start (Docker) +Run the following `docker` command: +`docker run -p 443:443 -p 3000:3000 -v "$(pwd)"/data:/data ghcr.io/gurucomputing/headscale-ui:latest` + +or on a selinux enabled distro (like fedora): +`docker run -p 443:443 -p 3000:3000 -v "$(pwd)"/data:/data:Z ghcr.io/gurucomputing/headscale-ui:latest` +A full browser based vscode development environment will be found at `http://:3000/?tkn=`. The authentication token will be printed in your docker logs, and must be included in the URL. + +> You can set a custom connection token using the $CONNECTION_TOKEN environment variable + +Once started, the development environment can be found at `/data/headscale-ui` inside vscode. The development server (including hot reloading) will be found at port 443. The `npm run dev` process can be accessed within tmux, accessed with `tmux a` in the vscode terminal. + +### Remapping port 443 +You may wish to remap port 443 to something else (like 9443). You *cannot* remap via docker directly (IE: `docker run -p 9443:443`): doing so breaks the hot-reload mechanism. Instead, you must change the port the server runs on, and map it correctly (IE: `docker run -p 9443:9443`). You can change the server port under `package.json` once the container is loaded (see below gif for details): + +![](/documentation/assets/README_ports.gif) + +If you wish to do the same with the `npm run stage` mechanism, you can edit the included `Caddyfile` to run on the correct port, changing `:443` to the appropriate port. + +### Docker Guide +see [docker environment](/documentation/Docker) for additional variables and options + +### Quick Start (npm) +Clone the repository with `git clone https://github.com/gurucomputing/headscale-ui`, navigate to the project directory, and install with `npm install`. + +Development environment can be ran with `npm run dev`. Static site can be generated with `npm run build`. Testing (and potentially even production) can be ran with `npm run stage` *if* caddy is installed in your distribution (red hat/fedora can install with `sudo dnf install caddy`). ### Style Guide see [style](/documentation/Style.md) for details diff --git a/docker/development/dockerfile b/docker/development/dockerfile new file mode 100644 index 0000000..588d755 --- /dev/null +++ b/docker/development/dockerfile @@ -0,0 +1,57 @@ +FROM fedora:36 + +# Arguments +ARG OPENVSCODE_VERSION="1.68.1" +ARG NODEJS_VERSION="16" +# Volumes +VOLUME /data + +# Ports +# openvscode server port. Note: Runs HTTP by default +EXPOSE 3000 +# Dev Web Server port. Runs a self signed SSL certificate +EXPOSE 443 + +# System Environment Variables +ENV PATH="/opt/vscode:${PATH}" +ENV HOME="/data/home" +ENV SHELL="/usr/bin/fish" + +# User Set Environment Variables +# Set to false if you do not want to attempt to pull a repository on first load +ENV AUTOINITIALIZE=true +# sets a connection token for VSCode Server. https://github.com/gitpod-io/openvscode-server#securing-access-to-your-ide +ENV USE_CONNECTION_TOKEN=true +#Set to a secret to have some measure of protection for vscode. Randomized if left blank +ENV CONNECTION_TOKEN= +# Project name. Typically the same as the project in the URL +ENV PROJECT_NAME="headscale-ui" +# URL for the github/git location +ENV PROJECT_URL="https://github.com/gurucomputing/headscale-ui" +# autostart the dev command on boot? +ENV AUTOSTART=true +# command to run in the background on startup +ENV DEV_COMMAND="npm run dev" + +# Set the staging environment +WORKDIR /staging/scripts +WORKDIR /staging +RUN chown 1000:1000 /staging + +# Copy across the scripts folder +COPY scripts/* ./scripts/ + +# Set permissions for all scripts. We do not want normal users to have write +# access to the scripts +RUN chown -R 0:0 scripts +RUN chmod -R 755 scripts + +# Build the image. This build runs as root +RUN /staging/scripts/1-image-build.sh + +# set to the non-root user +USER nodejs + +WORKDIR /data + +ENTRYPOINT /bin/sh /staging/scripts/2-initialise.sh \ No newline at end of file diff --git a/docker/development/scripts/1-image-build.sh b/docker/development/scripts/1-image-build.sh new file mode 100644 index 0000000..c4ab350 --- /dev/null +++ b/docker/development/scripts/1-image-build.sh @@ -0,0 +1,55 @@ +#!/bin/sh + +# script environment +# turn on bash logging +set -x + +# script variables +OPENVSCODE_URL="https://github.com/gitpod-io/openvscode-server/releases/download/openvscode-server-v$OPENVSCODE_VERSION/openvscode-server-v$OPENVSCODE_VERSION-linux-x64.tar.gz" +OPENVSCODE_RELEASE="openvscode-server-v$OPENVSCODE_VERSION-linux-x64" + +# install dependencies +# ncurses basic command line QOL improvements +# tmux used for monitoring secondary processes +# git It's git! +# fish prettier shell +# caddy file server for stage testing +dnf install -y ncurses tmux git fish caddy + +# Add the ability to set file permissions on /data to the non-privileged user +echo "ALL ALL=NOPASSWD: /bin/chown -R 1000\:1000 /data" >> /etc/sudoers + +# install nodejs +dnf module install -y nodejs:${NODEJS_VERSION} + +# enable openssh +ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key -N '' + +# create the non-root user +groupadd -g 1000 nodejs +useradd -u 1000 -g 1000 nodejs + +# set the default shell to the chosen shell +usermod --shell ${SHELL} nodejs + +# Add the ability to set file permissions to the non-privileged user +echo "ALL ALL=NOPASSWD: /bin/chown -R 1000\:1000 /data" >> /etc/sudoers + +# install openVSCode +cd /opt + +### Download Open VSCode +curl -LJO "$OPENVSCODE_URL" + +### Extract and move into directory +tar -xzf "$OPENVSCODE_RELEASE.tar.gz" +mv $OPENVSCODE_RELEASE openvscode-server +rm -f "$OPENVSCODE_RELEASE.tar.gz" + +# create data and home directories +mkdir -p /data/home + +# set tmux to use mouse scroll +echo "set -g mouse on" > /data/home/.tmux.conf + +chown -R 1000:1000 /data \ No newline at end of file diff --git a/docker/development/scripts/2-initialise.sh b/docker/development/scripts/2-initialise.sh new file mode 100644 index 0000000..a853113 --- /dev/null +++ b/docker/development/scripts/2-initialise.sh @@ -0,0 +1,66 @@ +#!/bin/sh + +#----# +# placeholder for testing +# while true; do sleep 1; done +#----# + +# set file permissions if required +if [ $(id -u) -ne $(stat -c %u /data) ] +then + if [ $(id -u) -eq 1000 ] + then + echo "---- Detected File Permission Mismatch ----" + echo "---- Forcing File Permissions to the node user ----" + sudo /bin/chown -R 1000:1000 /data + else + echo "---- You are not running as the node user AND your file permissions don't match your user ---\n" + echo "---- You may need to manually fix your file permissions ----" + fi +fi + +# create the home directory if it doesn't exist +cd /data +if ! [ -d /data/home ] +then + mkdir /data/home + # set tmux to use mouse scroll + echo "set -g mouse on" > /data/home/.tmux.conf +fi + +#attempt to initialize and run a repository +if [[ "$AUTOINITIALIZE" == "true" ]] +then + # check if there is a copy of ${PROJECT_NAME}, if not assume this is a fresh install + if ! [ -d /data/${PROJECT_NAME} ] + then + echo "-- Fresh Install detected, setting up your dev environment --" + echo "-- Installing Source --" + # clone the latest version of ${PROJECT_NAME} + cd /data + git clone ${PROJECT_URL} + cd ${PROJECT_NAME} + npm install + else + cd /data/${PROJECT_NAME} + fi + + if [[ "$AUTOSTART" == "true" ]] + then + # run the sub process + tmux new-session -d "${DEV_COMMAND}; sh" + fi +fi + +# run the main process. +if [[ "$USE_CONNECTION_TOKEN" == "false" ]] +then + /opt/openvscode-server/bin/openvscode-server --host 0.0.0.0 --without-connection-token +else + if [[ "$CONNECTION_TOKEN" == "" ]] + then + CONNECTION_TOKEN=$(echo $RANDOM | md5sum | head -c 20) + echo "connection token is not set, randomising to $CONNECTION_TOKEN" + fi + /opt/openvscode-server/bin/openvscode-server --host 0.0.0.0 --connection-token=${CONNECTION_TOKEN} +fi \ No newline at end of file diff --git a/documentation/Docker.md b/documentation/Docker.md new file mode 100644 index 0000000..e69de29 diff --git a/documentation/Style.md b/documentation/Style.md index 41337ad..bfdadfa 100644 --- a/documentation/Style.md +++ b/documentation/Style.md @@ -2,11 +2,16 @@ Rough style guide for development in Headscale-UI. Documentation will be improved as style gets more defined ## CSS -CSS should be written as tailwind classes. Where (when) tailwind classes become cumbersome (10+ classes for an HTML object), classes should instead be broken into a separate `