Beginners Guide to Install Discourse on Windows 10 for Development

So you want to set up a development environment for Discourse on Windows 10? You can do it easily using Windows Subsystem for Linux feature. It is faster too :star_struck:.

This setup requires the WSL 2 installation. It is only available in Windows 10 builds 18917 or higher. We’ll assume that you already installed Windows Subsystem for Linux 2 (Ubuntu) on your Windows 10 system. Let’s begin!

  1. Initially follow the steps from the topic Beginners Guide to Install Discourse on Ubuntu for Development until the step Clone Discourse.

    Before setting up the database you have to start PostgreSQL service & Redis server manually using following commands

    sudo service postgresql start
    redis-server --daemonize yes
  2. Then go through all the remaining steps of the Ubuntu guide.

Now your development environment is almost ready. The only problem is every time when you open Ubuntu on Windows you have to start the PostgreSQL service & Redis server manually. Don’t worry we can have a workaround for this by creating a custom command :wink:

cd ~

Create a new file using the command nano start-discourse and paste the content below then save and exit.


# to start PostgreSQL
sudo service postgresql start

# to start Redis server
redis-server --daemonize yes

Now modify the CHMOD using below command

chmod +x start-discourse

And copy the file to your bin folder

sudo cp start-discourse /usr/bin/

It’s done. Now, whenever you open the Ubuntu bash just run the command below and start developing :+1:


Alternatively, if you are using Windows 10 enterprise, pro, or education edition then you can create a Linux virtual machine in hyper-v to set up the Discourse dev environment.

How to install Discourse on windows
Help installing Discourse for Developer
Beginners Guide to Install Discourse on Ubuntu for Development
Database connection error when setting up Discourse development environment using Linux Bash Shell on Windows 10
Restoring backup fails in Win10/Ubuntu development environment
How can i install Discourse forum on my win 10 dedicated server OVH
How to Install Discourse on LocalHost in Windows?
Restoring backup fails in Win10/Ubuntu development environment
Migrating to Discourse from another Forum software
How to Install Discourse on LocalHost in Windows?
Beginners Guide to Install Discourse for Development using Docker
Beginners Guide to Install Discourse on Ubuntu for Development
How to install on localhost
Help with setting up discourse An error occurred while installing xorcist (1.1.2), and Bundler cannot continue
WSL environment deadlocks
Problem with development on Windows with Docker and mounted volume
Please help, how do I install Discourse on macOS?
Beginners Guide to Install Discourse on Ubuntu for Development
Importing / migrating Phorum to Discourse
Discourse Development Contribution Guidelines
Importing / migrating PunBB to Discourse
Importing / migrating NodeBB (MongoDB) to Discourse
Importing / migrating NodeBB (Redis) to Discourse
Problem in development Installation
Importing / migrating MyBB to Discourse
Discourse eclipse in window
Beginners Guide to Install Discourse on Ubuntu for Development
How do I set up a local Discourse Development Environment?
Restoring backup fails in Win10/Ubuntu development environment
Topics which users cannot directly reply to, but can create a linked topic?
How to add a new language
How to Start Sidekiq When Using Puma
Discourse-webpack: A boilerplate for developing JS-heavy Discourse components
How can I directly edit Discourse database from a GUI?
Can't set up dev environment due to cppjieba_rb failing to install
Cloning and making our own Discourse community
How to Add Ngrok to Allowed Hosts
»vagrant up« hangs
Dev Category sidebar
Beginners Guide to Install Discourse on Ubuntu for Development
Discourse installation end to end on Windows Server 2016
Beginners Guide to Install Discourse on Ubuntu for Development
Beginners Guide to Install Discourse on Ubuntu for Development
No connection to db issue

As of June 30, 2020:
With the introduction of Windows 10 build 2004 and WSL 2 and many of you might run into some issues since Discourse now requires WSL 2 to actually run.
For starters: If you haven’t already, you would want to update your system to Windows 2004 (19041)
Note: Don’t install using Windows Update in the system settings as you might get errors mid-installation. Also make sure you are on Windows 1903 (18362) or 1909 (18363), you can search winver for that.

  • Go to: Download Windows 10
  • Click the Update Now button under Windows 10 May 2020 Update to download the update assistant and let it intall and finish
  • If you get any errors, then download the media creation tool, run it, and create a bootable flash drive (at least 8GB flash) and use it to install Windows.

When you are done with the Windows installation, you will need to manually install WSL 2
But first, we need to make sure that 2 features are enabled:

  • Virtual Machine Platform which can be enabled directly from your Windows by going to Programs and Features and then enabling Optional Features in Turn Windows features on or off
  • The other is Virtualization which can be only enabled from your BIOS. However this option can vary from one motherboard to the other. eg: on AMD it’s called SVM. So please look up your specific motherboard.

Now that you have both features enabled:

  • Install Ubuntu 18.04, and not 20.04 since some installations will fail on 20.04.
  • Go here and update Linux Kernel: Link in replies
  • Go to this link and follow the steps: Install Windows Subsystem for Linux (WSL) on Windows 10 | Microsoft Docs
  • Go to powershell (run as administrator) and run: wsl --set-version Ubuntu-18.04 2 or wsl --set-version Ubuntu 2, whichever distro shows up in wsl -l -v
  • Conversion takes time, a few minutes
  • Run wsl -l -v to make sure that Ubuntu is running on WSL 2

Now you can run Ubuntu-18.04 or Windows Terminal with Ubuntu and start installing the dependencies and tools

Note: If you are running into an error installing one of the gems during bundle install: Make sure you are on Ubuntu-18.04 and not 20.04

However, if you already have postgreSQL 12 and running on port 5432, you might run into some issues, since the dependencies install postgreSQL 10, which might increment the port to 5433.
To fix that:

  • Open your folder in a text editor (VS Code for example)
  • Go to config/database.yml
  • Under development and under adapter, add a new line and then add: port: 5433
  • Make sure you do the same for test and profile.

If the above doesn’t work, make sure to check if PostgreSQL is running and at which port via pg_isready. Then follow the same instructions above, setting the port equal to the one the database is running on.


FOR THE LINUX KERNEL: Updating the WSL 2 Linux kernel | Microsoft Docs


Tested it out, build 1903 upgrade worked following these steps, build 1909 awaiting installation to complete.

UPDATE: build 1909 upgrade to 2004 has failed (it took away my login screen so I couldn’t log in)

Awaiting future updates and bug fixes on Microsoft’s end to solve this issue.
In the meantime, I’m switching to solely Ubuntu.


Thanks so much! This was driving me insane


this fixed my issue, I can confirm it works! thank you so much ! :green_heart:


As of July 1, 2020:
A solution that does not require explicit port configuration in database.yml

Some errors during database creation and migration:

Invalid Redis connection to a specific port / connection refusal

$ bundle exec rake db:create
rake aborted!
Redis::CannotConnectError: Error connecting to Redis on localhost:6379 (Errno::ECONNREFUSED)

Caused by:
Errno::ECONNREFUSED: Connection refused - connect(2) for

Caused by:
IO::EINPROGRESSWaitWritable: Operation now in progress - connect(2) would block

Tasks: TOP => db:create => db:load_config => environment
(See full trace by running task with --trace)

From this error we can see that the port Redis uses is 6379, and we can fix this by starting the Redis server via that port.

By default, redis-server --daemonize yes should work, but if not, use:

$ redis-server --daemonize yes --port 6379

Check status of Redis instance:

$ redis-cli> ping

Invalid connection to psql port

$ bundle exec rake db:migrate
PG::ConnectionBad: could not connect to server: No such file or directory
       Is the server running locally and accepting
       connections on Unix domain socket "/var/run/postgresql/.s.PGSQL.5432"?

From this error we can see that PostgreSQL is having trouble connecting to port 5432. Usually starting the service should work

sudo service postgresql start

If this still doesn’t work and the error persists, try checking to see which port the service is listening from, and if necessary, change the port to the one you want in postgresql.conf:

$ pg_isready
/var/run/postgresql:5432 - no response
/var/run/postgresql:5432 - accepting connections

The Result

Once we have done the above or executed the start-discourse command, the two instances should run on their default/specified ports. To check their status via the default Windows cmd terminal, we can run:

netstat -anop tcp

which will show something like this:

Proto    Local Address        Foreign Address        State            PID
TCP              LISTENING        17768
TCP              LISTENING        17768

We have now confirmed that both our postgresql and redis-server instances are running.

We can also check the status of the instances on Ubuntu or WSL, with the following commands:

lsof -i
mailcatch  3244  rickyc0626  7u  IPv4   36127       0t0   TCP  localhost:1025 (LISTEN)
mailcatch  3244  rickyc0626  8u  IPv4   36128       0t0   TCP  *:socks (LISTEN)
redis-ser  3287  rickyc0626  6u  IPv6   29352       0t0   TCP  *:6379 (LISTEN)
redis-ser  3287  rickyc0626  7u  IPv6   29353       0t0   TCP  *:6379 (LISTEN)

sudo ss -plunt | grep postgres
tcp  LISTEN  0  128*  users:(("postgres",pid=3070,fd=7))

Ver Cluster Port Status Owner    Data directory              Log file
10  main    5432 online postgres /var/lib/postgresql/10/main /var/log/postgresql/postgresql-10-main.log

From here, these commands should work with no major issues, without needing to modify the database.yml file:

bundle exec rake db:create 
bundle exec rake db:migrate
RAILS_ENV=test bundle exec rake db:create db:migrate

Any further issues that show up can be addressed in the future.


I am able to run this with WSL2 and it’s whole lot faster than WSL1.

Question though: Anyone successfully expose the instance to local network? (to test out on mobile on the same WiFi). I am cracking my head to make it work, disabled firewall, listen to all interface but still no luck what could I had missed? My phone resolves “Err connection refuse” while trying to connect to my host PC’s ip at port 3000.

And this is for plugin development right? If I wanted to set things up for my new forum, what should the workflow be like? Can I migrate the backup from my local ubuntu to docker on Digital Ocean later on? What will be lost/kept?


Did you try by binding the rails server to all IP addresses ( Anyway in the desktop, you can force the application to mobile view by adding the query string ?mobile_view=1.

Yes, you can. It will copy everything from the database.


Yup, done that. I switched to Docker Dev and launch it with -p, still no luck. I have finally resort to using the mobile view in my browser.

I tested this out too, so far I think I got what I needed, i.e. categories, topics, etc.


1 Like

If anyone is trying to run this with arch linux and is getting a LoadError: cannot load such file -- irb on db:create, adding gem 'irb', require: false anywhere in the global scope of the Gemfile seems to fix it.

after some more fiddling, here’s what I had to do to get it running properly: (random package installations omitted)

add to .bashrc:

export PATH=$PATH:$HOME/.gem/ruby/2.7.0/bin # change version if needed
export PGDATA=$HOME/.pgdata
export DISCOURSE_DEV_HOSTS=arch # change to whatever you want, add the same name with the vm's ip (`ip addr` eth0 interface) to windows' hosts file
export SCREENDIR=$HOME/.screen

a helper script to set up environment after vm boot:

echo 'touching stuff'
sudo touch /var/run/utmp
mkdir ~/.screen && chmod 700 ~/.screen

echo 'preparing directories'
sudo mkdir /var/run/postgresql

echo 'fiddling with permissions'
sudo chmod 777 /var/run/postgresql

echo 'starting psql-server'
screen -mdS psql-server postgres -D $HOME/.pgdata/

echo 'starting redis'
redis-server --daemonize yes

echo 'forcing global bind on discourse'
nohup socat tcp-listen:3000,reuseaddr,fork,bind= tcp:localhost:3000 > /dev/null & # force discourse to listen globally # (wsl tries running a deprecated tool so it doesn't do this by default afaik)

creating a postgres db: initdb -D ~/.pgdata
running: screen -mdS discourse bundle exec rails server --binding=

1 Like

Hi, everybody. I’m a newbie. i encountered such a problem. After installing discourse, everything started up and opened up along the way http://localhost:3000/
Two weeks later, I open discourse and the site is unavailable.
i created a file using the nano start-discourse command following this guide, but discourse didn’t start. Tell me what could be the case?


One issue with creating a file to start Discourse is that you cannot easily see the Rails server log file.

I find it is best to troubleshoot core Discourse issues by starting Discourse as follows:

rails s

Then you can easily see all the verbose and very intricate details of what is going on with Rails and any errors.

Hope this helps.

1 Like

So I have followed this guide to set up a Discourse instance using WSL2 on Windows 10. And that is all working fine.

My next step was to set up VS Code with the Remote WSL and Ruby extensions, so I can edit and debug some files for a pluging I’m working on.
While the editing of the files works fine, I’m a bit stumped on how I should set up the debugger so it attaches to or launches the rails server so I can have breakpoints in my Ruby code that get hit.

My current launch.json file for VS Code looks like this:

  "version": "0.2.0",
  "configurations": [
      "name": "Rails server",
      "type": "Ruby",
      "request": "launch",
      "cwd": "${workspaceRoot}",
      "program": "${workspaceRoot}/bin/rails",
      "args": [ "server" ],
      "showDebuggerOutput": true,
      "useBundler": true

When trying to run this debug configuration, I can see the first line of the console text, but then the debugger just stops again:

Fast Debugger (ruby-debug-ide 0.7.2, debase, file filtering is supported) listens on

I, [2021-01-14T17:33:27.277069 #8916]  INFO -- : Refreshing Gem list

(I installed ruby-debug-ide and debase in my WSL Ubuntu instance, and included those in the Gemfile that the Discourse install uses)

Does anyone use a similar setup and knows what I might be doing wrong here?


Looks like I managed to get it to work by adding this to the config:

"pathToRDebugIDE": "${workspaceRoot}/bin/rdebug-ide"

And in my WSL instance I had to run bundler install --binstubs as well.

Not sure if this is the right/preferred way of doing this, but at least it works for me now :slight_smile:


Hello, while trying to import using dev environment, I am getting the following error:

/home/wm/.rbenv/versions/2.7.1/lib/ruby/gems/2.7.0/gems/bootsnap-1.5.1/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:77:in 'load': No such file to load -- lib/discourse.rb (LoadError)

Previously I followed this guide: Beginners Guide to Install Discourse on Windows 10 for Development without major issues.

Thanks in advance!


Can i launch in production mode?
I want to try out how things look in production mode (i know they will be identical but still)?

1 Like

Also, i am getting the following error.
Initially the setup worked fine for me, but after logout getting the following error -


1 Like

I would rather ask this earlier rather than later. Does the guide also apply to Windows 11? Has anything changed?

1 Like

Got errors spamming when running

bundle exec rails server --binding=
WARNING: Using `bundle exec` to start the server is unnecessary, and will make startup slower. Use `bin/rails s` or `bin/unicorn`.
I, [2021-08-15T23:07:59.825677 #826]  INFO -- : Refreshing Gem list
Starting CSS change watcher
E, [2021-08-15T23:08:07.929593 #826] ERROR -- : {:tcp_defer_accept=>1, :accept_filter=>"httpready", :backlog=>1024, :tcp_nopush=>nil, :tcp_nodelay=>true}: Protocol not available - setsockopt(2) (Errno::ENOPROTOOPT)
E, [2021-08-15T23:08:07.930318 #826] ERROR -- : /home/cx-unix/.rvm/gems/ruby-2.6.2/gems/unicorn-6.0.0/lib/unicorn/socket_helper.rb:74:in `setsockopt'
E, [2021-08-15T23:08:07.930538 #826] ERROR -- : /home/cx-unix/.rvm/gems/ruby-2.6.2/gems/unicorn-6.0.0/lib/unicorn/socket_helper.rb:74:in `set_tcp_sockopt'
E, [2021-08-15T23:08:07.930821 #826] ERROR -- : /home/cx-unix/.rvm/gems/ruby-2.6.2/gems/unicorn-6.0.0/lib/unicorn/socket_helper.rb:94:in `set_server_sockopt'
E, [2021-08-15T23:08:07.931046 #826] ERROR -- : /home/cx-unix/.rvm/gems/ruby-2.6.2/gems/unicorn-6.0.0/lib/unicorn/socket_helper.rb:149:in `bind_listen'
E, [2021-08-15T23:08:07.931302 #826] ERROR -- : /home/cx-unix/.rvm/gems/ruby-2.6.2/gems/unicorn-6.0.0/lib/unicorn/http_server.rb:242:in `listen'
E, [2021-08-15T23:08:07.931447 #826] ERROR -- : /home/cx-unix/.rvm/gems/ruby-2.6.2/gems/unicorn-6.0.0/lib/unicorn/http_server.rb:882:in `block in bind_new_listeners!'
E, [2021-08-15T23:08:07.931548 #826] ERROR -- : /home/cx-unix/.rvm/gems/ruby-2.6.2/gems/unicorn-6.0.0/lib/unicorn/http_server.rb:882:in `each'
E, [2021-08-15T23:08:07.931648 #826] ERROR -- : /home/cx-unix/.rvm/gems/ruby-2.6.2/gems/unicorn-6.0.0/lib/unicorn/http_server.rb:882:in `bind_new_listeners!'
E, [2021-08-15T23:08:07.931761 #826] ERROR -- : /home/cx-unix/.rvm/gems/ruby-2.6.2/gems/unicorn-6.0.0/lib/unicorn/http_server.rb:141:in `start'
E, [2021-08-15T23:08:07.931817 #826] ERROR -- : /home/cx-unix/.rvm/gems/ruby-2.6.2/gems/unicorn-6.0.0/bin/unicorn:128:in `<top (required)>'

Using windows 10 with WSL 2, Ubuntu 18.04

Any idea? Thanks!