How to setup Outline's development environment in WSL2? #6049
Unanswered
amoralesc
asked this question in
Show and tell
Replies: 1 comment
-
@tommoor A mention in the official docs at https://docs.getoutline.com/s/hosting/doc/local-development-5hEhFRXow7 wouldn't hurt to future devs trying to setup their environment in Windows/WSL. I noticed some fumes back in #4168 |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
This is a step-by-step guide to setup a local/development environment for Outline in WSL2 (Ubuntu distro). It builds upon the official docs for local development, while fixing all the issues that arise when trying to use WSL2 instead of a normal linux distro. Hopefully this guide helps other devs that tried setting up the project in Windows but ultimately failed.
There is a lot of troubleshooting going on, so I will try to be as explicit as possible! This includes copying steps already highlighted in the official guide btw.
Dependencies
Install these dependencies in WSL if you don't already have them:
Download
Clone the source code with the following command:
Configuration
Alias for
docker-compose
The
Makefile
uses the olddocker-compose
syntax to manage the containers. If you use the new syntax (docker compose
), you can create an alias for it so that you don't have to edit the Makefile (which shouldn't be edited and committed btw).Run this beautiful one-liner in your terminal, which creates the script
/usr/local/bin/docker-compose
to calldocker compose
with its arguments.Source: StackOverflow
Env
Copy the .env.sample file to .env
For development, the contents should mostly work as in the sample. That said, you need to configure file storage correctly or the server will fail.
Set file storage
The current sample uses:
FILE_STORAGE=local
(save images and file attachments in a local directory managed by Outline)FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data
(path to where the files are stored)Point
FILE_STORAGE_LOCAL_ROOT_DIR
to a directory where the server would have write access. A suggestion is a relative path to a local directory like./data
or./uploads
. Be careful not to commit uploaded data!Run the project for the first time
The project uses a
Makefile
to run all the needed commands. We need to run the server and the containers a first time to generate the SSL certificates which Windows (and the browsers) will need to correctly connect through HTTPS.Run the project with:
This might take a while the images are pulled and the deps are installed. After it's all done, the server will be running. Keep in mind that this will hang the terminal, and if closed or cancelled, the server will go down. The containers won't, and can be stopped with
make destroy
.Running the environment will also require the following ports clear in WSL:
3000-3001
: used by Outline (They also need to be clear on the Windows side)4569
: used by FakeS35432
: used by Postgres6379
: used by RedisIf you can't use those ports, replace them in the relevant
docker-compose.yml
and.env
parts.Hosts
When
make up
is first executed, mkcert will create a self-signed certificate for the*.outline.dev
domains, whichapp.outline.dev
andwiki.outline.dev
use for HTTPS. You will need to edit the/etc/hosts
file both in Windows and WSL to correctly direct the domains to the loopback ip (127.0.0.1).Do all the following steps:
Configure hosts in WSL
This one is simple. Edit the
/etc/hosts
file by adding these directives (requires sudo):Windows
Install CA
The first step is to install the root certificate in the Windows side. In a WSL terminal, run:
mkcert -CAROOT # ~/.local/share/mkcert
This path corresponds to the root CA, and it's usually placed in that path. Verify the name of the certificate with:
The public certificate (
rootCA.pem
) is the one we will install in Windows. Create a copy of it in an easy-to-find place on the Windows side (Windows drives are mounted atmnt
, soC:
would be at/mnt/c
and so on). I'm copying mine on the root of theD:
drive:cp ~/.local/share/mkcert/rootCA.pem /mnt/d/outline_ca_mkcert.crt
Now for the easy part, on the Windows explorer:
Install certificate...
Local Machine
and pressNext
(requires Admin privileges)Place all certificates in the following store
andBrowse...
Trusted Root Certification Authorities
, save and exitSource: github.com/FiloSottile/mkcert #357
Install CA in Firefox
If you are using Firefox as your browser, it may still fail to recognize the CA cert and will need a manual install of the certificate.
~/.local/share/mkcert
)rootCA.pem
Source: github.com/FiloSottile/mkcert #6
Source: github.com/FiloSottile/mkcert #370
Configure hosts in Windows
The hosts file is located at the
C:\Windows\System32\drivers\etc\
directory. You will need admin privileges to edit it. The simple approach is to run Notepad as an administrator and then browse to that directory (File
>Open
), and open thehosts
file. Add these directives at the top of the file, before the comments:To check the redirection is working correctly, open a Powershell terminal and run (all separate commands):
If everything went well, the ping will resolve to 127.0.0.1.
If the host wasn't found, there is a problem going on. The hosts file is rather finicky and will fail to correctly parse for a bunch of reason. This StackExchange answer has a lot of troubleshooting steps to correctly configure the file.
Port-forward to WSL (Must be repeated every time WSL is restarted)
The last networking step to face is port-forward the server running in WSL to the loopback ip of our computer. By default, WSL only port-forwards to
localhost
, which is not exactly 127.0.0.1. This means that the URL https://app.outline.dev:3000/ won't correctly resolve from the browser to our server. The solution is to port-forward all requests related to the app from Windows to WSL.First find out the WSL's IP. Run ifconfig in a WSL terminal:
And look for the IP at the
eth0
interface. Alternatively, run ipconfig in a Powershell terminal:And look for the WSL ethernet adapter IP. Afterwards, in a Powershell terminal with admin privileges, run (change ports if they don't correspond to Outline's server ports):
This will correctly route all requests going to 127.0.0.1:3000 to WSL and finally to Outline. You can always check out the forwards with:
Source: StackOverflow
Running
And voilá! After all configurations, your local environment should be configured correctly. Visit https://app.outline.dev:3000/ to check the app out.
As always, the command to run the server and containers is:
To stop, a CTRL + C and
make destroy
will suffice.Authentication
Finally, to authenticate in the app, you will need an OIDC client. However, for local development you can provision an admin user with email login by running the following command. The link for login will appear in the server logs, so you only need to follow the printed link:
yarn build:server && node build/server/scripts/seed.js my@email.com
Afterthoughts
This guide should be enough to get an initial dev environment in WSL. I hope it helps you!
Beta Was this translation helpful? Give feedback.
All reactions