myWebLog
Advanced Usage

Backup and Restore

myWebLog provides blog-level backup and restore via its command-line interface (CLI).

Backup

The backup command extracts the web log, its settings, its contents, and its theme, creating a JSON archive file. The structure of the backup command is:

.\myWebLog[.exe] backup [url-base] [*output-file] [*"pretty"]

Here, url-base is the URL base for the web log being backed up (and may need to be enclosed in quotes). *output-file is optional; if it is present, it specifies the (path and) name of the file to be written (.json will be appended if it does not already end with that). If the parameter is excluded, the output file name will be the slug of the web log with a .json extension. Finally, the default output produces the most compact JSON possible, but is not very human-readable; passing the optional pretty at the end will format the JSON to be more readable. The restore process can interpret either one, so choosing either format is purely up to the user.

(For this reason, you cannot set the slug of your web log to pretty.)

Restore

The restore command does the inverse of the backup command; it loads a web log, its settings and contents, and its theme into the existing database. Its format is:

.\myWebLog[.exe] restore|do-restore [backup-file] [optional-url-base]

backup-file is the (path and) name of the .json file that contains the backup being restored. optional-url-base is the URL base for the restored blog; using this value, a backup can be restored to a different site. This can be handy if, for example, you want to restore the contents of a public blog on a local copy, so you can work with the theme without affecting the live site.

Restoring can be a destructive process. If there is a web log with the destination URL base, the process will delete that data and restore what is in the backup archive. Additionally, the theme from the archive will be imported, possibly overwriting a theme with the same name. Generally, this is what you want to happen; however, if you think you may overwrite something you will want, it might be prudent to do a backup of the destination before restoring to it. If myWebLog detects that it will be deleting data, it will ask you to confirm this; however, using do-restore instead of restore will bypass this prompt, and is more suitable for scripts.

Configuration

Creating an appsettings.Production.json file is the safest way to customize the configuration for your instance of myWebLog. The project will not ship that file, and values in that file override the same settings that may appear in appsettings.json. When upgrading versions, ensure that this file is preserved, and your customizations should remain.

HTTP Ports

As myWebLog is a ASP.NET Core application, it uses Kestrel as its web server. It can be set up to serve directly on ports 80 and 443, or it can be configured behind a reverse proxy (such as nginx, IIS, or Apache). The default ports are 5000 (HTTP) and 5001 (HTTPS) on localhost, but can be configured via JSON. The following JSON makes Kestrel listen on localhost port 3000 (HTTP):

"Kestrel": {
  "EndPoints": {
    "Http": {
      "Url": "http://localhost:3000"
    }
  }
}

There are plenty of other options that can be configured this way as well.

Logging Levels

If the logging for myWebLog is too chatty, you can tweak log levels to hide things you may not care to see. As an example, log messages from MyWebLog.Handlers.* are generated from the route handlers themselves; these can be controlled at any level that ends with the . character. So, to say that you only want to see warnings and above from any myWebLog handler, this would be the JSON to use:

"Logging": {
  "LogLevel": {
    "MyWebLog.Handlers": "Warning"
  }
}

Following that pattern, you can specify additional levels to silence other log notices that may be extraneous.

Canonical Domains

myWebLog now incorporates canonical domain middleware which can redirect a site that listens on multiple domains to the preferred one. This can be used to enforce www. (or the lack thereof) from within myWebLog. It can be a useful tool in scenarios where you may not have access to the web server configuration to set it up there.

Speaking of things that would usually require changing the web server config….

Redirect Rules

Web servers like Apache, nginx, and IIS have the concept of “rewrite” rules; they can rewrite or redirect a request, allowing moved pages to be redirected automatically, or allowing the exposed URL structure to be different from the underlying files on disk. Placing these rules in the web server's configuration is great; they are all tuned to execute them very efficiently. However, what if you do not have access to update that configuration?

This is the motivation behind myWebLog's redirect rules. Since its original release, pages and posts have supported “prior permalinks” - if the page or post's URL used to be something different, myWebLog will return a permanent redirect to the current URL. Arbitrary URLs, though, are now supported from v2.1 forward. Let's walk through an example of how these might be implemented.

This author has had a personal website online continually since 2003. Over the years, this site has served as a test site for various hosting technologies, including WordPress and BlogEngine.NET. The original WordPress install used a category URL format of /categories/[cat]/[subcat]. BlogEngine.NET supported subcategories, but their URLs were flat - /category/CatOrSubCat.aspx. A later WordPress install, and myWebLog, both use /category/[cat]/[subcat]. Using redirect rules, we can make sure that any incoming links go to the current pages. We'll do this without regular expressions (for now).

There are few things to highlight here:

• Rules are matched in the order they appear. Non-RegEx rules are matched in their entirety, so a URL like /categories/general/other would not be matched by any of these rules.
• There is no leading slash on the “From” column, but there is on the “To” column.
• If the web log is not based on the domain root, any additional path will need to be specified here; these rules are the one place that does not use the web log's configuration to create URLs.

Even with all these caveats - these rules will not work the way they need to. The WordPress implementation also had a trailing slash, and those links would not match these. Also, while BlogEngine.NET showed subsequent category pages by using a ?page=# query string (which would not be affected), WordPress adds /page/# to the end of the URL. We need something that does not do an exact match; this is where regular expressions can help us. For our purposes, we'll redirect these links to page one of each category.

A few more notes:

• Regular expression matches should generally appear from most specific to least specific. The second rule above would match /categories/general/site-info, and if it appears above the first one, it would be selected first.
• Using ^ to indicate the start of the “From” URL is usually what you will want; otherwise, it will match anywhere within a URL. A “From” that just matched categories would redirect a page URL such as personalities-and-their-many-categories.html.
• Finally, the “To” does not have to be a site-relative URL. If there used to be a subdirectory named /blog that is now hosted at https://blog.example.com, that URL can be specified.

While its execution may not be quite as efficient as storing these rules in the web server's configuration, adding redirect rules within a web log instance allows you to specify rules when you may not otherwise be able. It also keeps these old/new URLs as part of your web log configuration.

Cache Management

myWebLog make judicious use of a few caches to speed up the most common scenarios it encounters, and to provide a rich set of template variables available for every page. As items within these caches are updated via the application, it keeps them all in sync. However, if you run commands via the CLI that change cached data, or make changes directly in the database, the current caches can be refreshed without requiring you to restart the application. This requires an Administrator access level, and is located on the “Admin” page below the list of themes.

The first set of caches deals with web logs. Each web log's identifying information and RSS feed settings are cached, as are its page list (without the text of the pages) and its categories. Within the “Web Logs” section, you can choose “Refresh All” (which will also pick up new web logs which may have been added), or you can choose to refresh a specific web log. This will reload the web log, page, and category information from the database.

The second set of caches deals with themes and theme assets. A theme's templates are cached as they are required, and their assets are catalogued in a cache (without the actual data of that asset). Under the “Themes” section, there is a “Refresh All” option that will empty the template cache and reindex the assets for all themes; as with the web logs, this will also pick up new themes that may have been loaded via the CLI. Each theme can be refreshed individually as well.

« myWebLog Home View Source Repo