Skip to content

Developing with GitHub Codespaces

As an alternative to the VIP Local Development Environment, WordPress application code can be developed within a GitHub Codespaces environment. WPVIP provides configuration (config) files that create Codespaces environments based on WPVIP’s infrastructure. The config files can be further customized for the Codespaces environment to have nearly identical settings as an individual application.

GitHub CodeSpaces is a cloud-based development environment that enables developers to write, test, and debug code directly in the cloud. Refer to GitHub’s documentation to learn how to use Codepaces for testing and development.

Limitations

Though the GitHub Codespaces integration is designed to be as identical to a VIP Platform environment as possible, some features differ slightly or are not available. When developing features for an application that rely on these services, it is strongly recommended to stage changes and perform tests on a non-production VIP Platform environment.

  • Page cache is not available.
  • The VIP File System is not available. However, for images that are uploaded to a Codespaces environment, a built-in Photon service will perform dynamic image transformations that are nearly identical to the behavior on a VIP Platform environment.
  • Cron control is not available. Scheduled cron events can be executed by an OS-based crontab system (disabled by default). Cron events are executed on a 15-minute interval by a wp cron event run --due-now command. Edit the Cron section of devcontainer.json to enable the built-in Cron system, or to adjust the interval value.
  • Databases in the codespace environment are MariaDB; VIP Platform environment databases are MySQL 8.

Access

The .devcontainer/devcontainer.json config file for creating a Codespaces environment based on VIP’s infrastructure can be retrieved from the vip-go-skeleton repository. GitHub repositories for WordPress applications created after 1 February 2024 will already include .devcontainer/devcontainer.json by default.

Prerequisites

If .devcontainer/devcontainer.json does not yet exist within a WordPress application’s GitHub repository, it can be added.

  1. Create a new branch—or use an existing branch—in the application’s repository.
  2. Create a .devcontainer directory in the repository root on the remote branch.
  3. Add a copy of devcontainer.json to the .devcontainer directory.

Create a new codespace

Codespaces environments are created per branch. For a branch that already has .devcontainer/devcontainer.json added to it:

  1. Navigate to the GitHub interface for the branch’s repository.
  2. Select the branch from the dropdown menu labeled “Switch branches/tags“.
  3. Select the button labeled “<> Code“.
  4. In the displayed options, select the tab labeled “Codespaces“.
  5. Select the button labeled “Create codespace on codespace-example“.

In a new browser tab, a displayed output log will report progress on the creation of the new codespace. The creation process will take several minutes. The length of time required for creation can be reduced by configuring a prebuild for codespaces.

When creation of the codespace is complete, the content in the browser tab will refresh and display a Visual Studio Code (VS Code) interface.

Example screenshot of a fully built VIP Codespaces development environment.

Log in to WordPress

In the browser tab’s VS Code interface for a codespace that is in a running state:

  1. Select the tab labeled “Ports” located in the bottom half of the screen.
  2. In the row for “Application (80)”, select the value in the column labeled “Local Address“. Three icons will be displayed at the right of the local address value.
  3. Load the front end of the codespace environment in a new browser tab by either:
    • Selecting the globe icon labeled “Open in Browser“.
    • Or right-clicking on the local address value and selecting “Open in Browser” from the flyout menu.
  4. Access the WordPress login portal by appending /wp-admin to the local address value in the browser’s address bar (e.g., https://$CODESPACE_NAME-80.preview.app.github.dev/wp-admin).
  5. Log in with the default user credentials, or user credentials that exist in a database that was imported to the codespace environment.

Default login credentials

Users can log in to the created codespace environment with default WordPress user account credentials.

Default username: vipgo
Default password: password

The default user account has an Administrator role on a WordPress single site and a Super Admin role on a WordPress multisite.

Log in to phpMyAdmin

Login credentials for phpMyAdmin are displayed in the terminal of the VS Code interface in the browser tab. These credentials will display each time a new codespace or VS Code terminal is created.

By default, the username for phpMyAdmin is vipgo. A unique password for phpMyAdmin is generated for each codespace. If a password value fails to display, it can be retrieved by running this command in the VS Code terminal:

cat /etc/conf.d/phpmyadmin-password; echo

In the browser tab’s VS Code interface:

  1. Select the tab labeled “Ports” located on the bottom half of the screen.
  2. In the row for “phpMyAdmin (81)”, select the value in the column labeled “Local Address“. Three icons will be displayed at the right of the local address value.
  3. Load phpMyAdmin for the codespace environment in a new browser tab by either:
    • Selecting the globe icon labeled “Open in Browser“.
    • Or right-clicking on the local address value and selecting “Open in Browser” from the flyout menu.
  4. In the prompt of the new browser tab, log in with the credentials that are displayed in the terminal panel of the VS Code interface.

Caution

Never modify the Visibility setting of the phpMyAdmin Port (Port 81). Setting the port’s visibility to anything other than Private will cause phpMyAdmin—and any imported data—to be vulnerable to attacks. The assigned login credentials for the port are not a sufficient security measure to prevent attacks.

Access logs

Log error files can be accessed in the terminal of the VS Code interface.

Access the logs with Linux prompts such as less, cat, tail or grep depending on a user’s needs. This example command demonstrates how to access the NGINX access logs of a running codespace environment with less:

less /var/log/nginx/access.log

To review log output in real time, include the -f (“follow”) parameter with the tail command. This example command demonstrates how to access and stream the NGINX/PHP error logs of a running codespace environment with tail -f:

tail -f /var/log/nginx/error.log
  • NGINX access log: /var/log/nginx/access.log
  • NGINX/PHP error log: /var/log/nginx/error.log

Visual Studio Code extensions for log access

The Automattic-authored VS Code Log Watcher extension and the VS Code Log File Highlighter extension are installed and enabled by default in the GitHub Codespaces environment. The Log Watcher extension simplifies the steps needed to access log files and output them in real time.

Access a log file :

  1. Open the Command Palette prompt (⇧⌘P).
  2. Type in the Watch nginx command.
  3. Select either the NGINX access.log or error.log value. (e.g. Watch nginx access.log).
  4. Confirm the selection by pressing Enter or Return.

Contents of the requested log will be displayed in real time in the tab labeled “Output“.

Option to automatically show changes

By default, when a watched file is updated, Log Watcher will shift focus to that file in the “Output” tab. This behavior can be disabled by:

  1. Selecting the VS Code option labeled “Manage“, represented by a gear wheel icon at the bottom left.
  2. Select “Settings” from the flyout menu.
  3. Select the tab labeled “User”.
  4. Either select “Log Watcher” from the list of extensions, or type “Log Watcher” in the search field to access settings options.
  5. Disable the option to “Automatically Show Changes”.

Import a SQL database file

Only SQL database files that were exported from a WordPress install can be imported to a running codespace environment. For environments that are hosted on the VIP Platform, SQL database backup files can be downloaded from the application’s VIP Dashboard.

The SQL database file for import must be located on a user’s local machine.

  1. Drag the file and drop the SQL file into the “Explorer” section of the VS Code interface in the browser tab. 
  2. If the SQL file is archived, run a command in the VS Code interface terminal to expand it. For example, a file archived with gzip can be expanded by running the command: gunzip example-file.gz
  3. In the VS Code tab labeled “Terminal“, import the file with WP-CLI command: wp db import <file>. For example, to import a file named example-file.sql, the command would be formatted as: wp db import example-file.sql
  4. Retrieve the codespace environment’s Local Address value:
    • Select the tab labeled “Ports“.
    • In the row for “Application (80)”, select the value in the column labeled “Forwarded Address“. Three icons will be displayed at the right of the local address value.
    • To copy the Local Address value, select the clipboard icon labeled “Copy Local Address“.
  5. In the tab labeled “Terminal“, use WP-CLI to run a search and replace and update the imported site address values in the database with the Local Address value of the codespace environment. For example, if the imported SQL file was exported from a site with the site address value example.com, and the codespace Local Address value is example-80.preview.app.github.dev, the WP-CLI command will be formatted as:
wp search-replace example.com example-80.preview.app.github.dev --all-tables --report-changed-only
  1. Flush the object cache with the WP-CLI command wp cache flush.
  2. Delete the SQL file from the VS Code “Explorer” window by right-clicking on the file name and selecting “Delete Permanently” from the flyout menu.

Access WordPress Core files and VIP MU plugins

By default, WordPress Core files and VIP MU plugins are not exposed in the VS Code interface. If needed, these files can be surfaced for reference in the VS Code Explorer panel.

  1. Enter the VS Code Command Palette by either:
    • Right-clicking anywhere in the Explorer panel and selecting “Add Folder to Workspace…“.
    • Or selecting the key combination ⇧⌘P on the keyboard, then enter the prompt Add folder to workspace.
  2. In the Command Palette field, highlight any existing values and replace them by entering the path value /wp.

Customize the configuration file

The .devcontainer/devcontainer.json file can be modified to customize the available features and settings of a codespace environment. Settings defined in the features section of the file allow customers to optionally enable features such as Elasticsearch, Xdebug, Photon, and MailPit, or specify a version of PHP.

The codespace environment will detect when edits are made to devcontainer.json. Codespaces will generate a prompt in the browser to rebuild the environment with the applied changes.

Note

Do not update the multisite or the multisiteStyle settings after a codespace environment has been created. To modify these settings, delete the existing codespace environment, edit the values in the configuration file, then create a new codespace environment.

Environment variables

Environment variables must be defined in .devcontainer/devcontainer.json; they cannot be managed with VIP-CLI in the codespace environment. Define the name-value pairs of the environment variables within the containerEnv property where it exists in the file.

Do not store passwords, secrets, and other sensitive data in .devcontainer/devcontainer.json. Use encrypted secrets provided by GitHub Codespaces for storing sensitive data.

Visual Studio Code extensions

A default group of VS Code extensions are defined in the customizations section of .devcontainer/devcontainer.json. The list can be modified to add or remove VS Code extensions as it suits the preferences of the developer. Refer to the VS Code Marketplace for available extensions.

Settings Sync is a VS Code feature that allows configurations such as settings, keyboard shortcuts, snippets, extensions, and UI state to be synchronized across machines and instances of VS Code. If Settings Sync is enabled in a user’s VS Code, GitHub Codespaces will attempt to install the same set of extensions in its VS Code interface.

Last updated: January 30, 2024

Relevant to

  • WordPress