Skip to content

Commit c40957b

Browse files
jeanntjeannt
committed
update to package management topics
1 parent 677f354 commit c40957b

9 files changed

Lines changed: 966 additions & 526 deletions

‎docs/advanced-analytics/r/create-a-local-package-repository-using-minicran.md‎

Lines changed: 153 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Create a Local Package Repository Using miniCRAN | Microsoft Docs"
33
ms.custom: ""
4-
ms.date: "03/30/2017"
4+
ms.date: "09/29/2017"
55
ms.prod: "sql-server-2016"
66
ms.reviewer: ""
77
ms.suite: ""
@@ -15,106 +15,185 @@ author: "jeannt"
1515
ms.author: "jeannt"
1616
manager: "jhubbard"
1717
---
18-
# Create a Local Package Repository Using miniCRAN
19-
This topic describes how you can create a local R package repository using the R package **miniCRAN**.
18+
# Create a local package repository Using miniCRAN
2019

21-
Because [!INCLUDE[ssNoVersion_md](../../includes/ssnoversion-md.md)] instances typically are located on a server that does not have Internet connectivity, the standard method of installing R packages (the R command `install.packages()`) might not work, as the package installer cannot access CRAN or any other mirror sites.
20+
There are two ways that you can prepare R packages for installation onto a server without internet access.
2221

23-
There are two options for installing packages from a local share or repository:
22+
- [Use the miniCRAN package to create a single local repository](#bkmk_miniCRAN)
2423

25-
+ Use the miniCRAN package to create a local repository of the packages you need, then install from this repository. This topic describes the miniCRAN method.
24+
The [miniCRAN](https://cran.r-project.org/web/packages/miniCRAN/index.html) creates an internally consistent repository consisting of selected packages from CRAN-like repositories. The user specifies a set of desired packages, and miniCRAN recursively reads the dependency tree for these packages, and downloads only the listed packages and their dependencies.
2625

27-
+ Download the packages you need, and their dependencies, as zip files, and save them in a local folder, and then copy that folder to the [!INCLUDE[ssNoVersion_md](../../includes/ssnoversion-md.md)] computer. For more information on the manual copy method, see [Install Additional Packages on SQL Server](../../advanced-analytics/r-services/install-additional-r-packages-on-sql-server.md).
26+
You can then move this local repository to the server, and proceed to install the packages without using the internet.
2827

28+
- [Manually download and copy packages one by one](#bkmk_manual)
2929

30-
## Step 1. Install miniCRAN and download packages
30+
This article describes how you can create an R package repository using both methods, with particualr emphasis on the **miniCRAN** package.
3131

32+
## Prepare packages using miniCRAN
3233

33-
1. Install the miniCRAN package on a computer that has Internet access.
34+
The goal of creating a local package repository is to provide a single location that a server administrator or other users in the organization can use to install new R packages on a server that does not have internet access.
3435

35-
~~~~
36-
# Install miniCRAN and igraph
36+
The miniCRAN package for R was written by Andre de Vries to make it easier to create a consistent, managed set of R packages for an organization.
3737

38-
if(!require("miniCRAN")) install.packages("miniCRAN")
39-
if(!require("igraph")) install.packages("igraph")
40-
library(miniCRAN)
38+
After creating the repository, you can modify it by adding new packages or upgrading the version of existing packages.
4139

42-
# Define the package source: a CRAN mirror, or an MRAN snapshot
43-
CRAN_mirror <- c(CRAN = "https://mran.microsoft.com/snapshot/2016-04-01")
40+
- For details, see [miniCRAN](https://cran.r-project.org/web/packages/miniCRAN/index.html)
4441

45-
# Define the local download location
46-
local_repo <- "~/miniCRAN"
47-
~~~~
42+
- For a walkthrough of the repository creation process, see [How to install R packages on an off-line SQL Server 2016 instance](http://blog.revolutionanalytics.com/2016/05/minicran-sql-server.html)
4843

49-
2. Download or install the packages you need to this computer usng the following R script. This will create the folder structure that you need to copy the packages to the [!INCLUDE[ssNoVersion_md](../../includes/ssnoversion-md.md)] later.
5044

51-
~~~~
52-
# List the packages to get. Do not specify dependencies.
53-
pkgs_needed <- c("ggplot2", "ggdendro")
54-
# Plot the dependency graph
55-
plot(makeDepGraph(pkgs_needed))
56-
57-
# Create the local repo
58-
pkgs_expanded <- pkgDep(pkgs_needed, repos = CRAN_mirror)
59-
makeRepo(pkgs_expanded, path = local_repo, repos = CRAN_mirror, type = "win.binary", Rversion = "3.2")
45+
There are many advantages to using miniCRAN to create the repository:
6046

61-
# List local packages
62-
pdb <- as.data.frame(
63-
pkgAvail(local_repo, type = "win.binary", Rversion = "3.2"),
64-
stringsAsFactors = FALSE)
65-
head(pdb)
66-
pdb$Package
67-
pdb[, c("Package", "Version", "License")]
68-
~~~~
47+
- **Security**: Many R users are accustomed to downloading and installing new R packages at will, from CRAN or one of its mirror sites. However, for security reasons, production servers running [!INCLUDE[ssNoVersion_md](file:///C:\includes\ssnoversion-md.md)] typically do not have internet connectivity.
6948

49+
- **Easier offline installation**: To install package to an offline server requires that you also download all package dependencies, Using miniCRAN makes it easier to get all dependencies in the correct format.
7050

71-
## Step 2. Copy the miniCRAN repository to the SQL Server computer
51+
- **Improved version management**: In a multiuser environment, there are good reasons to avoid unrestricted installation of multiple package versions on the server.
7252

73-
Copy the miniCRAN repository to the R_SERVICES library on the [!INCLUDE[ssNoVersion_md](../../includes/ssnoversion-md.md)] instance.
53+
### Step 1. Install the miniCRAN package
7454

75-
+ For SQL Server 2016, the default folder is `C:/Program Files/Microsoft SQL Server/MSSQL13.MSSQLSERVER/R_SERVICES/library1`.
76-
+ For SQL Server 2017, the default folder is `C:/Program Files/Microsoft SQL Server/MSSQL14.MSSQLSERVER/R_SERVICES/library1`.
55+
You begin by creating a miniCRAN repository to use as a source. You should create this repository on a computer that has internet access.
7756

78-
If you have installed R Services using a named instance, be sure to include the instance name in the path, to ensure that the libraries are installed to the correct instance. For example, if your named instance is RTEST02, the default path for the named instance would be:
79-
`C:\Program Files\Microsoft SQL Server\MSSQL13.RTEST02\R_SERVICES\library`.
57+
1. Install the miniCRAN package and the required **igraph** package.
8058

81-
If you have installed SQL Server to a different drive, or made any other changes in the installation path, be sure to make those changes as well.
59+
```R
60+
if(!require("miniCRAN")) install.packages("miniCRAN") if(!require("igraph"))
61+
install.packages("igraph") library(miniCRAN)
62+
```
8263

83-
## Step 3. Install the packages on SQL Server using the miniCRAN repository
64+
### Step 2. Define a package source: a CRAN mirror, or an MRAN snapshot
8465

85-
On the [!INCLUDE[ssNoVersion_md](../../includes/ssnoversion-md.md)] computer, open an R command line or RGUI as administrator.
86-
87-
> [!TIP]
88-
> You might have multiple R libraries on the computer; therefore, to ensure that packages are installed to the correct instance, use the copy of RGUI or RTerm that is installed with the specific instance where you want to install the packages.
89-
90-
When prompted to specify a repository, select the folder containing the files you just copied; that is, the local miniCRAN repository.
66+
1. Specify a mirror site to use in getting packages.
9167

92-
~~~~
93-
# Run this R code as administrator on the SQL Server computer
94-
pkgs_needed <- c("ggplot2", "ggdendro")
95-
local_repo <- "~/miniCRAN"
68+
```R
69+
CRAN_mirror \<- c(CRAN = "https://mran.microsoft.com/snapshot/2017-08-01")
70+
```
9671

97-
# OPTIONAL: If you are not running R from the instance library as recommended, you must specify the path
98-
# .libPaths()[1]
99-
# "C:/Program Files/Microsoft SQL Server/MSSQL14.MSSQLSERVER/R_SERVICES/library "
100-
# lib <- .libPaths()[1]
101-
102-
install.packages(pkgs_needed,
103-
repos = file.path("file://", normalizePath(local_repo, winslash = "/")),
104-
lib = lib,
105-
type = "win.binary",
106-
dependencies = TRUE
107-
)
108-
installed.packages()
109-
~~~~
72+
2. Indicate a local folder in which to store the collected packages. You needn't name the folder miniCRAN; it could be a more descriptive name like "GeneticsPackages" or "ClientRPackages1.0.2".
11073
111-
Verify that the packages were installed.
112-
~~~~
113-
installed.packages()
114-
~~~~
74+
Just be sure to create the folder in advance. An error is raised if the `local_repo` folder does not exist when you run the R code later.
11575
76+
```R
77+
local_repo <- "~/miniCRAN"
78+
```
11679
80+
> [!NOTE] The tilde expansion operator returns an environment variable, with results equivalent to `Sys.getenv("R_USER")`.
11781
118-
## Acknowledgements
82+
### Step 3. Add packages to the repository
11983
120-
The source for this information is this article by Andre de Vries, who also developed the miniCRAN package. For details and a complete walkthrough, see [How to install R packages on an off-line SQL Server 2016 instance](http://blog.revolutionanalytics.com/2016/05/minicran-sql-server.html)
84+
1. After miniCRAN is installed, create a list that specifies the additional packages you want to download.
85+
86+
Do not include dependencies; the **igraph** package used by miniCRAN generates the list of dependencies for you. For more information about how to use this graph, see [Using miniCRAN to identify package
87+
dependencies](https://cran.r-project.org/web/packages/miniCRAN/vignettes/miniCRAN-dependency-graph.html).
88+
89+
The following R script demonstrates how to get the target packages, "zoo"
90+
and "forecast".
91+
92+
```R
93+
pkgs_needed <- c("zoo", "forecast")
94+
95+
2. Optionally, plot the dependency graph, which can be informative and looks cool.
96+
97+
```R
98+
plot(makeDepGraph(pkgs_needed))
99+
```
100+
101+
3. Create the local repo. Be sure to change the R version if necessary
102+
103+
```R
104+
pkgs_expanded <- pkgDep(pkgs_needed, repos = CRAN_mirror)
105+
makeRepo(pkgs_expanded, path = local_repo, repos = CRAN_mirror, type = "win.binary", Rversion = "3.3")
106+
```
107+
108+
From this information, the miniCRAN package creates the folder structure that you need to copy the packages to the [!INCLUDE[ssNoVersion_md](file:///C:\includes\ssnoversion-md.md)] later.
109+
110+
4. At this point you should have a folder containing the packages you needed, and any additional packages that were required.
111+
112+
You can run the following code to list the packages contained in the miniCRAN repository.
113+
114+
```R
115+
pdb <- as.data.frame(pkgAvail(local_repo, type = "win.binary", Rversion = "3.3"), stringsAsFactors = FALSE)
116+
head(pdb)
117+
pdb$Package
118+
pdb[, c("Package", "Version", "License")]
119+
```
120+
121+
### Step 4. Use the repository to add R packages to the instance library
122+
123+
After you have created the repository and added the packages you need, you must move the package repository to the server computer, and ensure that the R packages are installed in the correct library for use from SQL Server.
124+
125+
Depending on the version of SQL Server, there are two options for adding new packages to the R library associated with the SQL Server instance:
126+
127+
- Install to the instance library using the miniCRAN repository and R tools.
128+
129+
- Upload packages to a SQL database and install packages on a per-database basis, using the CREATE EXTERNAL LIBRARY statement. See [Install additional R packages on SQL Server](install-additional-r-packages-on-sql-server.md).
130+
131+
The following procedure describes how to install the packages using R tools.
132+
133+
1. Copy the folder containing the miniCRAN repository, in its entirety, to the server where you will install the packages.
134+
135+
2. Open an R command prompt using the R tool associated with the instance.
136+
137+
- For SQL Server 2017, the default folder is `C:/Program Files/Microsoft SQL Server/MSSQL14.MSSQLSERVER/R_SERVICES/library`.
138+
139+
- For SQL Server 2016, the default folder is `C:/Program Files/Microsoft SQL Server/MSSQL13.MSSQLSERVER/R_SERVICES/library`.
140+
141+
- For a named instance, the default path would be something like: `<instance_path>.RTEST/R_SERVICES/library`.
142+
143+
- If you have installed SQL Server to a different drive, or made any other changes in the installation path, be sure to make those changes as well.
144+
145+
3. Get the path for the instance library (in case you're in a user directory), and add it to the list of library paths.
146+
147+
```R
148+
.libPaths()[1]
149+
lib \<- .libPaths()[1]
150+
```
151+
152+
This should return the instance path, "C:/Program Files/Microsoft SQL Server/MSSQL14.MSSQLSERVER/R_SERVICES/library "
153+
154+
2. Specify the location on the server where you copied the mininCRAN repository in `server_repo`.
155+
156+
In this example, we assume that you copied the repository to your user folder on the server.
157+
158+
```R
159+
R server_repo <- "C:\\Users\\MyUserName\\miniCRAN"
160+
```
161+
162+
3. Since you are working in a new R workspace on the server, you must also furnish the list of packages to install.
163+
164+
```R
165+
tspackages <- c("zoo", "forecast")
166+
```
167+
168+
4. Install the packages, using the path to the local copy of the miniCRAN repo.
169+
170+
```R
171+
install.packages(tspackages, repos = file.path("file://", normalizePath(server_repo, winslash = "/")), lib = lib, type = "win.binary", dependencies = TRUE)
172+
```
173+
174+
5. Now view the installed packages.
175+
176+
```R
177+
installed.packages()
178+
```
179+
180+
[!NOTE]
181+
> In SQL Server 2017, additional database roles and T-SQL statements are provided to help server administrators manage permissions over packages. The database administrator can own the task of installing packages, using either R or T-SQL, if so desired.
182+
>
183+
> However, the DBA can also use roles to give users the ability to install their own packages. For more information, see [R package management for SQL Server](r-package-management-for-sql-server-r-services.md).
184+
>
185+
> In SQL Server 2016, a server administrator must install packages from the miniCRAN repository into the default library used by the instance. To do this, use the R tools as described in the [preceding section](#bkmk_Rtools).
186+
187+
## Manually download single packages
188+
189+
If you do not want to use miniCRAN, you can also manually download the packages you need, and their dependencies. To do this requires that you are either an administrator or sole owner of a server.
190+
191+
After downloading the packages, you install the R packages from the zipped file location.
192+
193+
1. Download the packages zip files, and save them in a local folder
194+
195+
2. Copy that folder to the [!INCLUDE[ssNoVersion_md](file:///C:\includes\ssnoversion-md.md)] computer.
196+
197+
3. Install the packages into the SQL Server instance library.
198+
199+
- You can use R to install for the instance as a whole. Or, use the SQL Server CREATE EXTERNAL LIBRARY statement to install the package into a database and share the package with users. See [Install additional R packages in SQL Server](install-additional-r-packages-on-sql-server.md)

0 commit comments

Comments
 (0)