From 3196918f4de2b39ae9cb28cc0ca5f567adb565b9 Mon Sep 17 00:00:00 2001 From: David Taylor Date: Tue, 28 Jan 2025 23:25:25 +0000 Subject: [PATCH] DEV: Update 'development' section of readme, and drop outdated docs (#31044) These docs have not been updated for many years. Up-to-date content can be found at https://meta.discourse.org/c/documentation/developer-guides/56 --- README.md | 14 +- docs/DEVELOPER-ADVANCED.md | 93 ----------- docs/DEVELOPMENT-OSX-NATIVE.md | 275 --------------------------------- docs/TROUBLESHOOTING.md | 70 --------- 4 files changed, 7 insertions(+), 445 deletions(-) delete mode 100644 docs/DEVELOPER-ADVANCED.md delete mode 100644 docs/DEVELOPMENT-OSX-NATIVE.md delete mode 100644 docs/TROUBLESHOOTING.md diff --git a/README.md b/README.md index f62e29c60c6..4379c122d57 100644 --- a/README.md +++ b/README.md @@ -22,16 +22,16 @@ Browse [lots more notable Discourse instances](https://www.discourse.org/custome ## Development -To get your environment set up, follow the community setup guide for your operating system. +To get your environment set up, follow one of the setup guides: -1. If you're on macOS, try the [macOS development guide](https://meta.discourse.org/t/beginners-guide-to-install-discourse-on-macos-for-development/15772). -1. If you're on Ubuntu, try the [Ubuntu development guide](https://meta.discourse.org/t/beginners-guide-to-install-discourse-on-ubuntu-for-development/14727). -1. If you're on Windows, try the [Windows 10 development guide](https://meta.discourse.org/t/beginners-guide-to-install-discourse-on-windows-10-for-development/75149). -1. If you're looking to use a simpler Docker-based install, try the [Docker development guide](https://meta.discourse.org/t/install-discourse-for-development-using-docker/102009). +- [Docker / Dev Container](https://meta.discourse.org/t/336366) +- [macOS](https://meta.discourse.org/t/15772) +- [Ubuntu/Debian](https://meta.discourse.org/t/14727) +- [Windows](https://meta.discourse.org/t/75149) -If you're familiar with how Rails works and are comfortable setting up your own environment, you can also try out the [**Discourse Advanced Developer Guide**](docs/DEVELOPER-ADVANCED.md), which is aimed primarily at Ubuntu and macOS environments. +Before you get started, ensure you have the following minimum versions: [Ruby 3.2+](https://www.ruby-lang.org/en/downloads/), [PostgreSQL 13](https://www.postgresql.org/download/), [Redis 7](https://redis.io/download). -Before you get started, ensure you have the following minimum versions: [Ruby 3.2+](https://www.ruby-lang.org/en/downloads/), [PostgreSQL 13](https://www.postgresql.org/download/), [Redis 7](https://redis.io/download). If you're having trouble, please see our [**TROUBLESHOOTING GUIDE**](docs/TROUBLESHOOTING.md) first! +For more information, check out [the Developer Documentation](https://meta.discourse.org/c/documentation/developer-guides/56). ## Setting up Discourse diff --git a/docs/DEVELOPER-ADVANCED.md b/docs/DEVELOPER-ADVANCED.md deleted file mode 100644 index db713d2a0a9..00000000000 --- a/docs/DEVELOPER-ADVANCED.md +++ /dev/null @@ -1,93 +0,0 @@ -# Discourse Advanced Developer Install Guide - -This guide is aimed at advanced Rails developers who have installed their own Rails apps before. - -Note: If you are developing on a Mac, you will probably want to look at [these instructions](DEVELOPMENT-OSX-NATIVE.md) as well. - -# Preparing a fresh Ubuntu install - -To get your Ubuntu 16.04 or 18.04 LTS install up and running to develop Discourse and Discourse plugins follow the commands below. We assume an English install of Ubuntu. - - # Basics - whoami > /tmp/username - sudo add-apt-repository ppa:chris-lea/redis-server - sudo apt-get -yqq update - sudo apt-get -yqq install software-properties-common vim curl expect debconf-utils git-core build-essential zlib1g-dev libssl-dev openssl libcurl4-openssl-dev libreadline6-dev libpcre3 libpcre3-dev imagemagick redis-server advancecomp jhead jpegoptim libjpeg-turbo-progs optipng pngcrush pngquant gnupg2 - - # oxipng - mkdir /tmp/oxipng-install && cd /tmp/oxipng-install - wget https://github.com/shssoichiro/oxipng/releases/download/v5.0.1/oxipng-5.0.1-x86_64-unknown-linux-musl.tar.gz - tar -xzf oxipng-5.0.1-x86_64-unknown-linux-musl.tar.gz && cd oxipng-5.0.1-x86_64-unknown-linux-musl - cp oxipng /usr/local/bin - - # Ruby - curl -sSL https://rvm.io/mpapis.asc | gpg2 --import - - curl -sSL https://rvm.io/pkuczynski.asc | gpg2 --import - - curl -sSL https://get.rvm.io | bash -s stable - echo 'gem: --no-document' >> ~/.gemrc - - # exit the terminal and open it again to activate RVM - - rvm install 2.7.2 - rvm --default use 2.7.2 # If this error out check https://rvm.io/integration/gnome-terminal - gem install bundler rake - - # Download and install postgresql-10 from https://wiki.postgresql.org/wiki/Apt - - # Postgresql - sudo -u postgres -i - createuser --superuser -Upostgres $(cat /tmp/username) - psql -c "ALTER USER $(cat /tmp/username) WITH PASSWORD 'password';" - exit - - # Node - curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.2/install.sh | bash - - # exit the terminal and open it again to activate NVM - - nvm install node - nvm alias default node - npm install -g svgo - - -If everything goes alright, let's clone Discourse and start hacking: - - git clone https://github.com/discourse/discourse.git ~/discourse - cd ~/discourse - bundle install - - # run this if there was a pre-existing database - bundle exec rake db:drop - RAILS_ENV=test bundle exec rake db:drop - - # time to create the database and run migrations - bundle exec rake db:create - bundle exec rake db:migrate - RAILS_ENV=test bundle exec rake db:create db:migrate - - # run the specs (optional) - bundle exec rake autospec # CTRL + C to stop - - # launch discourse - bundle exec rails s -b 0.0.0.0 # open browser on http://localhost:3000 and you should see Discourse - -Create an admin account with: - - bundle exec rake admin:create - -If you ever need to recreate your database: - - bundle exec rake db:drop db:create db:migrate - bundle exec rake admin:create - RAILS_ENV=test bundle exec rake db:drop db:create db:migrate - -Configure emails via MailHog (https://github.com/mailhog/MailHog): - - docker run -p 8025:8025 -p 1025:1025 mailhog/mailhog # open http://localhost:8025 to see the emails - -Discourse does a lot of stuff async, so it's better to run sidekiq even on development mode: - - bundle exec sidekiq # open http://localhost:3000/sidekiq to see queues - bundle exec rails server - -And happy hacking! diff --git a/docs/DEVELOPMENT-OSX-NATIVE.md b/docs/DEVELOPMENT-OSX-NATIVE.md deleted file mode 100644 index 2ef9f10695e..00000000000 --- a/docs/DEVELOPMENT-OSX-NATIVE.md +++ /dev/null @@ -1,275 +0,0 @@ -# Developing under OS X - -These instructions assume you have read and understood the **[Discourse Advanced Developer Install Guide](DEVELOPER-ADVANCED.md)**. - -OS X has become a popular platform for developing Ruby on Rails applications; as such, if you run OS X, you might find it more congenial to work on **[Discourse](https://www.discourse.org)** in your native environment. These instructions should get you there. - -Obviously, if you **already** develop Ruby on OS X, a lot of this will be redundant, because you'll have already done it, or something like it. If that's the case, you may well be able to just install Ruby 2.6+ using RVM and get started! Discourse has enough dependencies, however (note: not a criticism!) that there's a good chance you'll find **something** else in this document that's useful for getting your Discourse development started! - -## UTF-8 - -OS X 10.8 uses UTF-8 by default. You can, of course, double-check this by examining LANG, which appears to be the only relevant environment variable. - -You should see this: - -```sh -$ echo $LANG -en_US.UTF-8 -``` - -## OS X Development Tools - -As the [RVM website](https://rvm.io) makes clear, there are some serious issues between MRI Ruby and the modern Xcode command line tools, which are based on CLANG and LLVM, rather than classic GCC. - -This means that you need to do a little bit of groundwork if you do not already have an environment that you know for certain yields working rubies and gems. - -You will want to install Xcode Command Line Tools. If you already have Xcode installed, you can do this from within Xcode's preferences. You can also install just the command line tools, without the rest of Xcode, at [Apple's developer site](https://developer.apple.com/downloads/index.action). You will need these more for some of the headers they include than the compilers themselves. - -You will then need the old GCC-4.2 compilers, which leads us to... - -## Homebrew - -**[Homebrew](https://brew.sh)** is a package manager for ports of various Open Source packages that Apple doesn't already include (or newer versions of the ones they do), and competes in that space with MacPorts and a few others. Brew is very different from Apt, in that it often installs from source, and almost always installs development files as well as binaries, especially for libraries, so there are no special "-dev" packages. - -RVM (below) can automatically install homebrew for you with the autolibs setting, but doesn't install the GCC-4.2 compiler package when it does so, possibly because that package is not part of the mainstream homebrew repository. - -So, you will need to install Homebrew separately, based on the instructions at the website above, and then run the following from the command line: - - brew tap homebrew/dupes # roughly the same to adding a repo to apt/sources.list - brew install apple-gcc42 - gcc-4.2 -v # Test that it's installed and available - -(You may note the Homebrew installation script requires ruby. This is not a chicken-and-egg problem; OS X 10.8 comes with ruby 1.8.7) - -## RVM and Ruby - -While some people dislike magic, I recommend letting RVM do most of the dirty work for you. - -### RVM from scratch - -If you don't have RVM installed, the "official" install command line on rvm.io will take care of just about everything you need, including installing Homebrew if you don't already have it installed. If you do, it will bring things up to date and use it to install the packages it needs. - - curl -L https://get.rvm.io | bash -s stable --rails --autolibs=enabled - -### Updating RVM - -If you do already have RVM installed, this should make sure everything is up to date for what you'll need. - - rvm get stable - - # Tell RVM to install anything its missing. Use '4' if homebrew isn't installed either. - rvm autolibs 3 - - # This will install baseline requirements that might be missing, including homebrew. - # If autolibs is set to 0-2, it will give an error for things that are missing, instead. - rvm requirements - -Either way, you'll now want to install Ruby 2.6+ (we recommend 2.6.2 or higher). - - # Now, install Ruby - rvm install 2.6.2 - rvm use 2.6.2 --default # Careful with this if you're already developing Ruby - -## Git - -### Command line - -OS X comes with Git (which is why the LibXML2 dance above will work before this step!), but I recommend you update to Homebrew's version: - - brew install git - -You should now be able to check out a clone of Discourse. - -### SourceTree - -Atlassian has a free Git client for OS X called [SourceTree](https://www.sourcetreeapp.com/download/) which can be extremely useful for keeping visual track of what's going on in Git-land. While it's arguably not a full substitute for command-line git (especially if you know the command line well), it's extremely powerful for a GUI version-control client. - -## Postgres 10 - -OS X might ship with Postgres 9.x, but you're better off going with 10 and above from Homebrew or [Postgres.app](https://postgresapp.com). - -### Using Postgres.app - -After installing [Postgres.app](https://postgresapp.com/), there are some additional setup steps that are necessary for discourse to create a database on your machine. - -Open this file: -``` -~/Library/Application Support/Postgres/var-9.3/postgresql.conf -``` -And change these two lines so that postgres will create a socket in the folder discourse expects it to: -``` -unix_socket_directories = '/var/pgsql_socket' # comma-separated list of directories -#and -unix_socket_permissions = 0777 # begin with 0 to use octal notation -``` -Then create the '/var/pgsql_socket/' folder and set up the appropriate permission in your bash (this requires admin access) -``` -sudo mkdir /var/pgsql_socket -sudo chmod 770 /var/pgsql_socket -sudo chown root:staff /var/pgsql_socket -``` -Now you can restart Postgres.app and it will use this socket. Make sure you not only restart the app but kill any processes that may be left behind. You can view these processes with this bash command: -``` -netstat -ln | grep PGSQL -``` -And you should be good to go! - -#### Troubleshooting - -If you get this error when starting `psql` from the command line: - - psql: could not connect to server: No such file or directory - Is the server running locally and accepting - connections on Unix domain socket "/tmp/.s.PGSQL.5432"? - -it is because it is still looking in the `/tmp` directory and not in `/var/pgsql_socket`. - -If running `psql -h /var/pgsql_socket` works then you need to configure the host in your `.bash_profile`: - -``` -export PGHOST="/var/pgsql_socket" -```` - -Then make sure to reload your config with: `source ~/.bash_profile`. Now `psql` should work. - - -### Using Homebrew: - -Whereas Ubuntu installs postgres with 'postgres' as the default superuser, Homebrew installs it with the user who installed it... but with 'postgres' as the default database. Go figure. - -However, the seed data currently has some dependencies on their being a 'postgres' user, so we create one below. - -In theory, you're not setting up with vagrant, either, and shouldn't need a vagrant user; however, again, all the seed data assumes 'vagrant'. To avoid headaches, it's probably best to go with this flow, so again, we create a 'vagrant' user. - - brew install postgresql - ln -sfv /usr/local/opt/postgresql/*.plist ~/Library/LaunchAgents - - export PATH=/usr/local/opt/postgresql/bin:$PATH # You may want to put this in your default path! - initdb /usr/local/var/postgres -E utf8 - launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist - launchctl load ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist - -### Seed data relies on both 'postgres' and 'vagrant' - - createuser --createdb --superuser postgres - createuser --createdb --superuser vagrant - - psql -d postgres -c "ALTER USER vagrant WITH PASSWORD 'password';" - psql -d postgres -c "create database discourse_development owner vagrant encoding 'UTF8' TEMPLATE template0;" - psql -d postgres -c "create database discourse_test owner vagrant encoding 'UTF8' TEMPLATE template0;" - psql -d discourse_development -c "CREATE EXTENSION hstore;" - psql -d discourse_development -c "CREATE EXTENSION pg_trgm;" - -You should not need to alter `/usr/local/var/postgres/pg_hba.conf` - -## Redis - - brew install redis - ln -sfv /usr/local/opt/redis/*.plist ~/Library/LaunchAgents - launchctl load ~/Library/LaunchAgents/homebrew.mxcl.redis.plist - -That's about it. - -## Google Chrome 59+ - -Chrome is used for running QUnit tests in headless mode. - -Download from https://www.google.com/chrome/index.html - -## ImageMagick - -ImageMagick is used for generating avatars (including for test fixtures). - - brew install imagemagick - -ImageMagick is going to want to use the Helvetica font to generate the -letter-avatars. To make it available we need to extract it from the system -fonts: - -```sh -brew install fontforge -cd ~/Library/Fonts -export HELVETICA_FONT=/System/Library/Fonts/Helvetica.ttc # The extension might be dfont instead -fontforge -c "[open(u'%s(%s)' % ('$HELVETICA_FONT', font)).generate('%s.ttf' % font) for font in fontsInFile('$HELVETICA_FONT')]" -mkdir ~/.magick -cd ~/.magick -curl https://legacy.imagemagick.org/Usage/scripts/imagick_type_gen > type_gen -find /System/Library/Fonts /Library/Fonts ~/Library/Fonts -name "*.[to]tf" | perl type_gen -f - > type.xml -cd /usr/local/Cellar/imagemagick//etc/ImageMagick-6 -``` - -Edit system config file called "type.xml" and add line near end to tell IM to -look at local file we made in earlier step - -``` - - - ### THIS LINE ADDED - -``` - -## Sending email (SMTP) - -By default, development.rb will attempt to connect locally to send email. - -```rb -config.action_mailer.smtp_settings = { address: "localhost", port: 1025 } -``` - -Set up [MailHog](https://github.com/mailhog/MailHog) so the app can intercept -outbound email and you can verify what is being sent. - -## Additional Image Tooling - -In addition to ImageMagick we also need to install some other image related -software: - -```sh -brew install jpegoptim optipng oxipng jhead -npm install -g svgo -``` - -## Setting up your Discourse - -### Check out the repository -```sh -git clone git@github.com:discourse/discourse.git -cd discourse # Navigate into the repository, and stay there for the rest of this how-to -``` -### What about the config files? - -If you've stuck to all the defaults above, the default `discourse.conf` and `redis.conf` should work out of the box. - -### Install the needed gems -```sh -bundle install -``` - -### Prepare your database -```sh -# run this if there was a pre-existing database -bundle exec rake db:drop -RAILS_ENV=test bundle exec rake db:drop - -# time to create the database and run migrations -bundle exec rake db:create -bundle exec rake db:migrate -RAILS_ENV=test bundle exec rake db:create db:migrate -``` - -## Now, test it out! -```sh -bundle exec rspec -``` -All specs should pass - -### Deal with any problems which arise. - -Reset the environment as a possible solution to failed rspec tests. -These commands assume an empty Discourse database, and an otherwise empty redis environment. CAREFUL HERE - - RAILS_ENV=test rake db:drop db:create db:migrate - redis-cli flushall - bundle exec rspec # re-running to see if tests pass - -Search https://meta.discourse.org for solutions to other problems. diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md deleted file mode 100644 index b58603cc573..00000000000 --- a/docs/TROUBLESHOOTING.md +++ /dev/null @@ -1,70 +0,0 @@ -## Troubleshooting issues with Discourse environments - -Are you having trouble setting up Discourse? Here are some basic things to check before -reaching out to the community for help: - - -1. Are you running Ruby 2.5 or later? - - Discourse is designed for Ruby 2.5 or later. We recommend 2.5.2 or later. You can check your version by typing - `ruby -v` and checking the response. - - -2. Are you on Postgres 10 or later with HSTORE enabled? - - You can check your postgres version by typing `psql --version`. To see if hstore is - installed, open a session to postgres and type `\dx` and see if hstore is listed. - - -3. Have you run `bundle install`? - - We frequently update our dependencies to newer versions. It is a good idea to run - `bundle install` every time you check out Discourse, especially if it's been a while. - -4. Did you run `bundle update`? - - Don't. Running `bundle update` will download gem versions that we haven't tested with. - The Gemfile.lock has the gem versions that Discourse currently uses, so `bundle install` - will work. If you ran update, then you should uninstall the gems, run - `git checkout -- Gemfile.lock` and then run `bundle install`. - -5. Have you migrated your database? - - Our schema changes fairly frequently. After checking out the source code, you should - run `bundle exec rake db:migrate && RAILS_ENV=test bundle exec rake db:migrate` - -7. Do the tests pass? - - If you are having other problems, it's useful to know if the test suite passes. You - can run it by first using `RAILS_ENV=test bundle exec rake db:drop db:create db:migrate` and then `bundle exec rspec`. If you - experience any failures, that's a bad sign! Our master branch should *always* pass - every test. - -8. Have you updated host_names in your database.yml? - - If links in emails have localhost in them, then you are still using the default host_names - value in database.yml. Update it to use your site's host name(s). - -9. Are you having problems bundling: - -``` text -ArgumentError: invalid byte sequence in US-ASCII -An error occurred while installing active_model_serializers (0.7.0), and Bundler cannot continue. -Make sure that `gem install active_model_serializers -v '0.7.0'` succeeds before bundling. -``` - - Try this in console: - -``` text -$ export LANG="en_US.UTF-8" -$ export LC_ALL="en_US.UTF-8" -``` - - And/or this in top of `Gemfile`: - -``` text -if RUBY_VERSION =~ /1.9/ -Encoding.default_external = Encoding::UTF_8 -Encoding.default_internal = Encoding::UTF_8 -end -```