connectlocal_
ConnectLocal/Docs/Connect to Bluehost

THE CONNECTION MANUAL

Connect to Bluehost

Connect Bluehost to Local, push and pull your site, and sync selected files.

On this page

Install the Bluehost add-on using the installation guide, then follow the setup below.

Requirements

  • Local 6 or newer. Developed against Local 10.1.2 on macOS.
  • Shared hosting: SSH turned on for the account. In the Bluehost Portal, open Hosting → My Plans → SSH Management and turn on Shell Access (Bluehost's guide). The server IP and SSH username are listed there under SSH Details; the port is 22.
  • Bluehost Cloud: an SSH user for the site. In the Bluehost Portal, open Websites → Manage Site → SSH/SFTP → Add SSH User and turn on SSH Key (Bluehost's guide).
  • rsync and PHP on the server. WP-CLI is used if it is installed; if it isn't, the add-on installs its own copy.

Use

  1. Open a site in Local and go to Tools → Bluehost.
  2. Connect in one of two ways:
    • Shared hosting: enter the IP and username from SSH Details, and either your password or the add-on's public key.
      • With a password and Add Local's SSH key to the account ticked (the default), the add-on adds its key to ~/.ssh/authorized_keys. That is what cPanel's "Authorize" button does. Once a key login works, the password is discarded.
      • With the key option, click Add SSH Key under Manage SSH Keys on the SSH Management page and paste the shown public key first. On the account tested, a key added there works immediately.
      • The add-on then lists every WordPress site in the account (main domain first). Pick one and click Link.
    • Bluehost Cloud / SSH: the host defaults to ssh.atomicsites.net. Enter the site's SSH username (a Global SSH User looks like globaluser-12345678) and paste the shown public key into the Add SSH User form. This tab also works for any other SSH login; set the remote path if WordPress isn't found automatically.
  3. Push or pull from the panel's Push to Bluehost / Pull from Bluehost tabs. Once the site is linked, you can also use the Bluehost: Pull / Push buttons in the site header.
    • Push options: Files and/or Database; delete files on Bluehost that aren't in Local (on by default, like WP Engine); purge Bluehost caches afterwards.
    • Every pull moves the Local files it replaces or deletes into app/bluehost-backups/pull-<time>/ instead of discarding them; the last 3 are kept. If you pull by mistake, copy them back from there.
    • Pull options: Files and/or Database; back up the Local database first; delete Local files that aren't on Bluehost (on by default).

Progress appears in Local's site overlay. When the transfer finishes, a banner reports success or the error.

Pull a Bluehost site into a new Local site

  1. Click + (Create a site) in Local and choose Pull from Bluehost.
  2. Pick the site from your connected account, or enter Cloud/SSH details. Name the Local site; it defaults to the site's domain.
  3. Click Create site & pull. The connection is checked first, so a wrong login never leaves an empty site behind.

Compare & sync files (selective sync)

Go to Tools → Bluehost → Compare & sync files and click Compare with Bluehost. Nothing changes until you choose files. Differing files are listed under Different on each side, Only in Local and Only on Bluehost. Tick files, then click Push selected or Pull selected. A ticked file that exists only on the receiving side is deleted there. The database is never touched.

Sites inside other sites (addon domains)

On cPanel, addon domains and subdomains are often served from folders inside the main site's public_html, for example ~/public_html/shop.example.org. Each time it connects, the add-on finds these by looking for other WordPress installs and for cPanel docroots inside the linked site's folder. It excludes them from every transfer and comparison. A push with "delete files on Bluehost" can therefore never remove another site, and a pull never downloads one. The linked site's panel lists them under Never synced.

What a database push does

  1. Exports the Local database and rewrites MySQL 8 utf8mb4_0900_* collations to ones MariaDB and older MySQL accept.
  2. On Bluehost, saves the current database to local-backup-before-push.sql in a private ~/.bluehost-connect folder. The folder is outside public_html and readable only by your account. The add-on also reads the current home URL and table_prefix.
  3. Uploads the dump to that folder, then runs wp db reset and wp db import. If the import fails, it restores the backup automatically. The uploaded dump is always deleted afterwards.
  4. Sets table_prefix to match Local if the two differ.
  5. Runs wp search-replace across all tables (--precise, guid skipped) from //site.local to the Bluehost URL, including the JSON-escaped form, plus http:// → https:// when the Bluehost site uses HTTPS.

What a database pull does

  1. On Bluehost, exports the database with --single-transaction (the live site isn't locked), downloads it and deletes the export.
  2. Makes the dump importable by Local's MySQL. It removes the MariaDB "sandbox mode" line and rewrites uca1400 collations.
  3. Saves the Local database to app/sql/local-backup-before-pull.sql (optional).
  4. Imports through Local's own WP-CLI service. If the import fails, it restores the backup.
  5. Matches Local's table_prefix to Bluehost's, then replaces the Bluehost URL, and any other domain served from the same folder, with the Local URL.

What is never transferred

These paths are excluded in both directions, and excluded paths are also protected from --delete:

  • Environment config: wp-config.php, .htaccess, .user.ini, php.ini, and the copies Bluehost keeps beside them (wp-config.php.bak, which contains the database password, and .htaccess.nfd-backup), plus wp-cli.yml and nfd-private/
  • cPanel files: cgi-bin/, .well-known/ (AutoSSL validation), error_log files, .ftpquota
  • Caches and host drop-ins: object-cache.php, advanced-cache.php, wp-content/cache/, wp-content/newfold-page-cache/, wp-content/endurance-page-cache/, mu-plugins/endurance-*, Bluehost's mu-plugins/sso.php, WP Cloud's wpcomsh loader
  • Server-specific state: wp-content/jetpack-waf/ (firewall rules with absolute server paths) and wp-content/upgrade/
  • Other sites nested inside the linked site's folder (see above)
  • VCS and tool binaries, root-level *.sql dumps, Local's helper files

Must-use plugins that exist only on the receiving side are never deleted. Bluehost installs its own there.

Bluehost Cloud: platform-managed core and plugins

WP Cloud doesn't keep WordPress core in the site folder: /srv/htdocs/__wp__ links to a shared core, and some plugins, themes and drop-ins link to a shared store (/wordpress/plugins/...). Each time it connects, the add-on finds links that resolve outside the site and treats them as platform-managed:

  • WordPress core (__wp__, wp-admin/, wp-includes/, root wp-*.php and index.php) is excluded in both directions. Local keeps its own core and the server keeps its shared one. After a database pull, a banner warns if the two WordPress versions differ.
  • Managed plugins and themes come down to Local as real files on a pull. A push never replaces them, so the platform keeps updating them.
  • A database pull first checks that the Local site still has WordPress core. If it doesn't, the pull stops before changing the database.

Themes and plugins symlinked from elsewhere

A theme or plugin that you develop in another folder and symlink into the Local site (for example wp-content/themes/mytheme → ~/code/mytheme) is pushed as real files, because the server has no such folder to point to. It is never pulled into: a pull leaves the symlink and the folder it points to untouched, so server copies can't overwrite or delete your working files. Symlinks within the site stay symlinks, and broken symlinks are skipped (and logged).

To skip more, add rsync patterns (one per line) to app/public/.bluehost-push-ignore or .bluehost-pull-ignore. These work like .wpe-push-ignore and .wpe-pull-ignore.

← Back to documentationDownload an add-on ↗