If you're using Docker or a local development environment, you will be starting off with minimal development data. Here are some tips for creating data on your development environment.

All the instructions on this page assume that you already have a running local application, e.g. a Docker setup.

By default, the following users exist in your development environment:

Note that accounts with the "Archivist" role can't leave kudos.

The following admins exist as well.

Note: The "Log In" option at the top of every page will not allow you to log in to an admin account. Instead, go to the admin login path and use the form there: /admin/login.

To create and activate a user account, first launch the Rails console:

bundle exec rails c

If you are using Docker try

docker compose run --rm web rails c

Then you can create and activate a user account by entering the following, replacing the values as desired:

User.new(login: "desired_username", email: "[email protected]", password: "desired_password", password_confirmation: "desired_password", age_over_13: "1", terms_of_service: "1").activate

If you'd like to make it possible to create user accounts through your local archive website, enter the following commands:

setting = AdminSetting.first
setting.account_creation_enabled = true
setting.last_updated_by = 1
setting.save

A "Create an Account!" link should now appear on your local site's homepage, or you can visit the new user path directly: /signup.

Creating and logging into an admin account will allow you to perform tasks such as managing user permissions (e.g. make a user a tag wrangler) and modifying your archive's settings through the admin interface.

To create an admin account, run the following script from your command line (not the Rails console) and enter information as prompted:

bundle exec rails runner script/create_admin.rb

If you are using Docker you can try

docker compose run --rm web rails runner script/create_admin.rb

The script triggers an email with a temporary password. If you can access the email in your development logs, you can follow the instructions there. If not, you'll need to set a password from the Rails console:

bundle exec rails c
admin = Admin.find_by(login: "admin-name")
admin.update(password: "desired_password")
admin.roles = ["superadmin"]
admin.save

Note: the "Log In" option at the top of every page will not allow you to log in to an admin account. Instead, go to the admin login path and use the form there: /admin/login.

An admin account with the "superadmin" role has access to all admin functions.

Some miscellaneous features of the archive may not work as expected in local dev because some rake tasks weren't run or aren't scheduled.

If you use Docker, prefix the listed commands with docker compose run --rm web to run them in the container, for example docker compose run --rm web bundle exec rails autocomplete:load_data. Alternatively, get a shell inside the container with docker compose exec web bash and execute the listed command there.

If the autocomplete fields are not showing results for any existing tags, you can run:

bundle exec rails autocomplete:load_data

To cache the default skin and any skin featured in the skin chooser in the footer, you can run:

bundle exec rails skins:cache_chooser_skins

This can be useful to remove most of the skin related queries from the debug logs.

Pages likes work indexes for users and tags are powered by Elasticsearch. If the Elasticsearch indexes are empty, these pages will also be empty. The Elasticsearch indexes are filled by delayed jobs that are queued and then executed by a Resque worker.

To fill the Elasticsearch indexes and run various other background jobs, you need to start the Resque worker. This is a blocking command that needs to keep running, so use a second shell window to run the command:

RAILS_ENV=development QUEUE=* bundle exec rake environment resque:work

If you are using Docker or Ona (formerly Gitpod), the workers should already be running in a separate resque container and should have filled the Elasticsearch indexes when you ran the init script.

If the indexes are empty, you can create and fill them with the tasks from search.rake:

bundle exec rake search:index_tags
bundle exec rake search:index_works
bundle exec rake search:index_pseuds
bundle exec rake search:index_bookmarks 
bundle exec rake search:index_admin_users
bundle exec rake search:index_collections

The Resque workers will run the queued index updates and also other delayed jobs like mails queued with deliver_later or challenge matching.

To make sure your Elasticsearch indexes get updated (e.g. when you create a new work), you need to start the Resque Scheduler in addition to the worker. It queues jobs for the worker, such as updating the reading history and regular indexing of new works, bookmarks and so on, refer to resque_schedule.yml. Starting the Resque Scheduler is a blocking command that needs to keep running, so use a second shell window to run the command:

bundle exec rake resque:scheduler

If you are using Docker or Ona (formerly Gitpod), then the scheduler should already be running in the resque container.

If you are using Docker or Ona (formerly Gitpod), and modifying code that is run by the workers (e.g. elasticsearch indexing), you'll need to restart the resque container with `docker compose restart resque` to update the workers with the newest code.

If you want to customize the values in config.yml for your local installation, do not edit this file. Instead, create or modify the local.yml file in the same folder, it will override anything in config.yml. As an example, to change the name of your local archive, add this to the local.yml file and restart the application:

  APP_NAME: 'Very Custom Archive'

The Archive of Our Own FAQs may be helpful when creating other types of data through your dev environment's interface.